Nomos OS Docs

Appearance

Nomos CLI Command Reference ​

The nomos CLI is the compiled Go execution engine governing local developer workspaces, task state machines, AST code quality gates, and multi-repo GitOps lifecycles.

🏛️ CLI Architecture & Core Invariants ​

  • State Machine Isolation: All mutations to SQLite state (nomos_global.db, nomos_local.db) execute strictly through deterministic CLI commands.
  • Phase Discipline: Workspaces operate under four procedural phases (IDLE, PLAN, EDIT, REVIEW). Code modifications are cryptographically blocked outside transient worktrees in the EDIT phase.
  • Cognitive Load Index (CLI): Tasks are scored by Context Burden (1–5) and Logic Depth (1–5), guiding autonomous AI delegation vs. human-in-the-loop review.

🛠️ Complete Command Suites (29 Suites) ​

1. Task Lifecycle Management (nomos task) ​

Manage the lifecycle of engineering units from triage to atomic production release.

  • nomos task create "<Title>" -F plan.md --burden <1-5> --label "<tags>" [--plane <substrate|intent|membrane|infra>]: Scaffolds a new backlog item in SQLite with explicit Dual-Core plane classification.
  • nomos task start <KEY>: Claims task, snapshots root diffs, scaffolds an isolated transient worktree (worktrees/<repo>-<task>), and enters PLAN phase.
  • nomos task transition <PHASE>: Changes workspace phase (PLAN $\rightarrow$ EDIT $\rightarrow$ REVIEW $\rightarrow$ IDLE). Use --override=surgical for hotfixes $\le 3$ lines.
  • nomos task approve [KEY]: Approves active plan or walkthrough, advances phase state, and generates a timestamped PO authorization token (15-minute TTL) required for release sync.
  • nomos task edit <KEY> [--status <STATUS>] [--parent <PARENT_KEY>] [--plane <PLANE>]: Modifies task metadata, execution plane, or promotes hierarchy.
  • nomos task next [--cycle] [--leaf] [--project <NAME>] [-g/--global] [--limit <N>] [--json]: Surfaces the next highest-priority executable task or Cycle using the multi-dimensional priority scoring engine (Severity, Layer, Type, Cycle bonus), prioritizing thematic batches to accelerate backlog burndown. Filters root units by default; use --leaf to surface individual standalone subtasks.
  • nomos task split <KEY> [--dry-run]: Atomically decomposes a cross-layer task into Single-Layer Responsibility units (Subtask A on Substrate Go engine, Subtask B on Intent specs/docs), wires a BlockedBy dependency from Subtask B to Subtask A, and links an enclosing parent Cycle.
  • nomos plan [--json] [--no-bundle] [--bundle] [--dry-run] [--project <NAME>]: Performs deterministic backlog triage, running automated topological cycle clustering, stale task pruning, single-layer boundary auditing, and cosine duplicate detection.
  • nomos task bundle [--dry-run]: Executes the heuristic CPM task clustering engine to group cohesive tasks into parent Cycles.
  • nomos task sync --approve -F walkthrough.md: Validates PO authorization token, executes 36 Definition of Done (DoD) verification gates, signs commit payload, fast-forward merges feature branch, and tears down worktree.
  • nomos task list / nomos task ls [-u] [-b] [-r] [-C] [-t <1|2>] [--cli <low|med|high>] [-a] [-p <NAME>] [--json] [--show-remedy] [--show-closed]: Lists active tasks and backlog items across projects (-u / --unblocked shows executable frontier tasks with no open blockers; -b / --blocked shows tasks waiting on dependencies with pending blocker keys; -r / --roots shows Root Enablers sorted by blast radius; -C / --cycles shows only Cycle containers; -t / --tier <1|2> filters by intelligence tier; --cli <low|medium|high> filters by Cognitive Load Index; -a / --global shows ecosystem-wide tasks; --show-remedy includes transient auto-remediation nodes).
  • nomos task reset: Safely aborts active task, preserves uncommitted work, and cleans up transient worktrees.
  • nomos task close <KEY>: Closes completed tasks directly in the SQLite tracking backend.
  • nomos task cancel <KEY>: Marks tasks as cancelled.
  • nomos task context <KEY>: Generates localized architectural context for LLM agents.
  • nomos task search "<query>": Searches tasks by title, key, or labels.
  • nomos task view <KEY>: Displays formatted task details.

