Reference · CLI

agentmako CLI reference

The agentmako CLI is the entry point for everything — attaching projects, running the MCP server, managing model providers and credentials, and inspecting state. Below is the full surface, grouped by what you reach for it for.

Quick reference

The five commands you'll use 95% of the time:

agentmako connect .              # attach the current project
agentmako doctor                 # green checks for config + service + index
agentmako mcp                    # start the stdio MCP server
agentmako tool list              # list registered tools
agentmako status                 # show project + provider state

Run any command with --help for inline flags and examples.

Project attachment

agentmako connect [path]

The first command you run in a new project. Attaches the project to Mako, indexes it, and (optionally) wires up a database connection.

# interactive — prompts for DB URL, etc.
agentmako connect .

# non-interactive (CI):
agentmako connect . --no-db
agentmako connect . --db-env DATABASE_URL --yes

Common flags:

  • --no-db — skip database wiring; you can attach a DB later with project db bind.
  • --db-env VAR — read the connection string from an environment variable instead of prompting.
  • --yes — accept all prompts. CI-friendly.
  • --name NAME — override the auto-derived project display name.

agentmako project list

Lists all attached projects. Each project is a separate Reef store keyed by canonical path.

agentmako project attach [path]

Same as connect but skips database setup entirely. Use when you want a bare attachment.

agentmako project detach [path]

Removes the project from Mako's registry. Optional flags:

  • --purge — also delete the local SQLite store under .mako-ai/.
  • --delete-secrets — also remove the project's database credentials from the OS keychain.

agentmako project index [path]

Re-runs the indexer for one project. Equivalent to the project_index_refresh tool with mode: "if_stale". Add --force for a full re-parse.

agentmako project status [path]

Prints freshness counts (indexed/dirty/missing), Reef row counts, last diagnostic run, and DB binding state.

Database

agentmako project db bind

Add or replace a database connection on an attached project. Connection strings are stored in the OS keychain; the project config holds a keychain reference, not the URL.

agentmako project db bind --db-env DATABASE_URL --yes
agentmako project db bind --supabase-project xxxxxxxx

agentmako project db unbind

Removes the database binding. Add --delete-secret to also remove the keychain entry.

agentmako project db test

Verifies the database is reachable. Same logic as the db_ping MCP tool.

agentmako project db verify

Runs the read-only schema introspection queries to make sure Mako has the permissions it needs (read schema, RLS, functions). Stops at the first failure with a clear error.

agentmako project db refresh

Re-snapshots the schema into Reef. Run after migrations or Supabase type regeneration. MCP equivalent: db_reef_refresh.

MCP server

agentmako mcp

Start the stdio MCP server. The agent harness (Claude Code, Codex, Cursor, Cline) spawns this process via your MCP config and talks to it on stdin/stdout. You don't usually run this manually — but you can, to debug.

# run standalone to see the JSON-RPC handshake
agentmako mcp

Common flags:

  • --project PATH — pin the server to a specific project (defaults to the current working directory's attached project).
  • --log-level debug|info|warn|error — control stderr verbosity. JSON-RPC traffic stays on stdout.

agentmako tool list

Prints every tool currently exposed by the MCP server, grouped by category. Includes mode (read/mutation), description, and input schema. Authoritative runtime catalog.

agentmako tool call NAME ARGS

Invoke an MCP tool from the shell — the same call the agent harness would make. Useful for debugging and CI scripting.

agentmako tool call context_packet \
  --args '{"request":"trace auth flow","budgetTokens":4000}'

Status & diagnostics

agentmako doctor

Top-level health check. Prints one line per subsystem (config, API service, project index, database binding, providers). All green = ready.

agentmako status

Compact dashboard: current project, freshness counts, provider, recent activity. Run between sessions.

agentmako verify [path]

Runs the verification suite — checks evidence freshness across the index against the working tree. MCP equivalent: verification_state.

agentmako refresh [path]

Composite refresh — index + diagnostics + DB facts. Useful as the "kick everything" command after a long break.

agentmako git precommit

Runs the staged-file route auth and boundary checks. Designed to drop into a pre-commit hook:

# .git/hooks/pre-commit
#!/bin/sh
agentmako git precommit || exit 1

Model providers

For the optional harness (chat / answer / workflow commands). Not required for the MCP server itself.

agentmako providers list

Lists configured providers and their models.

agentmako providers add

Add a provider (Anthropic, OpenAI, Ollama, LM Studio, etc.). Stores the API key in the OS keychain.

agentmako providers test [name]

Roundtrip test against the configured provider.

agentmako providers remove [name]

Removes the provider config and (with --delete-secret) the keychain entry.

agentmako keys set / keys delete

Lower-level keychain controls when you need them independent of provider configs.

Optional harness commands

If you've configured a provider, agentmako can run as a coding agent itself. These are optional — the MCP server works without them.

agentmako chat

Interactive chat loop using your configured provider and Mako tools.

agentmako answer ask "QUESTION"

One-shot question against the project. Routes to a canonical Mako tool and returns a structured answer.

agentmako workflow packet "TASK"

Generate a context packet for a task — the same shape context_packet returns over MCP.

agentmako session list / show / resume / rm

Manage chat session history.

agentmako memory remember / recall / list

The harness's persistent memory store. Independent of Reef facts/findings — these are user-curated notes.

agentmako semantic search "QUERY"

Vector search across embeddings, if you've enabled the optional embeddings index.

agentmako embeddings reindex

Rebuild the embeddings index.

Permissions & safety

The harness can require approval for destructive actions (running shell commands, mutating Reef, etc.). These commands manage that ledger.

  • agentmako permissions list — show pending and decided permission requests.
  • agentmako permissions approve / deny ID — decide a single request.
  • agentmako permissions add — pre-grant a permission so the harness doesn't ask again.
  • agentmako permissions remove — revoke an existing grant.
  • agentmako undo — roll back the last harness mutation, when undoable.

Misc operations

agentmako catalog status / catalog refresh

Manage the harness's tool catalog cache. Most users never touch these — they exist for when the published tool surface drifts from the local cache.

agentmako tier

Print the current support tier for the active project (which language/framework features Mako can fully analyze).

agentmako usage

Token / call usage for the harness, broken down by provider.

agentmako telemetry show

Confirms what telemetry would be collected — which is nothing. agentmako has no telemetry endpoint; telemetry show exists so you can verify that.

agentmako serve

Run agentmako as a local HTTP service instead of stdio. Used by the optional dashboard. Most agents use agentmako mcp instead.

agentmako dashboard

Open the local web dashboard in your browser. Optional — all dashboard data is also reachable via MCP tools.

Environment variables

  • MAKO_STATE_HOME — override ~ for global Mako state. Default: $HOME.
  • DATABASE_URL — common name for project DB binding when using --db-env DATABASE_URL.
  • ANTHROPIC_API_KEY / OPENAI_API_KEY / etc. — picked up by providers add if present.
  • NO_COLOR — disable ANSI in CLI output.
  • MAKO_LOG_LEVEL — global default for stderr verbosity.