Reference

CLI & File Reference

Every spotexec and sx command, subcommand, and local or remote state file path in one concise reference.

Command Cheat Sheet#

diagram

sx [flags] <command...>                      run remotely (shorthand for `spotexec run --`)
sx <task> [args...]                          run a named task; parallel tasks fan out across slots
spotexec run [flags] -- <cmd>                sync worktree, execute remotely, write back changes
spotexec exec [flags] -- <cmd>               execute in the last-used slot without syncing
spotexec tasks                               list tasks defined in .spotexec.toml
spotexec sync [flags]                        pre-sync a slot (plus container build & [deps] install)
spotexec sync-plan [--json]                  dry-run manifest: file count, bytes, largest files, excludes
spotexec pull <glob>... [--dest DIR]         pull gitignored artifacts from the last-used slot
spotexec status [runner...] [--json]         inspect runners, Spot VMs, active slot holders, idle timers
spotexec monitor [runner...] [--interval 2s] live terminal dashboard of slot load and $/hr burn rate
spotexec up [runner] [--count N]             pre-warm Spot VMs now and wait until ready
spotexec down [runner...] [--all]            terminate fleet VMs immediately (and leftover bake builders)
spotexec daemon start|stop|run               manage optional local pool manager process
spotexec daemon status [--json]              inspect warm pool health, probes, and scaling history
spotexec container init [--path P] [--force] scaffold .spotexec/Dockerfile and wire [container] config
spotexec container build [run flags]         build project container on a runner now (pushes to ECR on AWS)
spotexec image bake [runner] [--pull IMG]    bake a fast-boot AMI from the runner's bootstrap scripts
spotexec image list|clear [runner]           list or deregister baked AMIs and snapshots
spotexec setup [host...] [flags]             configure this machine (and others over SSH) + scoped IAM keys
spotexec doctor [runner...]                  end-to-end check of SSH, helper, config, AWS auth, VPC, quota
spotexec unlock [runner[/id]] (--slot N | --all)
                                             kill a wedged command and reclaim its slot lock
spotexec prune [runner[/id]...] [--older-than 7d] [--dry-run]
                                             clean up unused dependency caches and idle slot workspaces
spotexec init [--global] [--force]           generate starter .spotexec.toml (or global config.toml)
spotexec hook install [--claude] [--codex] [--shared|--global] [--uninstall]
                                             install or remove coding agent command hooks
spotexec hook check '<command>'              test whether the agent hook offloads or keeps a command local
spotexec cloud-init [runner]                 print the exact cloud-init user-data script for an AWS runner
spotexec completion bash|zsh|fish|powershell generate shell tab-completion script
spotexec version                             print binary and embedded helper version

Files & State Paths#

Path	Purpose
`~/.config/spotexec/config.toml`	Global runner configuration (overridable via `SPOTEXEC_CONFIG`, `SPOTEXEC_CONFIG_DIR`, or `XDG_CONFIG_HOME`).
`~/.config/spotexec/keys/`	Auto-generated Ed25519 SSH keypair (`id_ed25519`) injected into ephemeral Spot VMs via user-data.
`~/.config/spotexec/owner-id`	Per-machine random identifier applied via the `spotexec-owner` EC2 tag so workstations isolate their VMs.
`~/.aws/credentials` `[spotexec]`, `~/.aws/config` `[profile spotexec]`	Scoped IAM user access key (`0600`) and region written by `spotexec setup`.
`~/.local/state/spotexec/`	Local `flock`-protected pool ledgers (`pool.json`), fair queue tickets (`waiters/`), per-instance `known_hosts`, and `daemon` logs (`SPOTEXEC_STATE_DIR` / `XDG_STATE_HOME`).
`~/.cache/spotexec/`	Local OpenSSH `ControlMaster` sockets (`cm/`) and helper upload markers.
`.spotexec.toml`, `.spotexecignore`	Committed per-repository configuration and extra sync exclusion patterns.
`.spotexec/Dockerfile`	Committed project toolchain Dockerfile created by `spotexec container init`.
`<git-dir>/spotexec/conflicts/<run-id>/`	Saved remote versions of files that conflicted with concurrent local edits during 3-way write-back (`.spotexec/conflicts/` outside Git).
Runner: `~/.cache/spotexec/`	Remote `work_root` holding `bin/spotexec-helper`, per-slot workspaces, and lockfile dependency caches.
Runner: `/var/tmp/spotexec/`, `/var/log/spotexec-bootstrap.log`	Ephemeral VM `lifecycle.lock`, activity clock, Spot drain markers, and first-boot log.