@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 |

Detector findings (with --gate)

With --gate, the CLI also runs the four repo-health detectors from @maind/code-index on this machine — number collisions in counter-style namespaces (ADR-263-*.md twice), spec drift (a registry vs. the artefact it declares), dead theme classes (a Tailwind v4 utility pointing at a token that does not exist), and table ACL (Supabase default grants never revoked) — and sends them to review_verdict as a third finding class next to convention findings and risk flags (ADR-324).

Only a commitment leaves the machine: detector_id, detector_version, rule_id, level, baseline, an evidence_hash (sha256 over the normalised evidence) and a count. Paths, tokens, class names, table names and numbers stay local — they appear in the report (.maind/review.md) but never in the manifest, the PR comment or the wire.

Block-eligible is only a finding this branch introduces (level: open, baseline: introduced). Objective detectors (number collisions, spec drift, dead theme classes) block by default; table ACL warns, because it encodes an architecture opinion — a team policy can override either way, with a reason.

diff_stats.detector_coverage reports whether every detector ran or honestly abstained (full), whether one could not run or could not grade against the merge base (partial), or whether none ran (none). Only full keeps a run attestation-grade; partial never does — the verdict still stands. Servers before 0.48.0 ignore the section silently; the CLI detects the missing echo and says so (server_acknowledged: false in the manifest).

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

License

MAIND Client License — proprietary; free to install and use in connection with the MAIND service (maind.dev). See LICENSE. Versions up to and including 0.13.0 were published under the MIT License and remain so.