@maind-dev/cli

Headless maind CLI for CI runners. Pulls stack-relevant, vetted lessons and conventions into a build before an agent runs, and emits a context manifest that records exactly which lessons were served — the attribution backbone for maind's CI feedback loop.

Unlike @maind-dev/mcp-bridge (which proxies a live stdio MCP client through a device-bound session), this CLI is a one-shot request/response tool: authenticate from an environment variable, call a few read-only maind tools, write files.

Install

npm i -g @maind-dev/cli   # or: npx @maind-dev/cli context ...

Auth

Set MAIND_API_KEY to a read-scoped CI key from https://maind.dev/keys. CI keys are device-unbound, so they work in a runner with no browser and no stable device. On a developer machine that already paired the bridge, the CLI falls back to the on-disk bridge key automatically.

export MAIND_API_KEY=mnd_xxxxxxxx_...

Usage

maind context --stack nextjs,supabase --languages typescript --tools claude-code

Writes two artifacts (defaults shown):

| File | Purpose | |---|---| | .maind/context.md | Lesson bodies + convention checklist — load this into the agent's context | | .maind/manifest.json | served lesson IDs + versions + tiers — attribution record for the run |

Options

| Flag | Default | Meaning | |---|---|---| | --stack <a,b> | — | Stack hint; seeds the platforms filter | | --platforms <a,b> | from --stack | Explicit platforms filter | | --tools <a,b> | — | Tool filter (e.g. claude-code) | | --languages <a,b> | — | Language filter | | --query <text> | stack terms | Search query | | --budget <n> | 15 | Max lessons (1–50; server caps search at 10) | | --out <path> | .maind/context.md | Context markdown output | | --manifest <path> | .maind/manifest.json | Manifest JSON output | | --run-ref <id> | $GITHUB_RUN_ID | Build identifier stored in the manifest | | --mcp-url <url> | $MAIND_MCP_URL or prod | MCP endpoint override |

Review (maind review)

Provenance-backed review findings for a change set (ADR-228). The CLI links the code-index engine directly — no bridge needed in CI: it enumerates hunk-graded changed symbols + closed-enum risk flags locally, sends only symbol names and counts to the maind review_changes tool (paths, lines, and diff content never leave the machine), and renders the citable findings (convention id + version + matched symbols).

maind review --base origin/main --comment

Artifacts (defaults shown):

| File | Purpose | |---|---| | .maind/review.md | Full findings report — always written, even fail-open | | .maind/review.json | Review manifest (maind.review.manifest/v1) — counts, citations, served attribution | | .maind/review-comment.md | With --comment: PR-comment markdown; line 1 carries the <!-- maind-review --> idempotency marker |

The CLI never posts the comment itself — your workflow posts the file via gh api, so provider tokens stay outside the CLI.

Review options

| Flag | Default | Meaning | |---|---|---| | --base <ref> | — | Review the diff against this ref; without it, uncommitted work | | --uncommitted | off | With --base: also include uncommitted changes | | --summary <text> | — | Prose change summary (enables index-less review) | | --out <path> | .maind/review.md | Report path (manifest lands next to it as .json) | | --comment [<path>] | off | Also write PR-comment markdown | | --json | off | Print the review manifest JSON to stdout | | --gate | off | Server-side pass\|warn\|block verdict (Team plan) | | --fail-on block\|warn | — | With --gate: exit 1 when the verdict crosses the threshold | | --strict | off | Infra errors exit 2 instead of failing open | | --project-key <hex> | auto | Repo project_key override | | --mcp-url <url> | $MAIND_MCP_URL or prod | MCP endpoint override |

Exit codes

| Code | Meaning | |---|---| | 0 | Advisory run (default) — findings never fail a build; plan-gate on --gate also exits 0 with a hint | | 1 | Only a server verdict crossing --fail-on (requires --gate) | | 2 | Infra error, only under --strict |

Fail-open contract

A context pull must never fail a build. On any error (missing key, network, auth) the CLI still writes explanatory artifacts (the manifest carries an error field) and exits 0. The agent simply runs without extra context. maind review follows the same contract: advisory runs exit 0 no matter what; only the explicit --gate + --fail-on combination is fail-closed.

Example: GitHub Actions

- name: Pull maind context
  run: npx @maind-dev/cli context --stack nextjs,supabase --languages typescript
  env:
    MAIND_API_KEY: ${{ secrets.MAIND_API_KEY }}

- name: Upload manifest (for outcome attribution)
  uses: actions/upload-artifact@v4
  with:
    name: maind-manifest
    path: .maind/manifest.json