> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vers.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Execute

# vers execute

Execute a command within the Vers environment on the specified VM.

<Warning>
  **Commands must be wrapped in quotes!** Use `vers execute "command"` not `vers execute command`
</Warning>

## Usage

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers execute ""               # Run on current HEAD VM
vers execute [vm-id|alias] "" # Run on specific VM
```

## Options

| Option   | Description                                           |
| -------- | ----------------------------------------------------- |
| `--host` | Specify the host IP to connect to (overrides default) |

## Examples

### Execute on HEAD VM

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers execute "ls -la"
vers execute "python app.py"
vers execute "systemctl status nginx"
```

### Execute on specific VM

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers execute vm-abc123 "ps aux"
vers execute my-alias "tail -f /var/log/app.log"
```

### Commands with pipes and redirections

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Always use quotes for complex commands
vers execute "ps aux | grep python"
vers execute "find /app -name '*.py' | wc -l"
vers execute "echo 'Hello World' > /tmp/test.txt"
vers execute "grep -r 'error' /var/log/ | head -10"
```

### Development and testing

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers execute "npm test"
vers execute "python -m pytest tests/"
vers execute "curl -f http://localhost:3000/health"
vers execute "df -h"
```

## How it works

The `execute` command provides a way to run single commands on VMs without opening an interactive SSH session:

1. **VM detection**: If no VM is specified, uses the current HEAD VM
2. **SSH connection**: Establishes a secure connection using managed SSH keys
3. **Command execution**: Runs the command as root inside the VM
4. **Output streaming**: Returns stdout/stderr directly to your terminal
5. **Exit code preservation**: Maintains the original command's exit status

## Argument handling

The command intelligently handles VM identification:

* **One argument**: Treats as command, runs on HEAD VM
* **Two+ arguments**: First argument attempted as VM identifier
  * If valid VM: runs command on that VM
  * If invalid VM: treats all arguments as command, runs on HEAD VM

## Prerequisites

* VM must be in "Running" state
* VM must have SSH port configured
* Valid authentication (handled automatically)

## Common Patterns

### Run a script on boot

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
VM=$(vers run --wait --format json | jq -r .root_vm_id)
vers execute "$VM" -- bash -c "apt-get update && apt-get install -y jq"
```

### Pipe stdin into a remote command

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
echo 'print("hello from local")' | vers execute my-vm -i -- python3
```

### Fan-out across a fleet

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
for vm in $(vers status -q); do
  vers execute "$vm" -- uptime &
done
wait
```

### Healthcheck

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
if vers execute my-vm -- curl -sf http://localhost:3000/health >/dev/null; then
  echo "healthy"
else
  echo "unhealthy"
fi
```

## See Also

* [vers connect](/cli-reference/connect) - Open interactive SSH session
* [vers copy](/cli-reference/copy) - Transfer files to/from VMs
* [vers status](/cli-reference/status) - Check VM state