Auto-generated from CLI schema. See CLI Reference for flag tables.
Traditional approach: read generated Markdown, parse it mentally, hope it's current. This CLI queries the same annotated sources that generate those docs -- in real time, with typed output.
| Approach | Context Cost | Accuracy | Speed |
|---|---|---|---|
| Parse generated Markdown | High | Snapshot at gen time | Slow |
| Data API CLI | Low | Real-time from source | Instant |
The CLI has two output modes:
- Text commands (6) -- formatted for terminal reading or AI context. Use
===section markers for structure. - JSON commands (12+) -- wrapped in a
QueryResultenvelope. Pipeable tojq.
Run process-api --help for the full command reference with all flags and 26 available API methods.
The recommended session startup is three commands:
pnpm process:query -- overview
pnpm process:query -- scope-validate MyPattern implement
pnpm process:query -- context MyPattern --session implementExample overview output:
=== PROGRESS ===
318 patterns (224 completed, 47 active, 47 planned) = 70%
=== ACTIVE PHASES ===
Phase 24: ProcessStateAPIRelationshipQueries (1 active)
Phase 25: DataAPIStubIntegration (1 active)
=== BLOCKING ===
StepLintExtendedRules blocked by: StepLintVitestCucumber
=== DATA API ===
pnpm process:query -- <subcommand>
overview, context, scope-validate, dep-tree, list, stubs, files, rules, arch blocking
The --session flag tailors output to what you need right now:
| Type | Includes | When to Use |
|---|---|---|
planning |
Pattern metadata and spec file only | Creating a new roadmap spec |
design |
Full: metadata, stubs, deps, deliverables | Making architectural decisions |
implement |
Focused: deliverables, FSM state, test files | Writing code from an existing spec |
Decision tree: Starting to code? implement. Complex decisions? design. New pattern? planning. Not sure? Run overview first.
These 6 commands output structured text (not JSON). They are designed for terminal reading and AI context consumption.
Executive summary: progress percentage, active phases, blocking patterns, and a CLI cheat sheet.
pnpm process:query -- overviewExample output:
=== PROGRESS ===
318 patterns (224 completed, 47 active, 47 planned) = 70%
=== ACTIVE PHASES ===
Phase 24: ProcessStateAPIRelationshipQueries (1 active)
Phase 25: DataAPIStubIntegration (1 active)
=== BLOCKING ===
StepLintExtendedRules blocked by: StepLintVitestCucumber
=== DATA API — Use Instead of Explore Agents ===
pnpm process:query -- <subcommand>
overview, context, scope-validate, dep-tree, list, stubs, files, rules, arch blocking
Highest-impact command. Pre-flight readiness check that prevents wasted sessions. Returns a PASS/BLOCKED/WARN verdict covering: dependency completion, deliverable definitions, FSM transition validity, and design decisions.
pnpm process:query -- scope-validate MyPattern implementChecks: dependency completion, deliverable definitions, FSM transition validity, design decisions, executable spec location. Valid session types for scope-validate: implement, design.
Example output:
=== SCOPE VALIDATION: DataAPIDesignSessionSupport (implement) ===
=== CHECKLIST ===
[PASS] Dependencies completed: 2/2 completed
[PASS] Deliverables defined: 4 deliverable(s) found
[BLOCKED] FSM allows transition: completed → active is not valid.
[WARN] Design decisions recorded: No PDR/AD references found in stubs
=== VERDICT ===
BLOCKED: 1 blocker(s) prevent implement session
Curated context bundle tailored to session type.
pnpm process:query -- context MyPattern --session designExample output:
=== PATTERN: ContextAssemblerImpl ===
Status: active | Category: pattern
## ContextAssembler — Session-Oriented Context Bundle Builder
Pure function composition over MasterDataset.
File: src/api/context-assembler.ts
=== DEPENDENCIES ===
[active] ProcessStateAPI (implementation) src/api/process-state.ts
[completed] MasterDataset (implementation) src/validation-schemas/master-dataset.ts
=== CONSUMERS ===
ContextFormatterImpl (active)
ProcessAPICLIImpl (active)
=== ARCHITECTURE (context: api) ===
MasterDataset (completed, read-model)
ProcessStateAPI (active, service)
...
Dependency chain with status indicators. Shows what a pattern depends on, recursively.
pnpm process:query -- dep-tree MyPatternUse --depth to limit recursion depth: pnpm process:query -- dep-tree MyPattern --depth 2.
File reading list with implementation paths. Use --related to include architecture neighbors.
pnpm process:query -- files MyPattern --relatedExample output:
=== PRIMARY ===
src/cli/process-api.ts
=== ARCHITECTURE NEIGHBORS ===
src/cli/version.ts
src/cli/output-pipeline.ts
src/cli/error-handler.ts
Captures session-end state: deliverable statuses, blockers, and modification date.
pnpm process:query -- handoff --pattern MyPatternUse --git to include recent commits. Use --session to tag the handoff with a session id.
Example output:
=== HANDOFF: DataAPIDesignSessionSupport (review) ===
Date: 2026-02-21 | Status: completed
=== COMPLETED ===
[x] Scope validation logic (src/api/scope-validator.ts)
[x] Handoff document generator (src/api/handoff-generator.ts)
=== BLOCKERS ===
None
These commands output JSON wrapped in a QueryResult envelope.
Status counts and completion percentage.
pnpm process:query -- statusOutput: { counts: { completed, active, planned, total }, completionPercentage, distribution }
Filtered pattern listing. Composable with output modifiers and list filters.
pnpm process:query -- list --status roadmap --names-onlySee Output Modifiers and List Filters for all options. Examples: list --status active --count, list --phase 25 --fields patternName,status,file.
Fuzzy name search with match scores. Suggests close matches when a pattern is not found.
pnpm process:query -- search EventStoreFull detail for one pattern including deliverables, dependencies, and all relationship fields.
pnpm process:query -- pattern TransformDatasetWarning: Completed patterns can produce ~66KB of output. Prefer context --session for interactive sessions.
Design stubs with target paths and resolution status.
pnpm process:query -- stubs MyPatternUse --unresolved to show only stubs missing target files: pnpm process:query -- stubs --unresolved.
AD-N design decisions extracted from stub descriptions.
pnpm process:query -- decisions MyPatternNote: Returns exit code 1 when no decisions are found (unlike list/search which return empty arrays).
Cross-reference patterns mentioning a PDR number.
pnpm process:query -- pdr 1Note: Returns exit code 1 when no PDR references are found, same as decisions.
Business rules and invariants extracted from Gherkin Rule: blocks, grouped by product area, phase, and feature.
pnpm process:query -- rules --pattern ProcessGuardDeciderWarning: Unfiltered rules output can exceed 600KB. Always use --pattern or --product-area filters. Output shape: { productAreas: [{ productArea, ruleCount, invariantCount, phases: [{ phase, features: [{ pattern, source, rules }] }] }], totalRules, totalInvariants }
All architecture queries output JSON. They use @libar-docs-arch-* annotations.
All arch-roles with pattern counts
pnpm process:query -- arch rolesAll bounded contexts
pnpm process:query -- arch contextPatterns in one bounded context
pnpm process:query -- arch context scannerAll architecture layers
pnpm process:query -- arch layerPatterns in one layer
pnpm process:query -- arch layer domainUses, usedBy, dependsOn, same-context
pnpm process:query -- arch neighborhood EventStoreCross-context shared deps + integration
pnpm process:query -- arch compare scanner codecAnnotation completeness across input files
pnpm process:query -- arch coverageBroken references (names that don't exist)
pnpm process:query -- arch danglingPatterns with no relationships (isolated)
pnpm process:query -- arch orphansPatterns blocked by incomplete deps
pnpm process:query -- arch blockingTag usage report — counts per tag and value across all annotated sources.
pnpm process:query -- tagsFile inventory by type (TypeScript, Gherkin, Stubs, Decisions).
pnpm process:query -- sourcesTypeScript files missing the @libar-docs opt-in marker. Use --path to scope to a directory.
pnpm process:query -- unannotated --path src/typesExecute any of the 26 query API methods directly by name. This is the escape hatch for methods not exposed as dedicated subcommands.
pnpm process:query -- query getStatusCountsInteger-like arguments are automatically coerced to numbers. Run process-api --help for the full list of available API methods. Examples: query isValidTransition roadmap active, query getPatternsByPhase 18, query getRecentlyCompleted 5.
Frequently-used command sequences for daily workflow.
The recommended session startup is three commands.
pnpm process:query -- overview # project health
pnpm process:query -- scope-validate MyPattern implement # pre-flight
pnpm process:query -- context MyPattern --session implement # curated contextDiscover available patterns, blockers, and missing implementations.
pnpm process:query -- list --status roadmap --names-only # available patterns
pnpm process:query -- arch blocking # stuck patterns
pnpm process:query -- stubs --unresolved # missing implementationsDeep-dive into a specific pattern: search, dependencies, neighbors, and files.
pnpm process:query -- search EventStore # fuzzy name search
pnpm process:query -- dep-tree MyPattern --depth 2 # dependency chain
pnpm process:query -- arch neighborhood MyPattern # what it touches
pnpm process:query -- files MyPattern --related # file pathsGather full context, design decisions, and stubs before a design session.
pnpm process:query -- context MyPattern --session design # full context
pnpm process:query -- decisions MyPattern # design decisions
pnpm process:query -- stubs MyPattern # existing stubsCapture session-end state for continuity.
pnpm process:query -- handoff --pattern MyPattern # capture state
pnpm process:query -- handoff --pattern MyPattern --git # include commits