# CLI & File Reference

## Command Cheat Sheet

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