> ## Documentation Index > Fetch the complete documentation index at: https://docs.moda.dev/llms.txt > Use this file to discover all available pages before exploring further. # CLI parity map > How the MCP server's 53 tools map 1:1 onto moda CLI commands, where wire behavior is identical, where it deliberately deviates, and which commands stay CLI-only. The MCP server's contract with the [CLI](/cli/overview) is 1:1: every remote-capable `moda` command is exposed as exactly one MCP tool with the same name (kebab-case becomes snake\_case, subcommand spaces become underscores) and the same wire behavior — same endpoints, same query parameters, same encodings, same warnings. A few tools rename where the CLI verb implies local file I/O the server cannot do (`skills pull` → `skills_list`, `skills sync` → `skills_push`); the mapping below is the full list. Each tool's registration carries the command it mirrors in `_meta["dev.moda/cli_command"]`, and the `manifest` tool returns this entire map machine-readably at runtime. ## Tool-to-command map All 53 tools, grouped by toolset. **Writes?** reflects each tool's `readOnlyHint` annotation — what approval-gating clients see. | MCP tool | CLI command | Toolset | Writes? | | ------------------------------ | ------------------------------------------------ | ------- | ----------------- | | `overview` | `moda overview` | data | No | | `investigate` | `moda investigate` | data | No | | `failures` | `moda failures` | data | No | | `ask` | `moda ask` | data | No | | `clusters` | `moda clusters` | data | No | | `cluster_conversations` | `moda cluster-conversations` | data | No | | `conversations` | `moda conversations` | data | No | | `search` | `moda search` | data | No | | `world_state` | `moda world-state` | data | No | | `context` | `moda context` | data | No | | `audit` | `moda audit` | data | No | | `step_scores` | `moda step-scores` | data | No | | `frustrations` | `moda frustrations` | data | No | | `tool_failures` | `moda tool-failures` | data | No | | `tool_failure_detail` | `moda tool-failure-detail` | data | No | | `emotions` | `moda emotions` | data | No | | `hallucinations` | `moda hallucinations` | data | No | | `problems` | `moda problems` | data | No | | `problem` | `moda problem` | data | No | | `problem_feedback` | `moda problem-feedback` | data | Yes | | `feedback` | `moda feedback` | data | Yes | | `tail` | `moda tail --once` | data | No | | `fixes` | `moda fixes` | fixes | No | | `fixes_draft_batch` | `moda fixes draft-batch` | fixes | Yes | | `fixes_drive` | `moda fixes drive` | fixes | Yes | | `fix` | `moda fix ` | fixes | With `wait: true` | | `fix_start` | `moda fix start` | fixes | Yes | | `fix_packet` | `moda fix --packet` | fixes | No | | `fix_verify` | `moda fix verify` | fixes | Yes | | `fix_checkout` | `moda fix checkout` | fixes | Yes | | `fix_submit` | `moda fix submit` | fixes | Yes | | `fix_mark_applied` | `moda fix mark-applied` | fixes | Yes | | `fix_dismiss` | `moda fix dismiss` | fixes | Yes | | `prompts_sync` | `moda prompts sync` | prompts | Yes | | `prompts_diff` | `moda prompts diff` | prompts | No | | `prompts_promote` | `moda prompts promote` | prompts | Yes | | `prompts_ab` | `moda prompts ab` | prompts | Yes | | `prompts_propose` | `moda prompts propose` | prompts | Yes | | `replay_run_status` | `moda prompts ab --wait` (poll step) | prompts | No | | `skills_gen` | `moda skills gen` | skills | Yes | | `skills_status` | `moda skills status` | skills | No | | `skills_list` | `moda skills pull` | skills | No | | `skills_push` | `moda skills sync` | skills | Yes | | `skills_proposals` | `moda skills proposals list` | skills | No | | `skills_proposal` | `moda skills proposal apply` (fetch step) | skills | No | | `skills_proposal_mark_applied` | `moda skills proposal apply` (mark-applied step) | skills | Yes | | `harness_sync` | `moda harness sync` | harness | Yes | | `harness_delete` | `moda harness delete` | harness | Yes | | `harness_analyze_status` | `moda harness pull` | harness | No | | `whoami` | `moda auth whoami` | meta | No | | `doctor` | `moda doctor` | meta | No | | `status` | `moda status` | meta | No | | `manifest` | `moda manifest` | meta | No | `fix` is a pure read by default; `wait: true` turns each poll into an advance `POST` — the only thing that moves a fix through the pipeline — which is why it is not annotated read-only. `fix_checkout` performs no server-side write itself, but it is deliberately not annotated read-only so clients gate the checkout-and-deliver flow behind approval. ## Wire parity contract The server ports the CLI's request-building rules exactly; anything the backend sees is byte-for-byte what the CLI would have sent. The rules: | Rule | Behavior | | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Parameters travel only when provided | Absent parameters are omitted from the query string so backend defaults apply — the backend rejects unknown parameters, and the CLI never materializes defaults client-side. The handful of client-materialized defaults the CLI *does* send are copied exactly: `days_back` on `overview`/`investigate`/`failures` (default 7, floored and clamped to 90), `msg_index=0` on `world_state` snapshots, `format` on the `world_state` replay route, `status=approved` on `skills_list`, `category`/`severity` in the `feedback` body, `signal`/`limit` in `tail`. | | Numeric parameters are integers | Input schemas enforce integers, serialized as integer strings on the query string — never floats, never quoted numbers in JSON bodies. | | Boolean encodings copied per endpoint | Boolean wire encodings vary per endpoint by backend contract and are copied from the CLI verbatim: `include_tool_io=true` on `/search`, but `summary_only=1` on world-state and `include_raw=1` on audit. Booleans in JSON `POST` bodies are real JSON booleans. | | Empty-200 not-found convention | The Data API answers unknown ids with HTTP 200 and an empty payload, never a 404. Tools convert that to a warning — `No found for id "..." — it may not exist in this tenant` — using the CLI's template verbatim, never an error. | | UUID pre-validation on problem sub-resources | `problem` with a `view` and `problem_feedback` require a canonical problem UUID and fail fast client-side before any network call, because the backend returns 400 for non-UUID ids on those routes. The `problem` dossier (no `view`) accepts any id and answers `found: false`. | | Zero transport retries on writes | Every non-idempotent `POST` passes `retries: 0` — a transport retry after a lost response could double-run a pipeline step or insert a duplicate row. Reads retry up to 3 times on 429/5xx with exponential backoff (500 ms initial). `ask` additionally retries exactly once on a network-level failure (the CLI's poisoned-connection guard); HTTP errors never consume that retry. | ### Timeout budgets Per-call timeouts mirror the CLI's budgets. Calls not listed use the 30-second default. | Call family | Budget | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | | `ask` (`POST /cli/ask`) | 250 s | | Fix pipeline advance steps (`fix`/`fix_start`/`fix_verify` polling, `fixes_drive`), `fixes_draft_batch`, `prompts_ab` replay-set generation, `prompts_propose` revision | 300 s | | `fix_start` create, `fix_verify` enqueue, `fix_submit`, `skills_gen` | 120 s | | Replay run enqueue (inside `prompts_ab`/`prompts_propose`) | 120 s (1 retry) | | `fix_mark_applied`, `fix_dismiss`, replay comparison reads | 60 s | | Everything else | 30 s | ## Deliberate deviations Five behaviors intentionally differ from the CLI. Each is also called out in the affected tool's description. | Area | MCP server | CLI | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Path-segment ids | Every path-segment id is URL-encoded before interpolation, so ids containing `/`, `?`, or `#` cannot break out of their path segment (hardening). Query-string behavior is untouched. | Encodes some path ids (`/audit/:id`, `/conversations/:id/step-scores`) but not others (`/clusters/:node_id/conversations`, world-state, context) by design-accident. | | `prompts_ab` promotion | `promote_primary` defaults to `false` — an A/B never promotes the winning arm unless you ask. Promote explicitly with `prompts_promote`. | Defaults to promoting (`promotePrimary=true` unless `--no-promote`). | | Waits and drives | Bounded with call-again semantics: `max_wait_seconds` is 10–600 (default 120), `fixes_drive` runs at most `max_passes` (1–10, default 3) round-robin passes per call, and a lapsed deadline returns the current state with a timed-out warning instead of throwing. `prompts_ab`/`prompts_propose` default to async (`wait: false`), with `replay_run_status` as the poll half. | Blocking loops up to a 2-hour default timeout; waiting is the default. | | `tail` | The `--once` form only: one poll returning ordered events plus a coverage record stating how much of the score-ranked emotions window was scanned. Call repeatedly and dedupe by `conversation_id`/`detection_id` to follow along. | Continuous interval polling with cross-poll dedupe and NDJSON streaming. | | File reads and writes | Content travels inline: `fix_verify` takes `candidate_content` in place of `--prompt-file`, `fix_checkout` returns `{path, content, branch, magic_word}` for the client to write, `fix_packet` returns candidate text in the payload (no `.moda/fixes//` materialization), `prompts_sync`/`skills_push` take prompt and SKILL.md content as arguments, and `skills_list`/`skills_proposal` return content for the client to install. | Discovers content from and writes results to local files (`.moda/`, `.claude/skills/`, prompt files). Note the CLI never runs git either — branch and PR conventions are your job in both surfaces. | ## CLI-only commands Commands that open a browser, manage local credentials, or read and write your repo have no MCP tool. The `manifest` tool returns this list with the same reasons. | Command | Why it stays CLI-only | MCP alternative | | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | `moda init` | Browser sign-in, local file writes, coding-agent subprocesses. | None — run it once in a terminal; it produces the API key this server authenticates with. | | `moda provision` | Requires a browser-minted CLI session token; it mints the API key this server uses. | None — provision the key headlessly, then configure it on the connection. | | `moda auth login/token/logout` | Manages local credentials; MCP auth is per-request headers. | `whoami` validates the connection's key and reports its tenant. | | `moda profiles` / `moda config` / `moda keys` | Local credential/profile files; an MCP connection is one credential. | Add a separate MCP server entry per environment or tenant. | | `moda harness scan/analyze/approve/validate-report/agents/graph/explain/status` | Scans the local repo and writes `.moda/*` artifacts. | `harness_sync` uploads a locally produced graph; `harness_analyze_status` reads a hosted analysis run. | | `moda agent context/investigate/next-action/evidence` | Built from local doctor state plus `.moda` artifacts. | `overview`, `investigate`, and `doctor` cover the cloud halves. | | `moda workspace` / `moda hooks install` | Local git shadow repo and coding-agent hook configuration. | None. | | `moda tail` (continuous) | Long-running poller. | `tail` is the `--once` form; call it repeatedly and dedupe client-side. | | `moda prompts init/status/diff --watch` | Local manifest/lockfile scaffolding. | `prompts_diff`, or `prompts_sync` with `dry_run: true`, for a server-computed diff. | | `moda skills pull` / `moda fix checkout` file writes | The MCP tools return content; writing files is the client's job. | `skills_list`, `skills_proposal`, and `fix_checkout` return the content to write. | ## Next steps * [MCP server](/mcp/overview) — endpoint, authentication, toolsets, and client setup. * [MCP tool reference](/mcp/tools) — every tool with its parameters and example output. * [CLI reference](/cli/reference) — the `moda` commands these tools mirror, with flags and trimmed outputs.