Developers tired of the commit-push-wait cycle for CI verification now have a direct alternative with latchkey run. This CLI tool executes a single command on a fresh Latchkey runner by packing the current directory, uploading it to a clean Ubuntu machine, and streaming logs back to the terminal. It eliminates the need to spend a commit or a GitHub Actions workflow run just to see if tests pass, providing immediate verdicts for both humans and coding agents.

How the Execution Flow Works

The process follows a strict five-stage pipeline: packing the directory, creating the job with exact tarball size, uploading via presigned PUT, submitting the job, and tailing logs. The packaging root is the current directory, meaning running from a subdirectory only ships that specific folder. Exclusions are applied in three passes, including .gitignore, a credential deny-list, and .latchkeyignore, ensuring that node_modules and build artifacts do not ship. This forces a fresh dependency install on the runner, mimicking the clean state of CI environments.

Installation and Flag Configuration

Installation requires Node 20.18.1 or newer and the scoped npm package @latchkeydev/cli. Authentication is handled via latchkey login or the LATCHKEY_TOKEN environment variable, which is preferred for scripts to avoid touching config files. The tool offers granular control through flags such as --size for runner selection (small to xlarge), --env for variable injection, and --timeout for job duration limits ranging from 30 to 10,800 seconds. The --no-context flag skips packing entirely, running commands in an empty workspace for environment diagnostics.

Interpreting Exit Codes and Logs

The exit code is the primary contract for automation, distinguishing between test failures and operational errors. A successful job returns the command's own exit code, while cancellations return 130 and expirations return 124. Usage errors yield 2, and network or authentication failures return 1. This separation allows scripts to branch logic based on whether the code failed or the infrastructure broke. Interrupting the terminal with Ctrl-C stops the log tail but leaves the job running remotely, accessible via latchkey logs --follow.

Runner Specifications and Cost Efficiency

Latchkey runners are ephemeral, single-use machines destroyed after execution. The latchkey-small runner, documented at 2 vCPU and 8 GB RAM, costs $0.0025 per minute as of September 2026. Ten two-minute verification runs cost approximately five cents, drawing from the same free-minute pool as GitHub Actions jobs. This model is ideal for pre-push validation, ensuring that pull requests are opened only after code has passed on a clean Linux environment, rather than debugging macOS-specific issues in CI.

Key Takeaways

  • latchkey run provides instant CI feedback without committing code or triggering full workflows.
  • Exit codes are structured to differentiate between test failures (command exit code) and infrastructure errors (1, 2, 130, 124).
  • Runner sizes map directly to GitHub Actions labels, with small runners costing $0.0025 per minute.
  • The tool is optimized for non-interactive checks and cannot handle commands requiring stdin or TTY.

The Bottom Line

For builders who treat CI as a feedback loop rather than a deployment gate, latchkey run removes the friction of the commit-push cycle. It turns infrastructure verification into a cheap, fast, and scriptable terminal command.