> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blacksmith.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Allow your agents to access Blacksmith usage data through the terminal

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](/blacksmith-cli/cache), manage [sticky disks](/blacksmith-cli/stickydisk), report usage, and run CI against local changes with [Testboxes](/blacksmith-cli/testbox).

## Installation

```bash theme={"system"}
curl -fsSL https://get.blacksmith.sh | sh
```

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

```bash theme={"system"}
blacksmith update
```

## Authentication

```bash theme={"system"}
blacksmith auth login
```

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:

```bash theme={"system"}
blacksmith auth status
```

### Token types

`blacksmith auth login` mints a **user token** tied to your GitHub identity. Its permissions mirror yours: [Testbox](/blacksmith-cli/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:

```bash theme={"system"}
blacksmith org-token create --label cursor-cloud
```

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

<Note>
  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.
</Note>

For non-interactive environments (CI, scripts, agents), pass a token directly:

```bash theme={"system"}
blacksmith auth login --api-token - --non-interactive --organization <org-slug>
```

## Command groups

| Command                                               | Description                                                  |
| :---------------------------------------------------- | :----------------------------------------------------------- |
| [`blacksmith cache`](/blacksmith-cli/cache)           | List and delete Actions and Bazel cache entries              |
| [`blacksmith stickydisk`](/blacksmith-cli/stickydisk) | List and delete sticky disks                                 |
| [`blacksmith jobs`](/blacksmith-cli/jobs)             | Inspect job runs and aggregate CPU/memory metrics            |
| [`blacksmith logs`](/blacksmith-cli/observability)    | Search and analyze CI logs across your organization          |
| [`blacksmith usage`](/blacksmith-cli/observability)   | Report Actions and storage usage for a time range            |
| [`blacksmith runners`](/blacksmith-cli/observability) | Inspect Blacksmith runner SKUs and catalog metadata          |
| [`blacksmith testbox`](/blacksmith-cli/testbox)       | Run CI against local changes, instantly                      |
| `blacksmith auth`                                     | Manage authentication                                        |
| `blacksmith org-token`                                | Mint, list, and revoke organization tokens (org admins only) |
| `blacksmith update`                                   | Update the CLI to the latest version                         |

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.