CLI reference
Every vectis command and option, generated from the CLI help.
This page is generated from vectis --help when the documentation is built. Install the command line tools from the app as described in Install Vectis. In a source checkout, run pnpm vectis instead. See Operations and output for keys, waiting, exit codes and errors.
Service
service install Install and start the macOS login service for this home
service uninstall Remove the login service, preserving all data
service start Start the installed or an independent background service
service run Run the service in the foreground
service stop [--if-idle] Stop the service; --if-idle refuses to interrupt active work
service status Inspect the login service registration for this home
service update Adopt this runtime when idle; restore the previous one on failure
service recover-update Restore the previous runtime after an interrupted update
status Inspect the machine, unfinished work and bounded recent history
storage Inspect image and VM disk usage
doctor Inspect host and runtime prerequisites
logs [--lines <count>] Read the newest service log lines (default 200, at most 1000)
capabilities List supported commands and queries with the command schema
pause | resume Stop or allow admission of new VMsCloud and GitHub
cloud pair Begin browser-approved pairing of this machine with your account
cloud finish Complete an approved pairing
cloud disconnect Remove this machine's saved cloud connection and credential
github connect Print the page that links a GitHub account and installs the App
github accounts List verified GitHub accounts available to this machine
login [--name <text>] Begin browser-approved remote control of your machines
login finish Complete an approved remote control login
logout Revoke this CLI's remote access and remove its credentials
machine list List your machines and when they were last seen
machine configure [--max-runners <N>] [--memory-budget-mib <N>]
Set runner limit (1-16, default 5) and shared VM memory budget
Memory budget: 2048 MiB to host RAM, default 75% of host RAMRepositories and jobs
repository readiness <owner/name> [--environment <id>] Check readiness before connecting
repository readiness --binding <id> Check an existing binding
repository list List repositories connected to this machine, with their runs-on label
repository connect <name> Connect with --account <id> and --environment <id>, optional --owner <org>
repository enable-auto <id> Start runners automatically for matching queued jobs
repository disable-auto <id> Stop starting runners automatically
repository capacity-mode <id> demand|scale-set Choose runner capacity mode (scale sets are preview)
repository disconnect <id> Stop future runners without interrupting running jobs
runner run <binding-id> Start one disposable runner, optionally only for --job-id <id>
runner reconcile <operation-id> Clean up an interrupted runner after verifying its VM stopped
repository cache enable|disable|clear <binding-id> [--size-gib N]
Configure or clear an opt-in repository cache disk (default 20 GiB)
repository access <binding-id> --actors any|<id,id,...> --approval automatic|required
Actor IDs are numeric GitHub user IDs: gh api users/<login> --jq .id
job list <binding-id> Read recent GitHub job states for a connected repository
job logs <job-id> --binding <id> [--follow] Read the retained log; follow backs off from 2 to 30 seconds when empty
job scan <binding-id> Discover missing jobs through the GitHub API
job refresh <binding-id> <job-id> Recover one job state directly from GitHubWorkflow run control
run rerun-failed <binding-id> <run-id> Rerun failed jobs of a completed GitHub run
run cancel <binding-id> <run-id> Request cancellation of an active GitHub run
workflow dispatch <binding-id> <workflow> --ref <ref> Dispatch a workflow file or numeric ID
Successful rerun/cancel results distinguish requested from observed GitHub state.
Ambiguous POST responses require checking GitHub before retrying with a new key.
Run command receipts expire after 30 days; do not replay older keys.Workflow migration
migration preview <workflow-file> --map <from>=<to> Rewrite runs-on labels locally without writing files
migration analyze <binding-id> Prepare a reviewable migration preview for a repository
migration publish <preview-id> Create or recover its pull request; never mergesEnvironments
environment provision <id> Derive a new image with --from <id> --image-directory <new-path>
[--name <name>] [--setup-script <file>] [--no-runner]
environment prepare-linux <id> Prepare Ubuntu 24.04 with --image-directory and --storage-path
environment resume <setup-id> Continue an interrupted Ubuntu preparation
environment install-macos <id> Install macOS 27 with --image-directory and --storage-path, optional --restore-path
environment open-macos-setup <setup-id> Open the guest console for Setup Assistant
environment connect-macos-guest <setup-id> Prepare guest SSH enrollment, optional --open-terminal
environment verify-macos-guest <setup-id> Verify guest SSH and unattended startup prerequisites
environment finish-macos-setup <setup-id> Register the verified, stopped macOS setup
environment resume-macos <setup-id> Inspect or retry an interrupted macOS installation
environment discard-macos <setup-id> --environment <id> Permanently discard an unregistered setup
environment install-windows <id> Experimental: install Windows 11 from your ISO, drivers and firmware
environment resume-windows <setup-id> Continue an interrupted Windows installation
environment register --file <path> Register an existing prepared environment JSON file
environment list List environments and effective network egress
environment configure <id> Set --cpu, --memory-mib, --storage-path, --x64 rosetta|off or --egress internet_only|open for future VMs
--warm-pool <N> keeps 0-4 SSH-ready VMs (default 0, uses RAM)
environment start <id> Start a clean VM, optionally overriding --cpu, --memory-mib, --storage-path
environment remove <id> Remove an idle definition, preserving its disk
instance stop <id> Stop a VM owned by this service
instance reconcile <id> Recheck an interrupted VM safelyActivities and operations
activity list List unfinished and recent activities; filter with --kind, --status, --repository, --limit
activity get <id> Inspect one activity with the operations that belong to it
activity cancel <id> Cancel work an activity owns, or close one that only waits for you
operation get <id> Inspect one retained operation, including outside the status window
operation wait <id> Wait for an operation's terminal state; on --timeout, print it as it is
operation cancel <id> Cancel an active operation, or close one that only waits for you
command --file <path> Submit any protocol command as JSON
version Print the Vectis versionOptions
--home <directory> State directory (default: ~/.vectis, or ~/.vectis-dev for development builds)
--machine <id> Send commands and queries to a remote machine after vectis login
--json Print compact JSON (output is always JSON)
--key <id> Idempotency key; retrying with the same key never repeats work
--kind <vectis|github> Filter activities by what asked for them
--status <status> Filter activities by status
--repository <owner/name> Filter activities by repository
--wait Wait for the operation's terminal state (automatic for setting commands)
--timeout <milliseconds> Wait timeout (default: 120000)
--name <text> Environment or login name (defaults: Ubuntu 24.04 ARM64, macOS 27 ARM64,
Windows 11 ARM64, Vectis CLI)
--image-directory <path> Existing directory for prepared base images
--storage-path <path> Directory for VM clones
--cpu <count> Virtual CPUs (defaults: 2, Windows 4)
--memory-mib <MiB> Memory (defaults: 4096, Windows 8192; at most 75% of host memory)
--disk-gib <GiB> Disk capacity (defaults: Ubuntu 32, macOS 64, Windows 96)
--restore-path <file.ipsw> Local macOS restore image instead of the pinned download
--open-terminal Open Terminal with the guest enrollment script
--iso-path, --drivers-path, --firmware-path, --firmware-vars-path <path> Windows installation media
--image-name <text> Windows edition in the ISO (default: Windows 11 Pro)
--accept-license Accept the Windows license terms for this installation
--account <id> GitHub account ID from vectis github accounts
--owner <organization> Repository owner when it differs from the account
--environment <id> Environment ID
--job-id <number> Require a matching queued GitHub job before starting a runner
--ref <branch-or-tag> Git ref for workflow dispatch
--input <key>=<value> Workflow input; repeat for up to 25 inputs
--map <from>=<to> Label mapping for migration preview; repeat for more labels
--file <path> JSON input file
--if-idle Refuse to stop while VMs or operations are active
-v, --version Print the Vectis version
-h, --help Show this helpExit codes: 0 success, 1 failure or cancellation, 3 action required or still pending.
Setting commands always wait: pause/resume, repository enable-auto/disable-auto/capacity-mode, repository cache,
environment register/configure/remove, instance stop/reconcile, operation cancel, and activity cancel.
Their wait timeout reports wait_cancelled with exit code 3; the operation may still be running.
Errors are JSON: {“error”:{“code”,“message”,“nextStep”}}.
Examples
vectis status --json
vectis environment prepare-linux ubuntu --image-directory ~/VMs/images --storage-path ~/VMs/clones --wait
vectis repository list --json
vectis runner run <binding-id> --key <stable-key> --json
vectis operation wait <operation-id> --timeout 3600000 --jsonDocumentation: https://vectis.kerd.dev/docs