2. Definition of Done Gatekeeper (nomos verify) ​

Run machine-enforced Go AST quality gates before any task can be synchronized or merged.

  • nomos verify: Runs all 36 deterministic DoD quality gates.
  • nomos verify explain [gate]: Displays mathematical formulas, criteria, bypass flags, and actionable remediation steps for quality gates.
  • nomos verify -p yin: Evaluates Substrate Engine (Go AST invariants, cyclomatic complexity $< 15$, docstring density $\ge 10%$, no magic strings, zero dead code).
  • nomos verify -p yang: Evaluates Intent Membrane (VitePress markdown structure, schema synchronization, parity audits).
  • nomos verify --type <dod|security|parity|dor|drift>: Runs targeted verification stages.
  • nomos verify --list-json: Emits verification stages and their pass/fail criteria as JSON.

3. Session Bootstrap & Health (nomos handshake, nomos health, nomos version) ​

  • nomos handshake: Initial session boot. Validates SQLite database health, syncs GitBrain subconscious memories, bootstraps go.work environment, computes deterministic top_candidates recommendations with multi-dimensional priority scores, detects active cycle containers and transient worktree inception, and queries GitBrain subconscious context.
  • nomos health (alias: nomos doctor): Executes comprehensive diagnostics on SQLite databases, git repositories and hooks, core assets, and runtime services. Supports --json for machine-readable structured output.
  • nomos version [--json] [--short]: Displays current Nomos engine SemVer release tag, runtime architecture, and build metadata.

4. Workspace Hygiene & Maintenance (nomos hygiene, nomos chore) ​

  • nomos hygiene: Vacuums SQLite databases, defragments WAL logs, prunes merged remote branches, and cleans orphaned worktrees. Triggers rolling backup check.
  • nomos chore "<Title>": Auto-scaffolds an in-place lightweight task for non-destructive documentation, CSS, or configuration updates.

5. State Machine & Phase Inspection (nomos status, nomos phase, nomos lock, nomos run) ​

  • nomos status: Displays active workspace phase, substrate lock state, active task, git branch, and hemisphere (yin vs yang).
  • nomos phase <PHASE>: Directly inspects or transitions phase tokens.
  • nomos lock acquire / nomos lock release: Acquires or releases workspace phase guards.
  • nomos hook guard [--agent <name>]: Evaluates agent tool calls against lifecycle safety policies, blocks secret file exfiltration (.env, keys), intercepts destructive Git operations (force push, hard reset, clean, branch deletion), and enforces human-in-the-loop gates across supported adapters (Google Antigravity, Claude Code, SophiaLabs Nomos Code, OpenCode/Aider).
  • nomos hook init [agent] [-w]: Scaffolds or outputs native lifecycle hook configurations for supported AI coding agents.
  • nomos hook audit [--file <path>] [--agent <name>] [--json]: Executes real-time PostToolUse AST linting, formatting (go fmt), cyclomatic complexity (< 10), and comment density (>= 10%) on modified files.

6. Disaster Recovery & SQLite Snapshots (nomos backup) ​

Point-in-time state disaster recovery using SQLite's native non-blocking VACUUM INTO.

  • nomos backup create [--name <id>] [--retention <N>]: Captures hot online snapshots of nomos_global.db, nomos_local.db, and config.yaml with PRAGMA integrity verification.
  • nomos backup list: Catalogs all available database snapshots, table counts, sizes, and integrity status.
  • nomos backup restore <snapshot_id> [-f]: Rollback-guarded state restoration from a snapshot archive.

