--- title: CLI reference description: 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](/docs/get-started/install#command-line-tools). In a source checkout, run `pnpm vectis` instead. See [Operations and output](/docs/reference/operations) for keys, waiting, exit codes and errors. ## Service ```text 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 ] 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 VMs ``` ## Cloud and GitHub ```text 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 ] 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 ] [--memory-budget-mib ] Set runner limit (1-16, default 5) and shared VM memory budget Memory budget: 2048 MiB to host RAM, default 75% of host RAM ``` ## Repositories and jobs ```text repository readiness [--environment ] Check readiness before connecting repository readiness --binding Check an existing binding repository list List repositories connected to this machine, with their runs-on label repository connect Connect with --account and --environment , optional --owner repository enable-auto Start runners automatically for matching queued jobs repository disable-auto Stop starting runners automatically repository capacity-mode demand|scale-set Choose runner capacity mode (scale sets are preview) repository disconnect Stop future runners without interrupting running jobs runner run Start one disposable runner, optionally only for --job-id runner reconcile Clean up an interrupted runner after verifying its VM stopped repository cache enable|disable|clear [--size-gib N] Configure or clear an opt-in repository cache disk (default 20 GiB) repository access --actors any| --approval automatic|required Actor IDs are numeric GitHub user IDs: gh api users/ --jq .id job list Read recent GitHub job states for a connected repository job logs --binding [--follow] Read the retained log; follow backs off from 2 to 30 seconds when empty job scan Discover missing jobs through the GitHub API job refresh Recover one job state directly from GitHub ``` ## Workflow run control ```text run rerun-failed Rerun failed jobs of a completed GitHub run run cancel Request cancellation of an active GitHub run workflow dispatch --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 ```text migration preview --map = Rewrite runs-on labels locally without writing files migration analyze Prepare a reviewable migration preview for a repository migration publish Create or recover its pull request; never merges ``` ## Environments ```text environment provision Derive a new image with --from --image-directory [--name ] [--setup-script ] [--no-runner] environment prepare-linux Prepare Ubuntu 24.04 with --image-directory and --storage-path environment resume Continue an interrupted Ubuntu preparation environment install-macos Install macOS 27 with --image-directory and --storage-path, optional --restore-path environment open-macos-setup Open the guest console for Setup Assistant environment connect-macos-guest Prepare guest SSH enrollment, optional --open-terminal environment verify-macos-guest Verify guest SSH and unattended startup prerequisites environment finish-macos-setup Register the verified, stopped macOS setup environment resume-macos Inspect or retry an interrupted macOS installation environment discard-macos --environment Permanently discard an unregistered setup environment install-windows Experimental: install Windows 11 from your ISO, drivers and firmware environment resume-windows Continue an interrupted Windows installation environment register --file Register an existing prepared environment JSON file environment list List environments and effective network egress environment configure Set --cpu, --memory-mib, --storage-path, --x64 rosetta|off or --egress internet_only|open for future VMs --warm-pool keeps 0-4 SSH-ready VMs (default 0, uses RAM) environment start Start a clean VM, optionally overriding --cpu, --memory-mib, --storage-path environment remove Remove an idle definition, preserving its disk instance stop Stop a VM owned by this service instance reconcile Recheck an interrupted VM safely ``` ## Activities and operations ```text activity list List unfinished and recent activities; filter with --kind, --status, --repository, --limit activity get Inspect one activity with the operations that belong to it activity cancel Cancel work an activity owns, or close one that only waits for you operation get Inspect one retained operation, including outside the status window operation wait Wait for an operation's terminal state; on --timeout, print it as it is operation cancel Cancel an active operation, or close one that only waits for you command --file Submit any protocol command as JSON version Print the Vectis version ``` ## Options ```text --home State directory (default: ~/.vectis, or ~/.vectis-dev for development builds) --machine Send commands and queries to a remote machine after vectis login --json Print compact JSON (output is always JSON) --key Idempotency key; retrying with the same key never repeats work --kind Filter activities by what asked for them --status Filter activities by status --repository Filter activities by repository --wait Wait for the operation's terminal state (automatic for setting commands) --timeout Wait timeout (default: 120000) --name Environment or login name (defaults: Ubuntu 24.04 ARM64, macOS 27 ARM64, Windows 11 ARM64, Vectis CLI) --image-directory Existing directory for prepared base images --storage-path Directory for VM clones --cpu Virtual CPUs (defaults: 2, Windows 4) --memory-mib Memory (defaults: 4096, Windows 8192; at most 75% of host memory) --disk-gib Disk capacity (defaults: Ubuntu 32, macOS 64, Windows 96) --restore-path 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 Windows installation media --image-name Windows edition in the ISO (default: Windows 11 Pro) --accept-license Accept the Windows license terms for this installation --account GitHub account ID from vectis github accounts --owner Repository owner when it differs from the account --environment Environment ID --job-id Require a matching queued GitHub job before starting a runner --ref Git ref for workflow dispatch --input = Workflow input; repeat for up to 25 inputs --map = Label mapping for migration preview; repeat for more labels --file JSON input file --if-idle Refuse to stop while VMs or operations are active -v, --version Print the Vectis version -h, --help Show this help ``` Exit 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 ```text vectis status --json vectis environment prepare-linux ubuntu --image-directory ~/VMs/images --storage-path ~/VMs/clones --wait vectis repository list --json vectis runner run --key --json vectis operation wait --timeout 3600000 --json ``` Documentation: https://vectis.kerd.dev/docs