Modular Chunks CLI

A command-line tool that bridges the Modular Chunks platform with your local development environment and Claude Code.

Install

cd cli
npm install
npm run build
npm link          # exposes `modular` globally

Workflow

Platform (browser)          CLI                     Claude Code
─────────────────          ─────────────────────   ──────────────────────
1. Build chunks in UI  →   2. modular init
                           3. modular pull      →   4. modular serve  (MCP)
                                                    5. [Claude builds chunk]
                           6. modular validate  →
                           7. modular sync      →   Platform sees PASS/FAIL

Commands

| Command | Description | |---------|-------------| | modular init | Set up .modular/config.json (platform URL, project ID, API token) | | modular pull | Pull approved chunk contracts from the platform into .modular/cache.json | | modular status | Show all chunks with approval and validation status | | modular show <n> | Print full agent prompt for chunk N (or 00 for project context) | | modular next | Print prompt for the next unvalidated approved chunk | | modular validate [chunk] [--dir <path>] | Run structural validation against source files | | modular sync [chunk] | POST validation results back to the platform | | modular serve | Start MCP stdio server for Claude Code |

Claude Code MCP integration

Add to your Claude Code MCP config (e.g. .claude/mcp.json):

{
  "mcpServers": {
    "modular-chunks": {
      "command": "node",
      "args": ["/path/to/cli/dist/index.js", "serve"]
    }
  }
}

Claude Code will then have access to these tools:

• get_project_context — full project brief + architecture (Chunk 00)
• list_chunks — all chunks with status
• get_current_chunk — next chunk to build
• get_chunk — any specific chunk by number or name
• mark_chunk_validated — mark pass/fail after manual review

Platform setup

The Sync to CLI button in the Assembly page (Stage 06) must be clicked first. This POSTs the current project state to /api/assembly/contracts. The CLI pull command reads from this endpoint.

Auth model — six paths, one helper

Every CLI-callable platform route runs through authenticateRequest() (server-side helper at src/lib/cli-auth.ts). The helper accepts ANY of the following — the user picks whichever fits their workflow:

| Auth path | Header | Where to set | When to use | |---|---|---|---| | API key (mc_live_…) | Authorization: Bearer mc_live_… | Generated at /auth/cli; save in .modular/config.json as apiToken | Default for modular pull / sync / autopilot. Bound to ONE project. | | Supabase JWT | Authorization: Bearer eyJ… | Issued by modular login → cached locally | Multi-project session; rotates with the user's auth state. | | Cookie session | (browser cookie) | Auto-set after /auth/login | Used by the platform UI itself; not by the CLI. | | Admin secret | X-Admin-Trigger-Secret: … | ADMIN_REGENERATE_SECRET server env | Ops scripts that need to bypass project-ownership checks. | | Bearer cron secret | Authorization: Bearer … | CRON_SECRET server env | Vercel Cron entries (/api/cron/sdlc-tick, /api/cron/autopilot-watch). | | Bearer service secret | Authorization: Bearer … | CONTRACTS_INBOUND_API_KEY (assembly write surface), STAGE4_API_TOKEN (Stage-4 dispatcher), NOTIFY_TOKEN (server-side notifications) | Service-to-service trust. |

For the routes the CLI itself hits (/api/cli/*, /api/assembly/contracts, /api/chunks/*), the API key path is the path. Generate one per project at /auth/cli, save it as apiToken in .modular/config.json, and the CLI handles the rest.

A full enumeration of every server env var (with grouping by service) lives in .env.example at the repo root.

Webhook-signature paths (not CLI-relevant)

Inbound webhooks (Inngest, LemonSqueezy, Slack, GitHub) are signature-verified against their respective *_WEBHOOK_SECRET / *_SIGNING_SECRET env vars. The CLI doesn't interact with these surfaces; they're listed for completeness.