7. Cognitive Memory & GitBrain (nomos memory) ​

  • nomos memory index: Indexes repository symbols and documentation into GitBrain high-density vector embeddings.
  • nomos memory save: Persists agent cognitive tangents and decisions into Git Notes (refs/notes/agent).

8. AST Analysis & Code Auditing (nomos ast, nomos graph, nomos audit, nomos search, nomos refactor) ​

  • nomos ast <path>: Parses Go source files and extracts exported symbol hierarchies and interface implementations.
  • nomos fix [path] [--dry-run]: Automatically applies deterministic AST rewrites including filepath.Join and fmt.Errorf %w wrapping.
  • nomos graph cycles: Audits package import trees for circular dependencies.
  • nomos graph blast-radius: Calculates transitive blast radius across packages.
  • nomos graph find-tests: Identifies test files covering modified source lines.
  • nomos audit complexity [--promote]: Flags functions with Cyclomatic Complexity $\ge 15$, with optional automatic promotion of findings into deduplicated backlog debt tasks.
  • nomos audit dead-code [--promote]: Identifies unreachable code branches and unused private declarations, supporting backlog debt promotion.
  • nomos audit imports [--promote]: Audits cross-package import boundaries and layer coupling, supporting backlog debt promotion.
  • nomos audit wires [--promote]: Audits unwired frontend DOM containers, disconnected Go HTTP routes, and dangling handlers.
  • nomos audit docstrings [--all] [--promote]: Verifies $\ge 10%$ comment density and exported symbol docstrings on modified or all repository files, with batch debt promotion.
  • nomos audit all [--promote]: Runs consolidated static analysis audit across complexity, dead code, imports, wires, magic strings, and docstrings.
  • nomos audit cruft: Computes unified codebase hygiene score (0–100).
  • nomos audit refactor: Evaluates cognitive debt scores (CDS) and structural code duplication across files.
  • nomos audit concept-drift [--dict <path>] [--json]: Audits ecosystem documentation, markdown essays, and web components for deprecated substrate terminology and concept drift.
  • nomos search "<pattern>": Performs semantic AST code and symbol searching.
  • nomos refactor: Automates structural AST optimizations and code migrations.
  • nomos fix [path] [--dry-run]: Automatically applies deterministic AST self-healing fixes, filepath normalization, and error wrapping.

9. Schema Synchronization (nomos schema) ​

  • nomos schema show <ENTITY>: Emits deterministic schema specifications for task, plan, walkthrough, commit, and triage (supporting Dual-Layer Hybrid specifications with RFC 822 Git Trailers). Pass --agent to emit machine-readable JSON schemas.
  • nomos schema cli [--dry-run]: Reflects compiled Cobra CLI AST into cli_schema.json.
  • nomos schema sync: Proactively synchronizes cli_schema.json in core assets with compiled Go CLI commands.

10. Release Engineering & Changelogs (nomos release, nomos changelog) ​

  • nomos release <patch|minor|major> [--dry-run] [--export-github]: Calculates SemVer bumps, validates DoD gates, synchronizes web portals, records releases in SQLite SSoT, and publishes GitHub Releases via gh release create.
  • nomos changelog [--json] [--export-markdown]: Emits formatted release notes from SQLite task history or exports the full Keep A Changelog document.
  • nomos changelog --diff <v1>..<v2>: Generates structured diff payloads for public portal ingestion (releases.json).

