Reference

CLI

Every moil command on one page. Add --help to any of them for all of its flags; add --json to most of them for output a script can read.

Install with npx moil@latest, or npm install -g moil for the CLI alone. moil update moves to the newest version.

Account

Command	What it does
`moil login`	Sign in with a device code in your browser. Skipped when MOIL_API_KEY is set.
`moil whoami`	The account, workspace and key the CLI is using.
`moil usage`	This month’s usage, included credit left, and your plan’s limits.
`moil update`	Move the CLI to its newest version.
`moil keys create --name N [--expires-in 90d]`	Make an API key. It is printed once.
`moil keys ls \| revoke <key>`	List or revoke keys in the current workspace.

Command	What it does
`moil templates`	List the templates a box can start from.
`moil create --name N [--template T \| --from S]`	Start a box from a template or a snapshot, and wait until it runs.
`moil create … --vcpus 8 --mem 16 [--disk 50]`	Pick another size from your plan. Memory and disk are in GiB.
`moil ls [--label k=v] [--json]`	Your boxes, optionally filtered by label.
`moil get <box> [--json]`	One box: state, size, template, ports and operations.
`moil logs <box> [-f]`	Console log and recent operations. Never wakes the box.
`moil pause \| resume <box>`	Freeze a box with its memory, then carry on where it stopped.
`moil stop \| start <box>`	Shut down (files kept), then boot fresh.
`moil restart <box>`	Power-cycle a box that stopped answering. Disks are kept.
`moil resize <box> --vcpus N --mem M \| --disk D`	Change size or grow /data. A new CPU or memory size applies at the next start.
`moil idle <box> 15m \| off`	How long a box may sit idle before it pauses itself.
`moil rm <box> [--yes]`	Delete a box and its disks. Its snapshots stay.

Command	What it does
`moil exec <box> -- <cmd…>`	Run one command and exit with its exit code.
`moil exec --stream <box> -- <cmd…>`	Print output as it is written.
`moil exec --bg <box> -- <cmd…>`	Start a detached job and print its ID; follow it with moil jobs.
`moil jobs ls \| logs \| kill <box> [job]`	Background jobs started with exec --bg.
`moil run [--push DIR] [--timeout 10m] -- <cmd>`	Create a box, upload DIR, run the command, delete the box.
`moil ssh <box>`	An interactive shell over SSH.
`moil cp <src> <dst>`	Copy files in or out: moil cp ./a.tgz run-42:/data/a.tgz.
`moil ps <box>`	Processes running in the box.

Command	What it does
`moil snapshot <box> --name N`	Save a box’s disks as a snapshot.
`moil snapshot ls \| rm <snapshot>`	List or delete snapshots.
`moil restore <box> --snapshot S [--yes]`	Put a box’s disks back to a snapshot, in place. Same ID, name and URLs.
`moil fork <box> [--count N]`	Copy a box on its host in seconds, up to 5 copies, no snapshot needed.

Command	What it does
`moil port publish <box> <port> [--private]`	Give a port an HTTPS URL; --private adds a link token.
`moil port ls \| unpublish <box> <port>`	List or remove published ports.
`moil port forward <box> [LOCAL:]REMOTE`	A private localhost tunnel until Ctrl-C.
`moil desktop screenshot <box> > shot.png`	Grab the screen of a desktop box.
`moil desktop link <box> [--control] [--ttl 1h]`	A watch-only (or control) link to the desktop.
`moil desktop revoke <box>`	Invalidate every desktop link for the box and close open viewers.
`moil secrets set NAME --host H`	Store a credential the egress proxy adds for host H.
`moil secrets ls \| rm NAME`	List or delete secrets. Values are never printed.

moil ls --json | jq -r '.[] | select(.state == "paused") | .name'
moil create --name job --json | jq -r .id

Commands that change a box wait until the change is done and exit non-zero if it fails, so a script can run them one after another without polling.

Variable	Effect
`MOIL_API_KEY`	Use this key instead of a sign-in. Required where there is no browser.
`MOIL_WORKSPACE`	The workspace to act in when your account has more than one. Same as --workspace.
`NO_COLOR`	Plain output, no colour.

Code	Meaning
`0`	Done.
`1`	The request failed; the message says why.
`2`	Bad arguments or flags.
`3`	Not signed in, and no MOIL_API_KEY set.
`N`	moil exec and moil run exit with the command’s own code.