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

# CLI guide

> Manage Gauge measurements, run configurations, experiments, and analytics from the command line.

The `gauge` CLI is a typed client for the Gauge API. Use it for interactive work, repeatable scripts, and CI jobs. Agent execution stays in Gauge; the CLI only configures and launches work.

## Install the CLI

The CLI requires Node.js 22.12 or later.

```bash theme={null}
npm install -g @withgauge/cli
gauge --version
```

## Sign in

For a local terminal, use the browser flow:

```bash theme={null}
gauge auth login
```

For SSH or another machine that cannot accept a browser callback, use the device flow:

```bash theme={null}
gauge auth login --device
```

To provide an existing token without opening a browser, pipe it to the CLI:

```bash theme={null}
printf '%s\n' "$GAUGE_API_TOKEN" | gauge auth login --with-token
```

Gauge stores credentials in `~/.config/gauge/credentials` with permissions limited to your user. The `GAUGE_API_TOKEN` environment variable takes precedence over stored credentials.

<Warning>
  Treat a Gauge API token like a password. Do not commit it or pass it as a command-line argument that may appear in shell history.
</Warning>

## Select an organization

One token can access every organization where you are a member.

```bash theme={null}
gauge orgs list
gauge orgs use acme
gauge auth whoami
```

`gauge orgs use` writes the default organization to `~/.config/gauge/config.json`. Override it for one command with `--org`:

```bash theme={null}
gauge --org research-lab status
```

## Common workflows

### Measure Agent Experience

An eval set defines a task and its judging criteria. A run preset supplies the repository and agent configuration.

```bash theme={null}
gauge evals list
gauge presets list
gauge evals attach eval_123 --preset preset_456
gauge evals run eval_123
gauge evals runs eval_123
```

Attaching a preset changes scheduled spend. Interactive commands print the per-cycle run count and ask for confirmation. Pass `--yes` only in automation where you have reviewed the configuration.

### Measure Agent Preference

Agent Preference prompts measure which brands agents recommend or adopt.

```bash theme={null}
gauge preference list
gauge preference get prompt_123
gauge preference run prompt_123
gauge stats rankings
```

Use `gauge preference --help` to create prompts, attach presets, manage markets, and inspect run history.

### Configure runs

Run presets are reusable combinations of repositories, agents, models, personas, skills, and MCP servers.

```bash theme={null}
gauge presets create \
  --name api-main \
  --repo https://github.com/acme/api \
  --agent claude-code:claude-opus-4-8 \
  --skill acme-cli@1.2.0
```

Manage each part of the configuration with its own command group:

| Command          | Manages                                  |
| ---------------- | ---------------------------------------- |
| `gauge repos`    | Repository catalog and Git metadata      |
| `gauge personas` | Judge instructions referenced by presets |
| `gauge skills`   | Versioned agent skills staged into runs  |
| `gauge mcp`      | MCP server definitions prepared for runs |
| `gauge presets`  | Reusable combinations of those resources |
| `gauge cycles`   | Shared execution cadence                 |

### Watch a run

```bash theme={null}
gauge runs list --status running
gauge runs watch run_123
gauge runs logs run_123
gauge runs diff run_123
gauge runs insight run_123
```

`watch` follows the live event stream. `logs` prints the events available so far and exits. `diff` writes the run's working-tree diff to standard output.

### Apply a declarative configuration

Use `gauge apply` to launch work from a JSON specification.

```bash theme={null}
gauge apply --example > gauge-battery.json
gauge apply --schema > gauge-battery.schema.json
gauge apply --dry-run -f gauge-battery.json
gauge apply -f gauge-battery.json
```

Run the dry run first. It shows the resources and runs Gauge would create without applying the change.

### Query analytics

Discover the available datasets and fields before you build a report.

```bash theme={null}
gauge query datasets
gauge query fields --dataset ecosystem
gauge query \
  --dataset ecosystem \
  --dimensions brand \
  --metrics installs,install_rate \
  --since 30d \
  --output json
```

Use `--explain` to print the compiled query to standard error.

## Script with JSON output

Read commands support `--output json` or `-o json`.

```bash theme={null}
gauge runs list --status finished -o json | jq '.items[].id'
```

The output format is a global option, so place it before or after the command unless a shell wrapper requires otherwise.

## Environment and config

| Setting           | Purpose                                       | Precedence                    |
| ----------------- | --------------------------------------------- | ----------------------------- |
| `GAUGE_API_TOKEN` | Bearer token for CI or ephemeral environments | Highest                       |
| `GAUGE_API_URL`   | API base URL override                         | Higher than local config      |
| `defaultOrg`      | Default organization slug or public ID        | `~/.config/gauge/config.json` |
| `apiUrl`          | Persisted API base URL override               | `~/.config/gauge/config.json` |

Manage local values with `gauge config get`, `gauge config set`, and `gauge config unset`.

## Exit codes

| Code | Meaning                                                     |
| ---- | ----------------------------------------------------------- |
| `0`  | The command completed successfully.                         |
| `1`  | The API, network, or another runtime operation failed.      |
| `2`  | The command or request was invalid.                         |
| `3`  | Billing or provider-key requirements blocked the operation. |

## Discover commands

The CLI includes command groups for authentication, organizations, members, Agent Preference, evals, presets, personas, skills, MCP servers, cycles, repositories, runs, experiments, batches, brands, tags, actions, dashboards, provider keys, billing, usage, statistics, queries, and local configuration.

```bash theme={null}
gauge --help
gauge runs --help
gauge runs fork --help
```