11. Substrate Telemetry & Diagnostics (nomos telemetry, nomos analytics, nomos diag) ​

  • nomos analytics [--json] [--summary]: Displays Cyberpunk ASCII HUD with path-agnostic multi-repo mesh commit velocity across configured ecosystem repositories, rolling 7-day retrospective windows with explicit calendar date ranges, burndown charts, cognitive debt metrics, closed task metrics (total_closed_tasks), and metered Tier 2 agent token telemetry (prompt, completion, total, and USD savings).
  • nomos telemetry mine [--profile <yin|yang|all>] [--flow] [--infractions] [--by-agent] [--global] [--task <KEY>] [--limit <N>] [--json]: Mines execution traces and telemetry datasets to surface friction points, failing Definition of Done (DoD) verification gates, repetitive command bottlenecks, Intent ⇄ Substrate transduction flow impedance (Mean Loops to Green, AST Bounce Rate, Tool Thrashing Index, Phase Discipline Collisions, Topological Bleed), and Agent Governance Compliance HUD (attempted self-approvals, forbidden phase edits, blocked destructive commands, secret exfiltration attempts). Profile views isolate Substrate AST gates (yin) vs Cognitive Agent flow (yang).
  • nomos diag: Generates low-level repository hygiene and Go module diagnostic reports.

12. Workspace Configuration & Substrate Info (nomos config, nomos substrate) ​

  • nomos config: Inspects resolved project and global configuration YAML settings.
  • nomos substrate: Displays runtime engine details, compiler toolchain, and architecture invariants.

13. Interactive Environments & Shell (nomos shell, nomos explore, nomos plugin, nomos completion) ​

  • nomos shell: Launches an interactive shell initialized with Nomos environment variables.
  • nomos explore: Opens an interactive terminal cognitive playground.
  • nomos plugin <name>: Invokes dynamically discovered CLI plugins.
  • nomos completion <bash|zsh|fish|powershell>: Generates shell auto-completion scripts.

14. Living Vault SSoT Compiler & Parity Engine (nomos vault) ​

  • nomos vault compile [--portal-dir <path>] [--vault-dir <path>] [--skip-docs]: Executes full Living Vault SSoT compilation, mirroring handbook articles and dispatches into public web portals, synchronizing VitePress docs, and validating 100% SHA-256 byte parity.
  • nomos vault sync [--portal-dir <path>] [--vault-dir <path>]: Mirrors handbook articles and dispatches from the Living Vault into target portal directories with automated SSoT provenance banners.
  • nomos vault check [--portal-dir <path>] [--vault-dir <path>]: Performs byte-level SHA-256 parity verification between the Living Vault SSoT and web portal content mirrors.

15. Autonomous AI Coding Agent & Swarm (nomos code) ​

Orchestrate autonomous Tier 2 AI coding agents, reasoning loops, SWE-bench evaluations, and swarm burndowns.

  • nomos code <KEY> (or nomos code run <KEY>): Launches the autonomous coding worker in an isolated transient worktree to execute the task through the 5-stage TDD loop.
  • nomos code plan <KEY>: Runs the autonomous planning agent in read-only PLAN phase.
  • nomos code review <KEY>: Runs the autonomous verification and red-team agent in REVIEW phase.
  • nomos code status: Displays active autonomous worker status, PID, and turn progression.
  • nomos code logs [task-key]: Streams real-time output from running autonomous workers.
  • nomos code stop [task-key]: Terminates running autonomous worker processes.
  • nomos code fleet: Inspects active worker pool and multi-agent concurrency.
  • nomos code burndown [cycle-key]: Executes an end-to-end multi-task cycle burndown across subtasks.
  • nomos code bench [--suite <swebench|aider|livecode|nomos>]: Runs benchmark evaluation suites.
  • nomos code health: Verifies connectivity to configured LLM inference providers (Gemini, Anthropic, OpenAI, Ollama).

16. Authentication & Sovereign Licensing (nomos auth) ​

Manage terminal-first authentication, verify offline cryptographic Ed25519 licenses, and inspect sovereign subscription tiers.

  • nomos auth status: Displays formatted authentication state, license tier (Community, Pro, Sovereign), expiration date, and 14-day offline grace quota.
  • nomos auth login [--token <JWT>]: Performs terminal-first device login or directly saves an offline license token to ~/.nomos/data/auth.json.
  • nomos auth logout: Clears locally persisted credentials and switches back to the Community open-core baseline.