CLI agent guide
Mission
The stella CLI is the operator-facing Swiss army knife for scans, exports, policy management, offline kit operations, and automation scripting.
Active Work: CLI Consolidation (v2.x → v3.0)
The CLI is undergoing a major consolidation to improve discoverability and consistency. See:
- Advisory:
docs-archive/product/advisories/CLI_CONSOLIDATION_PROPOSAL.md - Command Mapping:
docs-archive/product/advisories/CLI_COMMAND_MAPPING.md - Migration Guide:
docs/modules/cli/guides/migration-v3.md
Consolidation Sprints
| Sprint | Scope | Status |
|---|---|---|
SPRINT_20260118_010_CLI_consolidation_foundation | Routing infrastructure, deprecation system | DONE |
SPRINT_20260118_011_CLI_settings_consolidation | stella config unified settings | DONE |
SPRINT_20260118_012_CLI_verification_consolidation | stella verify unified verification | DONE |
SPRINT_20260118_013_CLI_scanning_consolidation | stella scan unified scanning | DONE |
SPRINT_20260118_014_CLI_evidence_remaining_consolidation | Evidence, reachability, SBOM, crypto, etc. | TODO |
Key Changes
- 81+ → 18 top-level commands for discoverability
- Unified settings under
stella config(notify, feeds, registry, integrations) - Unified verification under
stella verify(attestation, vex, patch, sbom) - Compound commands split (
scangraph→scan graph) - Backward compatibility via deprecated aliases
Implementation Priorities
- Foundation (routing, deprecation) must complete first
- Sprints 011-014 can run in parallel after foundation
- All old commands kept as deprecated aliases until v3.0
- Tests must verify both old and new paths
Key docs
How to get started
- Open sprint file
/docs/implplan/SPRINT_*.mdand locate the stories referencing this module. - Review ./TASKS.md for local follow-ups and confirm status transitions (TODO → DOING → DONE/BLOCKED).
- Read the architecture and README for domain context before editing code or docs.
- Coordinate cross-module changes in the main /AGENTS.md description and through the sprint plan.
Guardrails
- Honour the Aggregation-Only Contract where applicable (see …/…/aoc/aggregation-only-contract.md).
- Preserve determinism: sort outputs, normalise timestamps (UTC ISO-8601), and avoid machine-specific artefacts.
- Keep Offline Kit parity in mind—document air-gapped workflows for any new feature.
- Update runbooks/observability assets when operational characteristics change.
- Advisory commands must default to read-only and display evidence refs with citations.
Required Reading
docs/modules/cli/README.mddocs/modules/cli/architecture.mddocs/modules/cli/implementation_plan.mddocs/modules/platform/architecture-overview.md
Working Agreement
- Update task status to
DOING/DONEin both correspoding sprint file/docs/implplan/SPRINT_*.mdand the localTASKS.mdwhen you start or finish work.
- Update task status to
- Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- Revert to
TODOif you pause the task without shipping changes; leave notes in commit/PR descriptions for context.
- Revert to