# CLI reference

> The common vy commands, their options, how vy finds your key and server, and its exit codes.

`vy` is the VMYard command-line interface. It needs Node.js 20 or newer.

> [!NOTE]
> The CLI is in private preview and is not published to npm. Build it from the [erphq/vmyard-sdk](https://github.com/erphq/vmyard-sdk) repository (ask your VMYard contact for access):

```sh
git clone https://github.com/erphq/vmyard-sdk.git
cd vmyard-sdk && npm ci && npm run build
npm install -g ./cli
export VMYARD_API_URL=https://api.example.com
vy login
```

`<machine>` is a machine ID, tenant alias, or display name everywhere. `<webhook>` is a webhook ID or name.

## Global options

| Option | Meaning |
| --- | --- |
| `--json` | Machine-readable output on stdout; errors as JSON on stderr. |
| `--api-url URL` | The API origin. Default: `VMYARD_API_URL`, or the one saved by `vy login`. |
| `--org ID` | Send `X-Organization-ID`. Default: `VMYARD_ORGANIZATION_ID`. |
| `-h`, `--help` | Show help. |
| `-v`, `--version` | Show the version. |

## Authentication

| Command | What it does |
| --- | --- |
| `vy login [--no-browser] [--scope PRESET]` | Browser sign-in with a device code; stores a new key and its organization. See [CLI device login](/docs/guides/cli-login). |
| `vy login --key-stdin [--no-verify]` | Store a key read from stdin, after checking it with `/v1/me`. |
| `vy logout` | Remove the stored key from this computer. |
| `vy whoami` | The caller, organizations, API URL, and where the key came from. |
| `vy keys` | List API keys. Today the server needs a browser session for this, so `vy keys` explains that keys are managed in the console. |

The key comes from `VMYARD_API_KEY` when it is set, otherwise from `vy login`. `vy` never accepts a key as an argument and never prints one, even in errors.

## Machines

| Command | What it does |
| --- | --- |
| `vy ls [--limit N]` | List machines. |
| `vy new [--plan P] [--image I] [--region R] [--name N] [--alias A] [--auto-stop HOURS\|never] [--setup-script FILE] [--wait]` | Create a machine. Plan, image, and region take names or IDs and default to the first in the catalog. `--name` is also the alias unless `--alias` is given. `--setup-script -` reads stdin. Without `--wait` it prints the operation ID. |
| `vy get <machine>` | Show one machine. |
| `vy rename <machine> <name>` | Change the display name. The alias keeps working. |
| `vy autostop <machine> <HOURS\|never>` | Set auto-stop: `2`, `0.5`, `30m`, `1d`, or `never`; 1 minute to 30 days. Restarts a running machine's deadline. |
| `vy start <machine> [--wait]` | Start a stopped machine. |
| `vy stop <machine> [--wait]` | Stop a machine. |
| `vy restart <machine> [--wait]` | Restart a machine. |
| `vy rm <machine> [--wait]` | Delete a machine. |

```sh
vy new --plan small --name dev --auto-stop 2 --setup-script ./setup.sh --wait
vy rename dev api
vy autostop api never
vy stop api --wait
vy rm api --wait
```

## Commands and files

| Command | What it does |
| --- | --- |
| `vy exec <machine> [--timeout MS] [--no-stream] -- <argv...>` | Run a program. Output streams as it arrives unless `--no-stream`. |
| `vy exec <machine> -c '<shell command>'` | Run a command under `/bin/sh -c`. |
| `vy cp <local> <machine>:<path>` | Upload a file into `/work`. `-` reads stdin. |
| `vy cp <machine>:<path> <local>` | Download a file. `-` writes stdout; a directory keeps the file's name. |

```sh
vy exec dev -- uname -a
vy exec dev -c 'cd /work && make test'
vy cp ./build.tar.gz dev:build.tar.gz
vy cp dev:out/report.txt .
```

## Catalog and operations

| Command | What it does |
| --- | --- |
| `vy plans`, `vy images`, `vy regions` | List the catalog for `vy new`. |
| `vy op <operation-id> [--wait]` | Show an operation, or wait for it to finish. |

## Billing

| Command | What it does |
| --- | --- |
| `vy usage [<machine>] [--since T] [--until T]` | Metered time and cost per machine with a total, or for one machine. `T` is RFC 3339 or `YYYY-MM-DD` (UTC). Defaults to the current period. |
| `vy billing` | Balances, plan, trial, and spend cap. |
| `vy limits` | Plan limits and current use. |

Billing refusals print their code, a hint, and how long to wait.

## Webhooks

| Command | What it does |
| --- | --- |
| `vy webhooks ls` | List endpoints. |
| `vy webhooks add --name N --url https://… [--event E]… [--disabled]` | Create an endpoint. Events default to all eight; `--event` repeats or takes a comma list. Prints the signing secret once. |
| `vy webhooks rm <webhook>` | Delete an endpoint. |
| `vy webhooks rotate <webhook>` | Rotate the signing secret and print the new one. |
| `vy webhooks deliveries <webhook> [--limit N]` | Recent deliveries. |

Webhooks need an Owner or Admin and a `full_access` key (`vy login --scope full_access`).

## Configuration

| Variable | Meaning |
| --- | --- |
| `VMYARD_API_URL` | The API origin. There is no default. |
| `VMYARD_API_KEY` | An API key. Wins over the stored key. |
| `VMYARD_ORGANIZATION_ID` | Sent as `X-Organization-ID`. |
| `VMYARD_CONFIG_DIR` | Where the config file lives. |

The config file is `config.json` in `$XDG_CONFIG_HOME/vmyard/` (Linux, default `~/.config/vmyard/`), `~/Library/Application Support/vmyard/` (macOS), or `%APPDATA%\vmyard\` (Windows). It is written with mode `0600`.

## Exit codes

| Code | Meaning |
| --- | --- |
| `0` | Success. |
| `1` | An API or runtime error. |
| `2` | A usage error (bad arguments). |
| any | `vy exec` exits with the remote command's exit code. |
| `124` | `vy exec`: the command timed out. |
| `125` | `vy exec`: VMYard couldn't run the command (an error frame or a broken stream). |

## More commands

This page covers the common commands. `vy --help` lists the rest, including `ports`, `ssh`, `shell`, `network`, `snapshot` and `snapshots`, `fork`, `restore`, `templates`, `env`, `history`, `logs`, `orgs`, and `alerts`. The CLI cannot start a background command; use the console, the SDKs, or the [HTTP API](/docs/guides/background-commands).