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

# Commands Reference

> Top-level reference for every rbtk command group. One-line summaries with links to deep-dive pages.

# Commands

`rbtk` organises commands into groups. This page is the index; each group has its own deep-dive page with full flag tables and examples.

Run `rbtk --help` for a live tree, or `rbtk <group> --help` to drill in.

## Global flags

These flags work on every command.

| Flag                         | Default                         | Description                                               |
| ---------------------------- | ------------------------------- | --------------------------------------------------------- |
| `--output table\|json\|yaml` | `table` (TTY), `json` (non-TTY) | Output format. See [Output formats](/cli/output-formats). |
| `--project <slug>`           | from context                    | Override the project for this invocation.                 |
| `--org <slug>`               | from context                    | Override the org for this invocation.                     |
| `--api-key <key>`            | from env / keyring              | Override the API key for this invocation.                 |
| `--debug`                    | off                             | Print HTTP requests, response status, and timing.         |
| `--quiet`                    | off                             | Suppress progress and informational lines.                |
| `--no-color`                 | off                             | Disable ANSI colour output.                               |

## Command groups

| Group               | What it does                                                                       | Deep dive                                                 |
| ------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------- |
| `rbtk auth`         | Log in/out, status, GitHub OIDC exchange, API key management                       | [Context & auth commands](/cli/context-commands)          |
| `rbtk context`      | Switch the active org and project; show current selection                          | [Context & auth commands](/cli/context-commands)          |
| `rbtk test`         | Run tests, watch live progress, inspect cases, fetch logs / files / evidence packs | [Test commands](/cli/test-commands)                       |
| `rbtk requirements` | Upload, list, show requirements; export and coverage reports                       | [Requirements commands](/cli/requirements-commands)       |
| `rbtk github`       | Link/unlink repos, show GitHub App status                                          | [GitHub commands](/cli/github-commands)                   |
| `rbtk pool`         | List, create, delete pools; register runners; per-pool stats                       | [Pool commands](/cli/pool-commands)                       |
| `rbtk log`          | Stream test-run logs in real time                                                  | [Test commands → logs](/cli/test-commands#rbtk-test-logs) |
| `rbtk org`          | List, get orgs you can access                                                      | covered in [Context & auth](/cli/context-commands)        |
| `rbtk project`      | List, get projects in the current org                                              | covered in [Context & auth](/cli/context-commands)        |

## Recipes by intent

| Goal                                 | Command                                                                                  |
| ------------------------------------ | ---------------------------------------------------------------------------------------- |
| Run my repo's tests once             | `rbtk test run --push ./`                                                                |
| Run on hosted Gazebo GPU             | `rbtk test cloud --pool hosted-gazebo-gpu --push ./`                                     |
| Watch a queued run go live           | `rbtk test watch <run-id>`                                                               |
| List test cases that ran             | `rbtk test cases <run-id>`                                                               |
| Download a single test's artifacts   | `rbtk test files <run-id> --nodeid "tests/test_x.py::test_y" --download --out ./test_y/` |
| Pull the latest evidence pack        | `rbtk test evidence-pack latest --out ./evidence/`                                       |
| Upload a ReqIF file                  | `rbtk requirements upload reqs.reqif`                                                    |
| See which requirements are uncovered | `rbtk requirements coverage --filter uncovered`                                          |
| Tail logs of a running test          | `rbtk log <run-id>`                                                                      |
| Create a self-hosted pool            | `rbtk pool create --name gpu-prod --type self-hosted`                                    |
| Mint a runner registration token     | `rbtk pool register-runner --pool gpu-prod`                                              |
| Switch project                       | `rbtk context set --project warehouse`                                                   |

## Exit codes

| Code | Meaning                                             |
| ---- | --------------------------------------------------- |
| `0`  | Success                                             |
| `1`  | Generic failure (logic error, API error)            |
| `2`  | Bad CLI invocation (unknown flag, missing arg)      |
| `3`  | Authentication failure                              |
| `4`  | Authorization failure (wrong scope, no access)      |
| `5`  | Resource not found                                  |
| `6`  | Validation failure (e.g., ReqIF malformed)          |
| `7`  | Test run finished but failed (`rbtk test run` etc.) |
| `8`  | Pool / runner offline or unavailable                |

Use these in shell scripts:

```bash theme={null}
rbtk test run --push ./ --wait || exit_code=$?
case $exit_code in
  0) echo "PASS" ;;
  7) echo "Tests failed"; exit 1 ;;
  *) echo "Infrastructure error ($exit_code)"; exit 2 ;;
esac
```

## Where to go next

<CardGroup cols={2}>
  <Card title="Test commands" icon="flask-vial" href="/cli/test-commands">
    The largest group — run, list, results, logs, artifacts.
  </Card>

  <Card title="Requirements" icon="file-import" href="/cli/requirements-commands">
    Upload, coverage, export.
  </Card>

  <Card title="Pool commands" icon="layer-group" href="/cli/pool-commands">
    Operate runner pools from the CLI.
  </Card>

  <Card title="Output formats" icon="table" href="/cli/output-formats">
    JSON, YAML, sparkline tables, ID-only piping.
  </Card>
</CardGroup>