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

# CLI Overview

> rbtk is the Roboticks CLI for running tests, managing requirements, configuring pools, and driving evidence packs from your terminal or CI pipeline.

# Roboticks CLI

`rbtk` is the command-line driver for the Roboticks platform. Use it to upload requirements, kick off test runs, stream logs, pull evidence packs, and operate runner pools. The dashboard is the friendliest surface for most of this; the CLI is the one you script.

The package ships **two binary names** so you can pick the one that reads best in your scripts:

* `rbtk` — short, fast to type
* `roboticks` — clear, self-documenting

They're identical entry points. Use either.

## Why a CLI in addition to the dashboard

| Job                                                   | Dashboard          | CLI                                               |
| ----------------------------------------------------- | ------------------ | ------------------------------------------------- |
| Eyeballing a traceability matrix                      | Best               | Possible (`rbtk requirements coverage`)           |
| Uploading a 4000-line ReqIF on every release          | Painful            | `rbtk requirements upload` in CI                  |
| Pulling the latest evidence pack into an audit folder | Click-and-download | `rbtk test evidence-pack <run-id> --out ./audit/` |
| Running a one-off test against a feature branch       | Possible           | `rbtk test run --push ./`                         |
| Diagnosing a runner pool from the airline lounge      | No                 | `rbtk pool runners --pool prod-gpu-farm`          |

If you're scripting against the platform, the CLI is the supported surface — the underlying REST API is versioned but not contract-stable across point releases.

## Command-group map

```
rbtk
├── auth            # login, logout, status, GitHub OIDC exchange
├── context         # current org/project selection
├── test            # run, list, results, logs, artifacts, evidence-pack
├── requirements    # upload, list, show, coverage, export
├── github          # link a repo, check link status, unlink
├── pool            # list, create, register-runner, runners, delete
├── log             # stream test-run logs
├── org             # list, get
└── project         # list, get
```

Each group has its own deep-dive page. The full reference index is at [Commands](/cli/commands).

## Quickstart

```bash theme={null}
# 1. Install
pipx install roboticks-cli

# 2. Authenticate
rbtk auth login                       # opens a browser

# 3. Pick a context
rbtk context set --org acme --project warehouse

# 4. Upload a requirement and run a test
rbtk requirements upload ./roboticks/requirements.yaml
rbtk test run --push ./

# 5. Pull the evidence pack
rbtk test evidence-pack latest --out ./evidence/
```

## Three auth modes

| Mode                              | Use case            | How                               |
| --------------------------------- | ------------------- | --------------------------------- |
| **OAuth + keyring**               | Local development   | `rbtk auth login`                 |
| **API key** (`ROBOTICKS_API_KEY`) | Generic CI, scripts | Mint in dashboard, export env var |
| **GitHub OIDC**                   | GitHub Actions      | `rbtk auth oidc-from-github`      |

See [Authentication](/cli/authentication) for the matrix.

## Output formats

All commands accept `--output table|json|yaml`. The default is `table` (pretty) for TTY, `json` for non-TTY. Pipe-friendly aliases like `--output ids` are available on list commands.

```bash theme={null}
rbtk test list --output json | jq '.[0].id'
rbtk test list --output ids
rbtk requirements list --output yaml > backup.yaml
```

See [Output formats](/cli/output-formats) for the full spec, including the sparkline column for last-N test runs.

## CI-friendly defaults

The CLI auto-detects non-TTY environments and:

* Disables progress bars and colour
* Returns non-zero exit codes on failure
* Refuses interactive prompts (set `ROBOTICKS_INTERACTIVE=true` to override)
* Emits JSON unless you ask for table

```bash theme={null}
# Force CI behaviour locally
ROBOTICKS_CI=true rbtk test run --push ./
```

## Where to go next

<CardGroup cols={2}>
  <Card title="Install" icon="download" href="/cli/installation">
    pip, pipx, or Homebrew. Python 3.10+.
  </Card>

  <Card title="Authenticate" icon="key" href="/cli/authentication">
    OAuth, API keys, GitHub OIDC.
  </Card>

  <Card title="Test commands" icon="flask-vial" href="/cli/test-commands">
    The most-used group. Run, list, results, logs, evidence-pack.
  </Card>

  <Card title="CI/CD recipes" icon="code-branch" href="/cli/ci-cd">
    GitHub Actions, GitLab CI, Jenkins, CircleCI, BuildKite.
  </Card>
</CardGroup>