Running Commands & Write-back

sx [flags] <command> [args...]        # sync → run remotely → write back changes
sx [flags] -- <command> [args...]     # explicit separator if command matches a flag/subcommand
sx <task> [args...]                   # run a named or parallel task from .spotexec.toml
spotexec exec -- <command>            # run inside the last-used slot without syncing

sx stops parsing its own flags at the first non-flag token, so sx pnpm vitest run --watch=false forwards --watch=false straight to pnpm. Multiple arguments are shell-quoted individually; a single string argument runs as a shell pipeline (sx 'pnpm lint && pnpm test'). Absolute local paths inside your worktree are automatically rewritten to the remote workspace path, and remote stack trace paths are rewritten back on output.

Run Flags#

Environment on the Runner#

Every remote command receives these environment variables automatically, in addition to keys listed in env_allow (forwarded from your local shell) and env (static map in .spotexec.toml):

Exit Codes#

3-Way Content-ID Write-back#

When a remote command formats code (prettier --write), applies lint fixes (eslint --fix), updates test snapshots (vitest -u), or runs codegen, spotexec brings those edits back without risking concurrent local work.

Before syncing, sx records the exact Git SHA-1 blob ID of every synced file—the baseline. After execution, spotexec-helper hashes the slot workspace by content (never trusting mtimes) and returns mutations. Each modified or deleted file is checked against your local worktree right now:

Remote file mutated (new SHA-1 != baseline SHA-1)
  │
  ├─ Local file now == Remote result  ──▶ No-op (already identical)
  │
  ├─ Local file now == Baseline SHA-1 ──▶ Safe to apply: stage to temp file + atomic rename
  │
  └─ Local file now != Baseline SHA-1 ──▶ Edited locally mid-run!
                                          • Keep your local file untouched
                                          • Save remote bytes to <git-dir>/spotexec/conflicts/<run-id>/<path>
                                          • Emit SYNC_CONFLICT warning

Additional write-back invariants:

• Deletions apply deepest-first before file writes.
• Newly created remote files are written back only if they are not ignored by .gitignore / .spotexecignore and do not already exist locally—so dist/, target/, and node_modules/ never pollute your laptop.
• Paths containing .git (in any case spelling) or traversing symlinks are rejected unconditionally.

Pulling Gitignored Artifacts#

When you do want gitignored outputs back locally (such as HTML coverage reports, Playwright traces, or compiled binaries), pull them explicitly:

# Pull after a single run
sx --pull coverage/ --pull 'packages/*/coverage' pnpm vitest run --coverage

# Or pull on demand from the most recently used slot
spotexec pull coverage/ playwright-report/ --dest ./artifacts

To pull artifacts automatically on every run, set pull_artifacts = ["coverage/"] under [sync] in .spotexec.toml. Pulled artifacts never overwrite tracked or non-ignored source files.