Skip to main content
The Blacksmith CLI lets you and your coding agents inspect and manage your Blacksmith organization from the terminal: search CI logs, inspect job runs and their CPU/memory metrics, manage Actions and Bazel caches, manage sticky disks, report usage, and run CI against local changes with Testboxes.

​
Installation

The CLI auto-updates in the background on every invocation. You can also update explicitly:

​
Authentication

This opens a browser for the OAuth flow and saves a token to ~/.blacksmith/credentials. You only need to do this once per machine. Tokens are scoped to an organization. If you’re authenticated with multiple organizations, select one with the --org flag or the BLACKSMITH_ORG environment variable. Check your authentication state with:

​
Token types

blacksmith auth login mints a user token tied to your GitHub identity. Its permissions mirror yours: Testbox warmup requires write access to the repository, reads require repository access, and you only see and manage your own testboxes. Cache and sticky disk reads require repository access; deletes require write access. Organization admins can mint an organization token for machine agents (Cursor Cloud agents, CI bots) that need access across the whole organization:
This opens a browser to verify you’re an org admin, then prints the token once — it is never shown again. Org tokens can warm up testboxes on any installed repository, see and shut down all testboxes, and manage all cache entries and sticky disks. Manage them with blacksmith org-token list and blacksmith org-token revoke <id>.
Don’t hand agents a copy of ~/.blacksmith/credentials from a human login — that token is tied to that person’s permissions and lifecycle. Mint an org token instead.
For non-interactive environments (CI, scripts, agents), pass a token directly:

​
Command groups

Most commands support --format json | table | yaml for output. JSON is the default, which makes the CLI easy to compose with tools like jq and easy for coding agents to consume.