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

# CLI reference

> Install the vms command line tool, sign in with your browser or an API key, and use each command: new, ls, ssh, exec, cp, stop, resume, rm, url, fork, template, snapshot, and desktop.

`vms` creates and uses sandboxes from your terminal. It is one file with no dependencies, for macOS on Apple silicon, macOS on Intel, and Linux on x86-64.

## Install

### With Homebrew

On macOS or Linux:

```bash theme={null}
brew install vms-dev-org/tap/vms
vms --version
```

To get a new version, run `brew upgrade vms`.

### Download the file

Download the file for your computer from the [latest release](https://github.com/vms-dev-org/cli/releases/latest), with `SHA256SUMS`:

| Computer | File |
| - | - |
| macOS, Apple silicon | `vms-darwin-arm64` |
| macOS, Intel | `vms-darwin-x64` |
| Linux, x86-64 | `vms-linux-x64` |

Check the file. Then rename it to `vms`, make it executable, and move it to a folder in your `PATH`:

```bash theme={null}
shasum -a 256 -c SHA256SUMS --ignore-missing
mv vms-darwin-arm64 vms
chmod +x vms
sudo mv vms /usr/local/bin/
vms --version
```

The macOS files are not notarized. If you download the file with a browser, remove the quarantine attribute before you run it. If you do not, macOS can refuse to open it:

```bash theme={null}
xattr -d com.apple.quarantine /usr/local/bin/vms
```

`vms ssh` needs OpenSSH. `vms cp -r` from a sandbox needs `tar`. macOS and most Linux systems have both.

## Sign in

### With your browser

```bash theme={null}
vms login
```

1. The CLI shows a code and a link, and opens the link in your browser.
2. Sign in, if you are not signed in.
3. Check that the page shows the same code as your terminal. Choose **Approve**.

The CLI then makes an API key for one workspace and saves it. If you are a member of more than one workspace, give the workspace:

```bash theme={null}
vms login --workspace acme
```

* You need the **Owner** or **Admin** role in the workspace. A member can sign in with an API key from an owner or an admin.
* The key has the scopes `workspace:read`, `sandboxes:read`, `sandboxes:write`, `sandboxes:exec`, `sandboxes:files`, `sandboxes:ssh`, `sandboxes:desktop`, `snapshots:read`, `templates:read`, and `templates:write`. It gets only the scopes that your role permits. It expires after 90 days.
* The key has the name `vms CLI on <computer name>`. You can see it and revoke it in **Settings**, then **API keys**. See [API keys](https://vms.dev/docs/workspace/api-keys.md).
* The code expires after 10 minutes. On a computer without a browser, open the link on a different computer.
* The CLI saves the key in `~/.config/vms/config.json`, which only your user can read. It does not save your password or your sign-in session.

### With an API key

Send the key on stdin, so that it does not go into your shell history:

```bash theme={null}
vms login --with-api-key < key.txt
```

Or set `VMS_API_KEY`. Each command uses it before the saved key:

```bash theme={null}
export VMS_API_KEY="<your-api-key>"
vms ls
```

The key needs the scopes of the commands that you use. See [Scopes for each command](#scopes-for-each-command).

### Sign out

```bash theme={null}
vms logout
```

`vms logout` revokes the key that `vms login` made with the browser, and removes the saved key. It does not revoke a key that you gave with `--with-api-key` or `VMS_API_KEY`.

## Commands

Give a sandbox by its name or by its ID, such as `agent-42` or `sbx_06d8k3m7q2v9x4b1n5c0e8f2ja`. Run `vms <command> --help` to see the options of a command.

### new

```bash theme={null}
vms new agent-42 --size medium --label team=search --stop-after 2h
```

Creates a sandbox and waits until it is `running`. It writes the sandbox ID to stdout.

| Option | Value |
| - | - |
| `--size <size>` | `small`, `medium`, `large`, or `xlarge`. The default is `small`. |
| `--template <template>` | Start with the files of a template: its name, its ID, or a share code. See [Save a sandbox as a template](https://vms.dev/docs/sandboxes/templates.md). |
| `--label <key=value>` | A label. Give the option again for more labels. |
| `--stop-after <time>` | The auto-stop time, such as `30m`, `2h`, or `3600`. Use `never` for no auto-stop. See [Stop sandboxes automatically](https://vms.dev/docs/sandboxes/auto-stop.md). |
| `--no-wait` | Do not wait until the sandbox is `running`. |
| `--json` | Write the sandbox as JSON. |

### ls

```bash theme={null}
vms ls --state running --label team=search
```

Lists the sandboxes of the workspace, with the ID, the name, the state, the size, and the creation time.

| Option | Value |
| - | - |
| `--state <state>` | Only sandboxes in this state. Give the option again for more states. |
| `--label <key=value>` | Only sandboxes with this label. |
| `--name-prefix <text>` | Only sandboxes with a name that starts with this text. |
| `--json` | Write the sandboxes as JSON. |

### ssh

```bash theme={null}
vms ssh agent-42
vms ssh agent-42 -- npm test
```

Opens a shell in the sandbox, or runs one command, through `ssh.vms.dev`.

* It adds the host key of `ssh.vms.dev` to `~/.ssh/known_hosts`, so that `ssh` does not ask you to trust the host. After that, `ssh agent-42@ssh.vms.dev` also connects with no question.
* It adds your public key to the sandbox. The key is `~/.ssh/id_ed25519`. If you do not have this key, the CLI makes a key in `~/.config/vms/ssh/`.
* Use `-i <file>` to use a different private key.
* If your computer cannot reach `ssh.vms.dev`, it stops with `Could not connect to ssh.vms.dev. Check your network.` It says `The sandbox did not accept the SSH key` only when the sandbox refuses the key.

See [Connect to a sandbox with SSH](https://vms.dev/docs/sandboxes/ssh.md).

### exec

```bash theme={null}
vms exec agent-42 -- ls -la /home/user
vms exec agent-42 'npm install && npm test'
echo "input" | vms exec agent-42 -- cat
```

Runs a command and streams its stdout and stderr. The CLI exits with the exit code of the command.

* Put `--` before the command, so that the options of the command do not go to the CLI.
* One argument runs in a shell, so you can use `&&` and pipes. More arguments run the program with no shell.
* When stdin is not a terminal, the CLI sends it to the command.

| Option | Value |
| - | - |
| `--cwd <folder>` | The working folder. |
| `-e`, `--env <KEY=value>` | An environment variable. Give the option again for more variables. |
| `--timeout <seconds>` | Stop the command after this time. The CLI then exits with `124`. |

See [Run commands in a sandbox](https://vms.dev/docs/sandboxes/run-commands.md).

### cp

```bash theme={null}
vms cp report.txt agent-42:/home/user/
vms cp agent-42:/home/user/out.json ./out.json
vms cp -r ./app agent-42:/home/user/app
vms cp -r agent-42:/home/user/app ./app
```

Copies files between your computer and a sandbox. Write a sandbox path as `<sandbox>:<absolute path>`. One of the two paths must be in a sandbox.

* A target that ends with `/` is a folder. The file keeps its name in it.
* `-r` copies the content of a folder into the target folder. To copy into the sandbox, the CLI sends the files in one tar upload. To copy out of the sandbox, it runs `tar` in the sandbox.
* A copy into the sandbox keeps the file mode, such as `0755`.

See [Read and write files](https://vms.dev/docs/sandboxes/files.md).

### stop

```bash theme={null}
vms stop agent-42
```

Stops each sandbox that you give, and waits until it is `stopped`. Use `--no-wait` to return at once. See [Stop and resume a sandbox](https://vms.dev/docs/sandboxes/stop-and-resume.md).

### resume

```bash theme={null}
vms resume agent-42 --size large
```

Starts each sandbox that you give, and waits until it is `running`. Use `--size` to change the size. Use `--no-wait` to return at once.

### rm

```bash theme={null}
vms rm agent-42
```

Deletes each sandbox that you give, with its files. You cannot undo this.

### url

```bash theme={null}
vms url agent-42 3000
vms url agent-42 3000 --public
```

Gives a port of the sandbox an HTTPS URL, and writes the URL to stdout. If the port has a URL, the CLI writes that URL. A URL that is not public has its token in `?_token=`.

| Option | Value |
| - | - |
| `--public` | Open the URL to everyone. |
| `--private` | Make the URL need its token again. |
| `--json` | Write the URL as JSON, with its token. |

See [Open a port of a sandbox on a public URL](https://vms.dev/docs/sandboxes/urls.md).

### fork

```bash theme={null}
vms fork agent-42 agent-43
vms fork agent-42 --count 10
```

Makes new sandboxes with the files and the environment variables of a `running` or `stopped` sandbox, and waits until each fork is `running`. It writes the ID of each fork to stdout, one on each line. A fork of a running sandbox gets the files of a new snapshot.

| Option | Value |
| - | - |
| `<name>`, `--name <name>` | The name of the fork. Do not give a name with a count of more than 1. |
| `--count <number>` | The number of forks, from 1 to 100. If one fork cannot start, you get no fork. |
| `--size <size>` | `small`, `medium`, `large`, or `xlarge`. The default is the size of the source sandbox. |
| `--label <key=value>` | A label. Give the option again for more labels. |
| `--stop-after <time>` | The auto-stop time of each fork, such as `30m`. Use `never` for no auto-stop. |
| `--no-fresh-snapshot` | Use the last snapshot of a running sandbox. Do not take a new one. |
| `--no-wait` | Do not wait until each fork is `running`. |
| `--json` | Write the forks as JSON. |

See [Fork a sandbox](https://vms.dev/docs/sandboxes/fork.md).

### template

```bash theme={null}
vms template save agent-42 node-base
vms template ls
vms new --template node-base
vms template rm node-base
```

| Command | What it does |
| - | - |
| `vms template save <sandbox> <name>` | Saves the files of a `running` or `stopped` sandbox as a template, and waits until it is `ready`. It writes the template ID to stdout. Use `--no-wait` to return at once, and `--json` to write the template as JSON. |
| `vms template ls` | Lists the templates of the workspace, with the ID, the name, the status, the size, and the creation time. Use `--json` to write them as JSON. |
| `vms template rm <template>...` | Deletes each template that you give, by its name or its ID, with its saved files. Sandboxes from the template do not change. You cannot undo this. |

See [Save a sandbox as a template](https://vms.dev/docs/sandboxes/templates.md).

### snapshot

```bash theme={null}
vms snapshot ls agent-42
vms snapshot ls agent-42 /home/user
vms snapshot get agent-42 /home/user/notes.md
vms snapshot get snp_06d8k3m7q2v9x4b1n5c0e8f2ja /home/user/project -o project.tar
vms snapshot get agent-42 -o agent-42.tar
```

Give a snapshot by its ID, or give a sandbox to use its latest snapshot. The sandbox can be stopped or deleted.

| Command | What it does |
| - | - |
| `vms snapshot ls <sandbox>` | Lists the snapshots of a sandbox, newest first, with the ID, the generation, the number of changed paths, and the time. It shows 20 snapshots. Use `--limit <number>` for up to 100. |
| `vms snapshot ls <snapshot> [<folder>]` | Lists the files in a folder of a snapshot, with the type, the size, and the time of the last change. The default folder is `/`. With a sandbox and a folder, it uses the latest snapshot. |
| `vms snapshot get <snapshot> <path>` | Writes a file of the snapshot to stdout. A folder comes as a tar. |
| `vms snapshot get <snapshot>` | Writes the whole snapshot as a tar. |

Use `-o <file>` to write to a file. The CLI does not write a tar to a terminal. Use `--json` with `ls` to write the list as JSON.

See [Read the files of a snapshot](https://vms.dev/docs/sandboxes/snapshot-files.md).

### desktop

```bash theme={null}
vms desktop agent-42
vms desktop agent-42 --mode browser
```

Opens the desktop of a `running` sandbox in your default browser. The link stops working 10 minutes after the CLI makes it, if nobody opens it. When no browser opens, the CLI writes the link to stdout.

| Option | Value |
| - | - |
| `--mode <mode>` | `desktop` shows the whole desktop. `browser` shows only the Chrome window. The default is `desktop`. |
| `--no-open` | Do not open a browser. Write the link to stdout. |
| `--json` | Write the desktop session as JSON. |

See [See the desktop of a sandbox](https://vms.dev/docs/sandboxes/desktop.md).

## Scopes for each command

| Command | Scopes |
| - | - |
| `ls` | `sandboxes:read` |
| `new`, `stop`, `resume`, `rm`, `url`, `fork` | `sandboxes:read`, `sandboxes:write` |
| `exec`, `cp -r` from a sandbox | `sandboxes:read`, `sandboxes:exec` |
| `cp` | `sandboxes:read`, `sandboxes:files` |
| `ssh` | `sandboxes:read`, `sandboxes:ssh` |
| `template save` | `sandboxes:read`, `templates:write`, `snapshots:read` |
| `template rm` | `templates:write` |
| `template ls` | `templates:read` |
| `snapshot ls` | `sandboxes:read`, and `snapshots:read` to list the files of a snapshot |
| `snapshot get` | `snapshots:read`, and `sandboxes:read` to use a sandbox |
| `desktop` | `sandboxes:read`, `sandboxes:desktop` |

## Environment variables

| Variable | Value |
| - | - |
| `VMS_API_KEY` | The API key. Each command uses it before the saved key. |
| `VMS_API_URL` | The base URL of the API. The default is `https://vms.dev/api`. |
| `XDG_CONFIG_HOME` | The folder of the saved key. The default is `~/.config`. |
| `VMS_NO_BROWSER` | Set it to any value, so that `vms login` and `vms desktop` do not open a browser. |

## Exit codes

| Code | Meaning |
| - | - |
| `0` | The command completed. |
| `1` | The command failed. The CLI writes `error:` and the reason to stderr. An API error also shows its code and its request ID. |
| `2` | The command does not exist. |
| Other | `vms exec` and `vms ssh` exit with the exit code of the command in the sandbox. |

Read the [changelog.](https://vms.dev/docs/changelog.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.