# CLI reference

## Which command?

### Onboarding & setup

| User question | Command | Output |
|---------------|---------|--------|
| "What is this repo?" | `sruja quickstart -r .` | Structural overview, scan findings, optional baseline |
| "Give me a complete architecture brief" | `sruja onboard -r .` | Full repo brief with trust signals |
| "I'm about to work on X" | `sruja ai -r . --task "..."` | Paste-ready AI coding brief |
| "Set me up" | `sruja init -r .` | `.sruja/`, `.srujaignore`, optional prompt |

*See [feature tightening](#feature-tightening-phase-t) for canonical workflow paths*

### Health & status

| User question | Command | Output |
|---------------|---------|--------|
| "Is my `repo.sruja` current?" | `sruja status -r .` | Truth freshness + baseline state |
| "Is my `repo.sruja` current?" (alias) | `sruja doctor -r .` | Same as `status` |
| "Are there structural problems?" | `sruja health -r .` | Architecture health score (0-100) from violations |
| "Can AI work effectively here?" | `sruja context-score -r .` | AI-readiness score (0-100) |
| "What should I do today?" | `sruja review -r .` | Action list from evidence refresh (`daily` alias) |

### Retrieval ladder

| Step | Command | When to use |
|------|---------|-------------|
| 1. Before starting a task | `sruja focus -r . --file <path>` | Blast radius, decisions, AI instructions |
| 2. Paste-ready AI brief | `sruja ai -r . --task "..."` | Share context with AI assistant |
| 3. Inside AI editor (MCP) | MCP tools | Cursor, Copilot, Claude integration |
| 4. Investigation | `sruja why "..."` / `sruja query "..."` | "Why is this like this?" |

### Discover vs onboarding

| Need | Command |
|------|---------|
| Scanner explain / repomap / question bank for AI or debugging | `sruja discover …` |
| First human read of the repo | `sruja quickstart -r .` |
| Full architecture brief | `sruja onboard -r .` |

## Stable commands

| Command | Description |
|---------|-------------|
| `sruja quickstart -r .` | First look: structural overview and baseline generation |
| `sruja onboard -r .` | Single onboarding brief (deterministic; optional LLM enrichment with `--enrich`) |
| `sruja lint <file>` | Validate `.sruja` file |
| `sruja sync -r .` | Refresh evidence and cached graph/context |
| `sruja status -r .` | Truth freshness and baseline state |
| `sruja review -r .` | Review workflow: refresh evidence, detect drift, summarize |
| `sruja drift -r . -a repo.sruja` | Declared vs actual structure |
| `sruja health -r .` | Architecture health score from violations |
| `sruja context-score -r .` | AI-readiness score (0-100) |
| `sruja publish -r .` | Export repo bundle for federation |
| `sruja compose -i <bundle.json> -o system.index.json` | Compose bundles into a system index |

## Other commands

| Command | Description |
|---------|-------------|
| `sruja export json <file>` | Export to JSON |
| `sruja export markdown <file>` | Export to Markdown |
| `sruja export mermaid <file>` | Export to Mermaid |
| `sruja fmt <file>` | Format DSL |
| `sruja tree <file>` | Print element tree |
| `sruja watch -r .` | Keep feedback live while coding |
| `sruja doctor -r .` | Alias for `status` |
| `sruja drift --ci -r .` | CI drift check (GitHub Actions annotations) |
| `sruja baseline -r .` | Snapshot violations for baseline ignore in CI |
| `sruja ai -r . --task "..."` | Paste-ready AI coding brief (optional `--enrich` / `--enrich-cmd`) |
| `sruja focus -r . --file <path>` | Context briefing before starting work |
| `sruja why "..."` | Investigate architecture decisions |
| `sruja query "..."` | Query registry for elements and relationships |
| `sruja ai-context -r .` | Structured context for AI editor integration |
| `sruja ai-context -r . -f for-ai --cache-friendly` | Prompt-cache-friendly JSON (invariant → tools → volatile; single repo) |

**Repo root:** Prefer `-r` / `--repo` for the repository directory. Some commands also accept `--path` as an alias for backwards compatibility.

## JSON output: metric hints

When `-f json` (or the command’s JSON mode) is used, some commands add stable **`metric_type`** and **`metric_description`** fields so parsers and dashboards do not confuse different scores:

| Command | `metric_type` | Role |
|---------|---------------|------|
| `sruja status -f json` | `truth_freshness` | Baseline / sync / truth status (not structural health alone) |
| `sruja health -f json` | `structural_health` | Violations vs declared `repo.sruja` (0–100) |
| `sruja context-score -f json` | `ai_readiness` | AI preparedness (0–100) |
| `sruja learn -f json` | *(see `artifact_kind`)* | `artifact_kind` is `learned_hypothesis` — not reviewed DSL truth |

## Aliases

- `start` = `init` (setup only)
- `daily` = `review`
- `overview` = `quickstart`
- `doctor` = `status`

## Feature Tightening (Phase T)

As part of feature tightening (Phase T), Sruja provides canonical paths for core workflows to reduce toolbox feeling:

| Workflow | Canonical Command | Deprecated Alternatives |
|----------|-------------------|-------------------------|
| Onboarding | `sruja onboard` | `discover explain` |
| Health Check | `sruja status` / `doctor` | `health` |
| Retrieval | `sruja focus` / MCP focus briefing | `get_architecture_context`, `get_hydrated_context` |
| Drift Gate | `sruja drift`, `sruja drift-pr` | deprecated `check` |

MCP tool profiles (`minimal`, `coding`, `arch`, `full`) control which tools are available via MCP. The default `coding` profile provides 15 tools focused on coding workflows.

Run `sruja --help` for full options.
