Skip to content
Maina

Getting Started

Terminal window
curl -fsSL https://api.mainahq.com/install | bash

That’s the whole install. No API key. No login. No Docker. Installs maina globally so the AI agents in your editor can shell out to it — the script fails loudly (distinct exit codes for no-package-manager / install-failed / PATH-missing) rather than pretending everything worked.

In under 60 seconds maina setup detects your stack, writes a constitution tailored to your repo, wires up every AI coding tool you have installed, seeds a searchable codebase wiki in the background, and runs maina verify to surface a real finding inline.

Alternate install paths

If you already have a package manager on PATH, a global install works too:

Terminal window
bun  add -g @mainahq/cli
pnpm add -g @mainahq/cli
npm  install -g @mainahq/cli


# One-off; setup will warn that `maina` will not be on PATH after exit,
# so AI-agent subshells won't find it. Prefer the one-liner above.
bunx @mainahq/cli@latest setup

What the wizard does

Section titled “What the wizard does”

  1. Detect — Languages, frameworks, package manager, linters, test runners, and CI system, inferred from files already in your repo. No prompts to fill out.

  2. Infer — A tailored .maina/constitution.md is generated via the host AI if you’re running inside Claude Code / Cursor / Codex, or via the anonymous Cloudflare AI Gateway if not. Bring your own key with MAINA_API_KEY (takes precedence) or OPENROUTER_API_KEY for full control. No network? Setup degrades gracefully — the offline template still includes the ## Maina Workflow and ## File Layout sections verbatim, and the reason is surfaced in the terminal and logged to .maina/setup.log with a copy-pasteable recovery line.

  3. Scaffold — Agent instruction files use non-destructive <maina-managed> regions so your existing rules stay intact:

    • AGENTS.md
    • CLAUDE.md
    • .cursor/rules/maina.mdc
    • .github/copilot-instructions.md
    • .windsurf/rules/maina.md

    Project-level MCP configs use keyed JSON merge — every existing mcpServers.* entry is preserved semantically (keys, values, array order), although JSON re-serialisation may normalise whitespace. Only the maina key is added:

    • .claude/settings.json (Claude Code)
    • .cursor/mcp.json (Cursor)

    The eight cross-platform skills are materialised into your project so any agent can read them directly:

    • .maina/skills/onboarding/SKILL.md
    • .maina/skills/verification-workflow/SKILL.md
    • .maina/skills/tdd/SKILL.md
    • .maina/skills/code-review/SKILL.md
    • .maina/skills/plan-writing/SKILL.md
    • .maina/skills/context-generation/SKILL.md
    • .maina/skills/wiki-workflow/SKILL.md
    • .maina/skills/cloud-workflow/SKILL.md

    The codebase wiki is kicked off in the background — maina setup returns immediately after seeding .maina/wiki/.progress.json. Poll progress any time with maina wiki status.

  4. Verify — maina verify runs once and surfaces one real finding inline. Now every agent on your machine — Claude Code, Cursor, Copilot, Windsurf — respects the same rules and reviews the same diff.

Zero-friction by design

Section titled “Zero-friction by design”
  • No API key required — host delegation or the anonymous gateway handles AI for the wizard.
  • No login wall — the wizard never opens a browser or asks you to create an account.
  • Non-destructive — agent files use <maina-managed> regions; your own content is preserved.
  • Resumable — re-run maina setup any time; it diffs and only writes what changed.

CI and automation

Section titled “CI and automation”
Terminal window
maina setup --ci

--ci disables all prompts and emits one JSON object per phase on stdout, making the wizard safe to drop into GitHub Actions, GitLab CI, or any provisioning script. The onboarding promise is enforced on every push via the onboarding-e2e matrix: Claude Code × TypeScript must complete in under 60 seconds, with Claude Code / Cursor × Python / Go / Rust tracked as informational cells.

Next steps

Section titled “Next steps”
Commands Every command, organized by workflow phase
MCP Server Already wired during setup — here's how it works
Configuration Model tiers, custom prompts, hooks
CI Integration Run verification on every pull request

Advanced

Section titled “Advanced”

Most users should stop at maina setup. These commands remain for power users and are kept as canonical references.

  • maina setup --update — re-tailor the constitution and agent files for the current stack. Run this after major stack changes.
  • maina setup --reset — back up .maina/ and start fresh.
  • maina setup --agents <list> — scope which agent files are written (e.g. --agents claude,cursor).
  • maina init — lower-level bootstrap used internally by the wizard. Kept for scripting and snapshot tests.
  • maina configure — Deprecated since v1.3 alias for maina setup --update. Will be removed in v1.5.

See the Full Setup reference for the long-form walkthrough, language matrix, and zero-friction layer breakdown.