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

# rbtk requirements

> Full reference for the rbtk requirements command group. Upload ReqIF/YAML/PDF, list, show, compute coverage, export.

# `rbtk requirements`

Requirements are the spine of the V-model. The CLI lets you push them in, inspect what's tracked, see what's covered, and export them back out.

```
rbtk requirements
├── upload         # Push requirements from a file
├── list           # List requirements in the current project
├── show           # Show one requirement with its confirming tests
├── coverage       # Per-requirement coverage status, gap analysis
└── export         # Export ReqIF (for round-trip back to Polarion / Jama / DOORS)
```

## `rbtk requirements upload`

Push requirements into the platform. Three input formats are accepted; the CLI sniffs by extension.

```bash theme={null}
rbtk requirements upload reqs.reqif       # ReqIF (preferred for round-trip)
rbtk requirements upload reqs.yaml        # Inline YAML
rbtk requirements upload spec.pdf         # PDF — extracted via LLM, requires Team+
```

| Flag                          | Description                                                                                                                     |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `--mode add\|update\|replace` | `add` only inserts new; `update` upserts; `replace` mirrors the file (anything not in the file is archived). Default: `update`. |
| `--dry-run`                   | Show what would change without writing.                                                                                         |
| `--release <tag>`             | Snapshot the post-upload state under this release tag for evidence.                                                             |
| `--baseline <name>`           | Use this requirement baseline instead of the default.                                                                           |
| `--field-map <file>`          | YAML field-mapping when uploading from a non-standard ReqIF (e.g., Polarion exports).                                           |

### Examples

```bash theme={null}
# CI integration after a Jama export
rbtk requirements upload jama-export.reqif --mode update --release ${GITHUB_REF_NAME}

# Pre-flight a YAML edit
rbtk requirements upload reqs.yaml --dry-run --output json | jq '.changes'

# Polarion field-mapping override
rbtk requirements upload polarion.reqif --field-map ./roboticks/polarion-mapping.yaml
```

ReqIF round-trip caveats live on each RM connector page — see [Jama](/integrations/jama), [Polarion](/integrations/polarion), [codeBeamer](/integrations/codebeamer), [DOORS](/integrations/doors).

## `rbtk requirements list`

List requirements in the current project.

```bash theme={null}
rbtk requirements list
rbtk requirements list --type safety --status uncovered
rbtk requirements list --pinned-to iso-10218-2025 --output json
```

| Flag                                               | Description                                      |
| -------------------------------------------------- | ------------------------------------------------ |
| `--type safety\|functional\|performance\|security` | Filter by requirement type                       |
| `--status confirmed\|uncovered\|stale`             | Filter by coverage status                        |
| `--pinned-to <standard>`                           | Only requirements derived from a pinned standard |
| `--baseline <name>`                                | List a non-default baseline                      |
| `--limit N`                                        | Cap result rows (default 50)                     |

Output:

```
ID         TYPE       TITLE                                STATUS       LAST RUN
REQ-001    safety     E-stop halts motion within 100 ms    confirmed    8a1f, PASS
REQ-002    safety     Stop-on-fault                        uncovered    —
REQ-003    func       Linear velocity in deadzone          confirmed    8a1f, PASS
REQ-014    perf       Path planner < 80 ms p99             stale        8a1a (3d ago)
```

`stale` means the last confirming test ran more than `project.staleness_window` ago — set in **Project Settings → Requirements** (default 7 days).

## `rbtk requirements show`

Show one requirement with its full link graph.

```bash theme={null}
rbtk requirements show REQ-001
```

```
REQ-001  E-stop halts motion within 100 ms
─────────────────────────────────────────────────────
Type        safety
ASIL/PL     PLd
Source      iso-10218-2025 §5.7.5
Text        On assertion of the E-stop input, all actuators
            must reach a safe stop state within 100 ms, as
            measured at the wheel encoders.

CONFIRMED BY
  tests/test_estop.py::test_estop_halts_motion
    Last run: 8a1f3c2d · PASS · 84 ms p95 (under 100 ms budget)

DERIVED FROM
  ISO 10218-2:2025 §5.7.5 (pinned)

CHANGE IMPACT
  Standard amendment 2026-A1 (issued 2026-04-12) touches §5.7.5.
  Action: re-derive REQ-001 against the new edition.
```

`--output json` returns the full link graph including MCAP attachments, deadlines, and prior-run history.

## `rbtk requirements coverage`

Per-requirement coverage status and gap analysis.

```bash theme={null}
rbtk requirements coverage
rbtk requirements coverage --filter uncovered
rbtk requirements coverage --since-release v2.3.0 --output json
```

| Flag                                        | Description                                               |
| ------------------------------------------- | --------------------------------------------------------- |
| `--filter confirmed\|uncovered\|stale\|all` | Subset filter (default `all`)                             |
| `--since-release <tag>`                     | Only show changes since a prior release tag               |
| `--baseline <name>`                         | Compute against a non-default baseline                    |
| `--format compact\|matrix`                  | Compact list (default) or full requirement-by-test matrix |

Compact output:

```
COVERAGE  142 / 160 confirmed (88.75%)
DELTA     +3 confirmed, -1 uncovered, +0 stale (vs v2.3.0)

UNCOVERED (18)
  REQ-002  Stop-on-fault                       (priority: high)
  REQ-051  Tool-change interlock              (priority: high)
  ... 16 more (use --output json for full list)

STALE (4)
  REQ-014  Path planner < 80 ms p99            (last run 3d ago)
  ...
```

`--format matrix` emits a requirement-by-test grid suitable for `jq` or spreadsheet ingestion.

## `rbtk requirements export`

Export the current requirement state as ReqIF (for round-trip into your RM tool) or YAML.

```bash theme={null}
rbtk requirements export --format reqif --out reqs.reqif
rbtk requirements export --format yaml --filter type=safety --out safety-only.yaml
```

| Flag                   | Description                                              |
| ---------------------- | -------------------------------------------------------- |
| `--format reqif\|yaml` | Output format                                            |
| `--out <file>`         | Output path                                              |
| `--filter <expr>`      | Subset (e.g., `type=safety`, `pinned-to=iso-10218-2025`) |
| `--baseline <name>`    | Export a non-default baseline                            |
| `--with-coverage`      | Embed coverage status as ReqIF attributes                |

ReqIF exports are accepted by Jama, Polarion, codeBeamer, and DOORS (with ReqIF Studio for DOORS Classic). See the matching [Integrations page](/integrations/overview).

## Working with baselines

Every release tag implicitly snapshots a requirement **baseline**. Compare baselines:

```bash theme={null}
rbtk requirements list --baseline v2.4.0
rbtk requirements coverage --since-release v2.3.0
```

Baselines are immutable — your auditor can ask "what were the requirements at v2.3.0?" and you can answer to the byte.

## Next

<CardGroup cols={2}>
  <Card title="Test commands" icon="flask-vial" href="/cli/test-commands">
    Run tests, see coverage update on PRs.
  </Card>

  <Card title="GitHub App" icon="github" href="/github-app/installation">
    Auto-link PRs to requirement deltas via Check Runs.
  </Card>
</CardGroup>