> ## 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.

# Copy

# vers copy

Copy files between your local machine and a Vers VM using SCP.

## Usage

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers copy [vm-id|alias]  
vers copy    # Uses HEAD VM
```

## Options

| Option            | Description                                     |
| ----------------- | ----------------------------------------------- |
| `-r, --recursive` | Recursively copy directories and their contents |

## Examples

### Upload a file to a VM

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers copy vm-123 ./local-file.txt /remote/path/
```

### Download a file from a VM

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers copy vm-123 /remote/path/file.txt ./local-file.txt
```

### Use HEAD VM for file transfer

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Upload using current HEAD VM
vers copy ./local-file.txt /remote/path/

# Download using current HEAD VM  
vers copy /remote/path/file.txt ./local-file.txt
```

### Copy directories recursively

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Upload entire directory
vers copy -r ./local-directory/ /remote/path/

# Download entire directory
vers copy -r /remote/path/directory/ ./local-directory/
```

## How it works

The `copy` command automatically handles the complexities of file transfer:

1. **VM validation**: Ensures the target VM is running and has SSH access
2. **SSH key management**: Creates or retrieves the appropriate SSH key for the VM
3. **Network routing**: Determines the correct connection method (direct IP or through cluster node)
4. **Transfer direction**: Auto-detects whether you're uploading or downloading based on path patterns

### Path detection

* **Local paths**: Don't start with `/` or exist on your local filesystem
* **Remote paths**: Start with `/` (absolute paths on the VM)
* **Auto-detection**: If a local file exists, the command assumes upload; otherwise, it assumes download

## Prerequisites

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

## Common Patterns

### Upload a project tree

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers copy -r ./my-app /srv/app
```

### Pull remote logs for local inspection

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers copy my-vm /var/log/app.log ./debug/
```

### Same file to N branches

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
for i in $(seq 1 5); do
  vers copy "worker-$i" ./config.json /etc/app/config.json
done
```

### Deploy a new binary to HEAD

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers copy ./dist/server /opt/app/server
vers execute -- systemctl restart app
```

## See Also

* [vers connect](/cli-reference/connect) - SSH into a VM interactively
* [vers execute](/cli-reference/execute) - Run commands on a VM
* [vers status](/cli-reference/status) - Check VM state