SDKs and CLI

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.

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

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.

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.