CLI overview

The Moda CLI (@moda-ai/cli, installed as moda) queries your production trace data from the terminal, manages prompt versions, and syncs your harness. This page covers installation, authentication, profiles, output formats, and exit codes. The full command list is in the CLI reference, and agent/CI integration patterns are in Using the CLI from agents and CI.

Install

Requires Node.js 18 or later.

npm install -g @moda-ai/cli
moda --version

npx -y @moda-ai/cli overview

Authentication

The CLI uses two credentials for two different groups of commands:

Credential	Used by	How you get it
CLI session	`auth *` commands and `provision`	`moda auth login` (browser flow)
API key (`moda_sk_...`)	Data commands (`search`, `overview`, `emotions`, `problem`, `tail`, `ask`, …), `prompts`, `skills`, `harness sync`	`moda init`, `moda provision`, or the dashboard at Settings → Ingestion keys

API keys (called ingestion keys in the dashboard) are tenant-bound: a key always operates on the tenant it was created for, and MODA_TENANT_ID cannot re-point it.

Log in (browser flow)

moda auth login

The command opens your browser to moda.dev, where you sign in; the CLI completes a PKCE exchange against a localhost callback (ports 8432–8435, first free port). If the browser cannot reach the CLI — for example when you run the CLI over SSH — paste the callback URL or the one-time code shown in the browser back into the terminal. The resulting CLI session lasts 30 days on a sliding window and renews in the background. Related commands:

moda auth status — reports session state; exits 4 when logged out. --online also probes the API.
moda auth whoami — shows the authenticated user and available tenants.
moda auth token — prints the raw session token (for scripting control-plane calls).
moda auth api-key — prints the saved moda_sk_ API key for $(moda auth api-key) and pipes.
moda auth logout — revokes the session server-side and clears local credentials, including the stored API key.

The session token authenticates control-plane commands only. Data commands require a moda_sk_ API key: set MODA_API_KEY, or mint one with moda init or moda provision. moda auth token output is not valid for the Data API.

API key resolution order

Data commands resolve the API key in this order:

MODA_API_KEY environment variable
The active profile’s stored key
~/.moda/config.json (api_key)

Headless provisioning: `moda provision`

moda provision mints (or reuses) a tenant API key without any interactive prompts and prints exactly one JSON document to stdout — nothing else. It is built for CI bootstrap scripts and agents:

MODA_API_KEY=$(moda provision --tenant-id=1f7c9a2e-4b3d-4c8e-9a1b-2d3e4f5a6b7c | jq -r .apiKey)

Output

{
  "apiKey": "moda_sk_...",
  "tenantId": "1f7c9a2e-4b3d-4c8e-9a1b-2d3e4f5a6b7c",
  "tenantName": "Acme Support",
  "tenantSlug": "acme-support",
  "ingestUrl": "https://moda-ingest.modas.workers.dev",
  "baseUrl": "https://moda.dev",
  "reused": false
}

The field names are a stable contract. reused is true when an existing stored key passed a liveness check and no new key was created. Behavior to script around:

Provision requires an existing CLI session (moda auth login run previously on that machine) and never opens a browser. Without a session it fails with exit code 4 and instructions to log in first.
With access to multiple tenants, --tenant-id (or the MODA_TENANT_ID env var; the flag wins) is required. Without it, provision fails with exit code 5 and a machine-readable input_request that lists every tenant with its resume flags — it never prompts, even on an interactive terminal.
--label=TEXT names the key (default: machine hostname). --save also persists the key and tenant to ~/.moda/config.json; by default provision only prints, so headless callers own storage.

Provision’s stdout contains a live API key. Capture it into a secret store or variable; do not pipe it to logs.

Profiles and configuration

