CLI Reference

The microcoreos command-line interface provides the tools for project lifecycle management, offline architecture validation, and the parallel development plan pipeline.

All commands run with uv run microcoreos <command> (or microcoreos <command> with an active virtualenv).

microcoreos new <path> [--force] [--no-ai-kit]   Scaffold a new project
microcoreos add <extra> [--no-install]           Install an optional extra
microcoreos upgrade [--apply]                    Report or apply upstream framework updates
microcoreos [run] [--boot-tool <tool>]           Boot the Kernel
microcoreos dev                                  Boot Kernel with auto-reload

microcoreos check [--strict] [--format=json]     Offline Architecture CI Gate (7 checkers)
microcoreos status                               Active plan, checklist progress & manifest freshness
microcoreos plan validate [path] [--fix]         The 18 plan validity rules offline
microcoreos plan sync [path]                     Sync execution checklist from plan
microcoreos plan probe [path]                    Probe tool interactions per feature
microcoreos migrate                              Apply migrations & regenerate AI_CONTEXT.md
microcoreos schema                               Live database tables & column definitions

---

Project Lifecycle Commands

microcoreos new <path>

Scaffolds a complete MicroCoreOS project structure at the specified target directory:

• tools/, domains/system, domains/devtools, extras/, plans/, dev_infra/
• Root main.py, Dockerfile, .env.example, pyproject.toml
• AI Kit: AGENTS.md, INSTRUCTIONS_FOR_AI.md, .agent/, docs/
• Hashes baseline in .microcoreos/manifest.json to enable zero-conflict future upgrades.

Flag	Description
--force	Materialize even if tools/ or domains/ already exist
--no-ai-kit	Skip generating AI agent instruction files

microcoreos add <extra>

Installs and configures an official swappable capability in one command:

1. Adds package dependency via uv add 'microcoreos[extra]'
2. Moves source files from extras/available_* into active tools/ or domains/
3. Injects default environment variables into .env (never overwriting existing values)

uv run microcoreos add postgres
uv run microcoreos add redis
uv run microcoreos add auth

Available extras: auth, ping, postgres, redis, s3, scheduler, kafka, rabbitmq, chaos. Run microcoreos add without arguments to view available items.

microcoreos upgrade

Tracks and reconciles upstream framework updates against your project's baseline using .microcoreos/manifest.json:

uv run microcoreos upgrade          # Dry-run report (conflicts, updates, deletions)
uv run microcoreos upgrade --apply  # Apply safe non-conflicting updates

• Safe to update: You never modified the file; upstream updated it.
• Yours: You modified the file; left untouched.
• Conflict: Both you and upstream modified the file; reported without overwriting.

microcoreos run / microcoreos dev

Boots the application Kernel.

uv run microcoreos run                  # Standard boot
uv run microcoreos dev                  # Auto-reload on file changes (requires watchfiles)
uv run microcoreos run --boot-tool db   # Boot single tool in isolation (for deployments)

---

🛡️ Offline Architecture CI Gate (microcoreos check)

Runs all 7 architectural linters offline in milliseconds using AST analysis and file scans, without booting the server or opening network ports.

uv run microcoreos check
uv run microcoreos check --strict
uv run microcoreos check --format=json
uv run microcoreos check --checker route_collisions

The 7 Checkers

1. discovery_naming: Verifies that classes inheriting BaseTool reside in *_tool.py files, classes inheriting BasePlugin reside in *_plugin.py, and test files follow proper naming conventions to avoid collisions.
2. domain_isolation: Enforces zero cross-domain imports (ast.Import and ast.ImportFrom) and forbids hardcoded import tools.* in plugin code (forcing dependency injection via __init__).
3. event_contracts: Matches statically known publish() payloads against subscriber payload model requirements, flagging MISSING_KEY, ORPHAN_PUBLISH, and ORPHAN_SUBSCRIBE.
4. field_divergence: Compares Pydantic Field(...) constraints across sibling plugins in the same domain to prevent accidental schema mismatches (with inline # divergence_ok: waiver support).
5. route_collisions: Verifies there are no duplicate (method, path) endpoint registrations across plugins.
6. table_ownership: Ensures single-domain write ownership per database table across SQL migrations.
7. tool_doc_drift: Ensures every public method exposed on a raw Tool instance is documented in its get_interface_description().

Options

Option	Description
--strict	Escalates warnings to exit code 1 (mandatory for CI pipelines)
--format=json	Outputs structured JSON report with findings, duration, and error counts
--checker <name>	Filters execution to a single checker

---

📋 The Plan Pipeline

Commands for managing multi-agent parallel development and declarative specifications.

microcoreos status

Pre-flight inspection: checks which plan is active in plans/active_plan.yaml, validates whether it is still the shipped template, reports checklist completion progress, and alerts if AI_CONTEXT.md is older than domain or tool source files.

microcoreos plan validate [path]

Validates the plan against the 18 mechanical plan validity rules offline (route uniqueness, table ownership, event contracts, idempotency rules for durable flows, sad-path coverage, etc.).

• Run with --fix to automatically sync the checklist before validating.

microcoreos plan sync [path]

Generates or synchronizes plans/active_plan.md from plans/active_plan.yaml, preserving existing completed checkboxes ([x]) while populating task paths for Phase 0, Phase 2, and Phase 3.

microcoreos plan probe [path]

Drives feature plugins with recording stand-in mocks to detect and print all tool method calls, ensuring actual execution matches the declared plan contract without guessing.

microcoreos migrate

Fully boots the system in memory, applies all pending database migrations (DB_AUTO_MIGRATE=true), regenerates AI_CONTEXT.md, and exits cleanly.

microcoreos schema

Uses the live database tool's describe_schema() method to print active tables, column types, and constraints in a normalized, engine-agnostic format.