# airgen-cli Requirements engineering from the command line. Manage requirements, architecture diagrams, traceability, baselines, and more — all from your terminal. Pairs with [AIRGen Studio](https://airgen.studio) and the AIRGen MCP server. ## Install ```bash npm install -g airgen-cli ``` ## Configuration Set credentials via environment variables or `~/.airgenrc`: ```bash # Environment variables export AIRGEN_API_URL=https://api.airgen.studio/api export AIRGEN_EMAIL=you@example.com export AIRGEN_PASSWORD=your-password ``` Or create `~/.airgenrc`: ```json { "apiUrl": "https://api.airgen.studio/api", "email": "you@example.com", "password": "your-password" } ``` For semantic linting, also set a UHT token: ```bash export UHT_API_KEY=your-token # or UHT_TOKEN ``` ## Quick start ```bash # List your tenants and projects airgen tenants list airgen projects list my-tenant # List requirements airgen reqs list my-tenant my-project # Render a diagram in the terminal airgen diag list my-tenant my-project airgen diag render my-tenant my-project diagram-123 # Run semantic lint airgen lint my-tenant my-project # Get a compliance report airgen report compliance my-tenant my-project ``` ## Global options | Flag | Description | |---|---| | `--json` | Output as JSON (works with any command) | | `-V, --version` | Print version | | `-h, --help` | Show help | ## Commands ### Tenants & Projects ```bash airgen tenants list # List all tenants airgen projects list # List projects in a tenant airgen projects create --name "X" # Create a project airgen projects delete # Delete a project ``` ### Requirements ```bash airgen reqs list # List (paginated) airgen reqs list --page 2 --limit 50 airgen reqs get # Full detail airgen reqs create --text "The system shall..." airgen reqs update --text "..." --tags safety,critical airgen reqs delete # Soft-delete airgen reqs history # Version history airgen reqs search --query "thermal" --mode semantic airgen reqs filter --pattern functional --tag safety ``` ### Architecture Diagrams ```bash airgen diag list # List diagrams airgen diag get # Blocks + connectors JSON airgen diag render # Terminal display (default) airgen diag render --format mermaid # Mermaid syntax airgen diag render --format mermaid --wrap -o diagram.md airgen diag create --name "X" --view block airgen diag update --name "Y" airgen diag delete ``` **Blocks:** ```bash airgen diag blocks library airgen diag blocks create --diagram --name "X" --kind subsystem airgen diag blocks delete

``` **Connectors:** ```bash airgen diag conn create --diagram --source --target --kind flow --label "data" airgen diag conn delete

--diagram ``` ### Traceability ```bash airgen trace list # List trace links airgen trace create --source --target --type derives airgen trace delete

airgen trace linksets list # Document linksets ``` ### Baselines & Diff ```bash airgen bl list airgen bl create --name "v1.0" airgen bl compare --from --to # Rich diff between baselines airgen diff --from --to # Pretty terminal output airgen diff --from --to --json # Structured JSON airgen diff --from --to --format markdown -o diff.md ``` `diff` shows added, modified, and removed requirements with full text, plus a summary of changes to documents, trace links, diagrams, blocks, and connectors. ### Quality & AI ```bash airgen qa analyze "The system shall..." # Analyze single requirement airgen qa score start # Background QA scoring airgen qa draft "user needs thermal imaging" # Draft requirements from NL airgen ai generate --prompt "..." # Generate candidates airgen ai candidates # List pending candidates airgen ai accept # Promote to requirement airgen ai reject # Reject candidate ``` ### Reports ```bash airgen report stats # Overview statistics airgen report quality # QA score summary airgen report compliance # Compliance + impl status airgen report orphans # Untraced requirements ``` All report commands auto-paginate through the full requirement set (up to 5000). ### Implementation Tracking ```bash airgen impl status --status implemented --notes "done in v2" airgen impl summary # Coverage breakdown airgen impl list --status blocked # Filter by status airgen impl bulk-update --file updates.json # Artifact linking airgen impl link --type file --path src/engine.ts airgen impl unlink --artifact ``` **Statuses:** `not_started`, `in_progress`, `implemented`, `verified`, `blocked` **Bulk update file format:** ```json [ { "ref": "REQ-001", "status": "implemented", "notes": "shipped" }, { "ref": "REQ-002", "status": "in_progress" } ] ``` ### Verification Manage verification activities, evidence, documents, and run the verification engine to detect gaps. ```bash # Run the verification engine airgen verify run # Coverage report + findings airgen verify matrix # Cross-reference matrix # Activities (TADI: Test, Analysis, Demonstration, Inspection) airgen verify act list airgen verify act create

--method Test --title "..." airgen verify act update --status passed # Evidence airgen verify ev list airgen verify ev add

--type test_result --title "..." --verdict pass --recorded-by "name" # Verification documents airgen verify docs list airgen verify docs create --name "Test Plan" --kind test_plan airgen verify docs status --status approved airgen verify docs revisions airgen verify docs revise --rev 1.0 --change "Final review" --by "name" ``` **Activity statuses:** `planned`, `in_progress`, `executed`, `passed`, `failed`, `blocked` **Evidence verdicts:** `pass`, `fail`, `inconclusive`, `not_applicable` **Document kinds:** `test_plan`, `test_procedure`, `test_report`, `analysis_report`, `inspection_checklist`, `demonstration_protocol` **Document statuses:** `draft`, `review`, `approved`, `superseded` ### Import / Export ```bash airgen import requirements --file reqs.csv airgen export requirements # Markdown airgen export requirements --json # JSON ``` ### Activity ```bash airgen activity list # Recent activity airgen activity list --limit 50 ``` ### Documents ```bash airgen docs list airgen docs get airgen docs create --title "X" --kind structured airgen docs delete airgen docs export # Markdown export airgen docs sec list # List sections ``` ### Semantic Lint Classifies domain concepts from your requirements using the [Universal Hex Taxonomy](https://universalhex.org) and flags ontological issues, structural problems, and coverage gaps. ```bash airgen lint # Full lint (top 15 concepts) airgen lint --concepts 20 # Classify more concepts airgen lint --format markdown -o lint-report.md airgen lint --format json # Machine-readable ``` **What it detects:** - Ontological mismatches (e.g., non-physical entity with physical constraints) - Abstract metrics missing statistical parameters - Verification requirements mixed with functional requirements - Degraded modes without performance criteria - Ontological ambiguity between similar concepts - Requirements lacking "shall" keyword **Requires:** `UHT_TOKEN` or `UHT_API_KEY` environment variable. Get a token at [universalhex.org](https://universalhex.org). ## JSON mode Append `--json` to any command for machine-readable output: ```bash airgen reqs list my-tenant my-project --json | jq '.[].ref' airgen report compliance my-tenant my-project --json | jq '.summary' ``` ## Aliases | Full command | Alias | |---|---| | `requirements` | `reqs` | | `diagrams` | `diag` | | `documents` | `docs` | | `connectors` | `conn` | | `baselines` | `bl` | | `traces` | `trace` | | `quality` | `qa` | | `reports` | `report` | | `projects` | `proj` | | `sections` | `sec` | | `verify activities` | `verify act` | | `verify evidence` | `verify ev` | | `verify documents` | `verify docs` | ## License MIT