CLI state lives in ~/.moda/: config.json (API key, tenant ID, ingest URL), profiles.json, and per-profile secrets under ~/.moda/secrets/. Three profiles exist by default: prod (https://moda.dev, the default), staging, and local.

moda profiles list
moda profiles use staging
moda config show --profile=prod

Select a profile per invocation with --profile=NAME or the MODA_PROFILE env var. Two env vars override URLs directly:

MODA_BASE_URL — the moda.dev host used for the Data API and control-plane calls.
MODA_INGEST_URL — the Ingestion API host.

A loopback MODA_BASE_URL (localhost, 127.0.0.1, ::1) is used only on a non-prod profile (local, staging, dev). On a prod profile the command fails with exit code 5 (input_required) before sending anything: the CLI never sends a prod profile’s key to a loopback server, and it does not send the request to production in its place. Re-run with --profile=local (or MODA_PROFILE=local) to use the local stack, or unset MODA_BASE_URL to use production. moda config show reports such a URL as refused, and moda auth status --online reports online.baseUrl, the URL every request uses.

Output formats

The CLI picks an output mode automatically, in this priority order:

Explicit flags: --human (or --prose), --json, --agent, --agent --stream
MODA_FORMAT env var: human | json | agent | agent-stream | ndjson
Agent environment detection: a truthy CLAUDECODE, CURSOR, CI, or MODA_AGENT env var selects agent
TTY detection: piped or redirected stdout selects agent; an interactive terminal selects human

The modes:

Mode	Output
`human`	Readable output for a terminal (data commands print pretty JSON; `overview`, `ask`, `doctor`, and others render prose)
`json`	The raw payload as JSON: one compact line when piped, indented on a terminal or with `--pretty`; errors print a structured error envelope
`agent`	One `moda.agent.v1` JSON envelope per invocation
`agent-stream`	NDJSON `moda.agent_event.v1` events (`--agent --stream`)

This means a piped or CI invocation gets machine-parseable output with zero flags. These commands bypass envelopes in every mode because their stdout is meant to be captured directly: moda provision (one JSON credentials document), moda auth token / moda auth api-key (the bare credential), and moda tail (NDJSON — one JSON line per event, since a live tail is a stream rather than a single response).

The `moda.agent.v1` envelope

In agent mode every command emits a single JSON envelope:

{
  "schema_version": "moda.agent.v1",
  "command": "tool-failures",
  "status": "ok",
  "generated_at": "2026-08-16T09:14:02.318Z",
  "summary": { "text": "3 tools failed in the last 7 days.", "confidence": "high" },
  "findings": [],
  "evidence_refs": [],
  "recommended_actions": [],
  "next_commands": [],
  "artifacts": [],
  "warnings": [],
  "errors": [],
  "data": { "summary": { "total": 41 }, "tools": [] },
  "meta": { "run_id": "1c3f...", "tip": "If a result looks wrong or is missing data: moda feedback ..." }
}

status is ok, degraded, or error; the command’s payload is always under data. The full field reference, the streaming event schema, and exit-code recipes are on Using the CLI from agents and CI. moda manifest --json and moda --json-schemas describe the protocol machine-readably.

Exit codes

Code	Meaning
`0`	Success.
`1`	Error: command, input, unknown id (`not_found`), access denied, API, network, or unexpected failure.
`3`	Degraded: an answer was produced from a local fallback instead of Moda Cloud (only `moda ask`).
`4`	Authentication required: no API key, or the API rejected it (HTTP 401). Set `MODA_API_KEY` or run the login command in the error payload, then resume.
`5`	Input required: a non-interactive caller must choose a value (for example `--tenant-id`, or `--profile=local` for a loopback `MODA_BASE_URL` on a prod profile) and re-invoke.
`130`	Cancelled: interrupted (Ctrl+C) or the output consumer closed the pipe.

Update check and telemetry

Both are on by default and both can be turned off:

Update check. At most once a day the CLI checks the npm registry for a newer @moda-ai/cli version and prints a notice to stderr on a terminal; agent envelopes carry it as meta.update. A failed check (offline, unreachable registry) also waits a day before the next try. In agent and JSON modes the check runs in a detached background process, so it never delays a command. Disable with --no-update-check (or --no_update_check) or MODA_CLI_UPDATE_CHECK=0. The check is automatically skipped in CI and when DO_NOT_TRACK=1 is set.
Usage telemetry. The CLI reports command name, the names of flags the command accepts (never values or arguments; any other --word is only counted), exit status, and duration. It is sent to the same base URL and with the same key the command uses, and not at all when --profile or MODA_PROFILE names a profile that does not exist. Events wait in a private local file (~/.moda/telemetry/, which never holds the API key) and are sent in batches by one background process once 20 have collected or the oldest is 30 seconds old (every run in CI). Disable with --no-telemetry (or --no_telemetry) for one run, or with MODA_CLI_TELEMETRY=0 or DO_NOT_TRACK=1, which also delete events still waiting to be sent.
Feedback tip. Successful commands print a one-line moda feedback tip (stderr on a TTY, meta.tip in envelopes). Hide the stderr line with MODA_CLI_TIPS=0.

Environment variables

Variable	Effect
`MODA_API_KEY`	API key for data commands (highest precedence).
`MODA_TENANT_ID`	Tenant selection for `provision` and `init` (a flag wins over it).
`MODA_PROFILE`	Active profile name.
`MODA_BASE_URL`	Override the moda.dev host. A loopback URL needs a non-prod profile (`--profile=local`); on a prod profile the command exits 5.
`MODA_INGEST_URL`	Override the Ingestion API host.
`MODA_FORMAT`	Force an output mode: `human`, `json`, `agent`, `agent-stream`, `ndjson`.
`MODA_AGENT`	Truthy value forces agent-environment detection.
`MODA_AUTH_TIMEOUT_MS`	How long `moda auth login` waits for the browser (default 10 minutes, clamped 30 s – 30 min).
`MODA_ASK_TIMEOUT_MS`	`moda ask` cloud timeout in milliseconds (default 250,000).
`MODA_HEARTBEAT_MS`	Idle heartbeat interval in `agent-stream` mode (default 10,000).
`MODA_AGENT_MAX_OUTPUT_BYTES`	Bound on agent envelope size (default 24,000 bytes, under the 30,000-character tool output limit of agent harnesses). Over it, redundant `content_blocks` are removed first, then whole list items are dropped (never cut text); `pagination` and `next_commands` say where the rest starts, and a `truncation` block points at the complete output file.
`MODA_AGENT_OUTPUT_DIR`	Where over-budget agent output is written in full (default `<tmpdir>/moda-agent-output-<uid>`, owner-only).
`MODA_AGENT_OUTPUT_RETENTION_HOURS`	How long full-output files are kept (default 24). Each new file prunes older full-output files in that directory; other files are never touched.
`MODA_CLI_TELEMETRY`	`0` (or `false`, `no`, `off`) disables usage telemetry.
`MODA_CLI_UPDATE_CHECK`	`0` (or `false`, `no`, `off`) disables the daily update check.
`MODA_CLI_TIPS`	`0` hides the feedback tip line.
`DO_NOT_TRACK`	`1` (or any value except empty, `0`, `false`, `no`, `off`) disables telemetry and the update check.

Next steps

CLI reference — every command with flags and example output.
Using the CLI from agents and CI — envelopes, exit-code recipes, and CI examples.
Data API overview — the HTTP API behind the data commands.
Connect the MCP server — the core read commands as MCP tools for Claude Code, Cursor, and other MCP clients (some CLI commands are CLI-only; see parity).
Authentication — how API keys and sessions work across Moda.

​Install

​Authentication

​Log in (browser flow)

​API key resolution order

​Headless provisioning: moda provision

​Profiles and configuration

​Output formats

​The moda.agent.v1 envelope

​Exit codes

​Update check and telemetry

​Environment variables

​Next steps

Install

Authentication

Log in (browser flow)

API key resolution order

Headless provisioning: `moda provision`

Profiles and configuration

Output formats

The `moda.agent.v1` envelope

Exit codes

Update check and telemetry

Environment variables

Next steps