Marrow CLI

The Marrow CLI carries Marrow context into local workflows and ships the local MCP compatibility entrypoint in the same public client. It connects documents, URLs, and records; retrieves useful context with citations and visible gaps; uses native memory commands; manages API keys; and runs local stdio MCP. Hosted MCP at https://mcp.marrow.id is the recommended MCP path. Version 1.0.4 keeps account authority and product credentials deliberately separate:

• a CLI session authorizes human account and API-key management;
• MARROW_API_KEY authorizes product commands and local MCP;
• non-secret defaults live in the Marrow config file;
• customer keys never enter command arguments or Marrow config.

Use the exact public clients @marrowid/[email protected], @marrowid/[email protected], and marrowid==1.0.4; Python imports the client with from marrow import Marrow. HTTP is their semantic authority. Direct HTTP, Python, and CLI examples run in a trusted application process; keeping credentials there does not provide prompt-injection isolation for untrusted content. See the OpenAPI document and the Native Memory API.

#Install

Install CLI version 1.0.4 with Node.js 20 or newer:

npm install -g @marrowid/[email protected]
npm exec --package @marrowid/[email protected] -- marrow --version
marrow --version
marrow --help

If an older global binary is already on PATH, the npm exec check verifies 1.0.4 independently before you replace the global install.

#First setup

Create the local config, set only the defaults you need, then inspect the local setup without making a network request:

marrow init
marrow config --workspace default
marrow doctor

marrow init and marrow config write only the API base URL and workspace default. marrow doctor reports package, platform, config permissions, and whether MARROW_API_KEY is present. It reports presence, never the key.

An upgraded client that finds a legacy plaintext apiKey refuses every network request. Set MARROW_API_KEY through your shell, process manager, or secret store; the next network command removes only the legacy key field atomically and preserves the non-secret defaults.

#Credentials and platform support

#Auth

Customer API keys are for apps and automation, not for signing in to this local CLI.

Device sign-in is available on macOS in version 1.0.4:

marrow auth login
marrow auth status

The browser flow must show the account, short code, expiry, and consequence before deliberate approval. Login or signup alone does not approve a device. Linux and Windows reject marrow auth login before sending a device request; use the Console for account management and an environment customer key for product commands and local MCP.

Sign out the device when it should no longer manage the account:

marrow auth logout

Logout clears the CLI session. It does not revoke or rotate customer API keys.

#Add records

Product commands require MARROW_API_KEY. Preview a source before writing:

marrow ingest url https://example.com/onboarding-note --dry-run --dated-at 2026-05-16
marrow ingest file ./onboarding.md --dry-run --dated-at 2026-05-16

Submit it when the preview is correct:

marrow ingest url https://example.com/onboarding-note --dated-at 2026-05-16 --idempotency-key onboarding-note-2026-05-16
marrow ingest file ./onboarding.md --dated-at 2026-05-16 --idempotency-key onboarding-file-2026-05-16

Use the authored, published, or otherwise relevant date. A live submission requires a caller-owned idempotency key between 8 and 160 characters. Reuse the same key when retrying the same submission; use a new key for a different source or changed content. Dry-runs may omit it. Poll the returned job until it reaches succeeded, failed, or quarantined:

marrow ingest jobs list --limit 5
marrow ingest jobs show <job-id>

#Retrieve cited context

Ask one concrete question after processing succeeds:

marrow query "What should this workflow remember about onboarding?" --limit 5 --evidence-limit 3

Marrow returns public answer fields, citations, source labels, excerpts, and warnings. An insufficient_evidence result is a usable outcome: add source material or continue without Marrow context instead of filling the gap.

Native workspace, peer, session, claim, event, and queue commands use the same environment customer key. Use each command's --help option for its exact arguments.

#Manage API keys on macOS

With an active CLI account session:

marrow api-keys list
marrow api-keys create --name "Production app"
marrow api-keys create --name "Query only" --scope query
marrow api-keys create --name "Memory app" --scope ingest --scope query --scope memory.read --scope memory.write
marrow api-keys rotate <key-id>
marrow api-keys revoke <key-id>

Omit scope flags for the ingest,query default. The admitted scopes are ingest, query, memory.read, and memory.write. Customer API keys accept only ingest, query, memory.read, and memory.write. Create and rotate show the new secret once; list and revoke never reveal secret material.

#MCP

Connect remote-capable clients to the canonical hosted endpoint:

https://mcp.marrow.id

Interactive authorization is the usual choice for a person connecting an MCP client to their existing Marrow account; it grants the full hosted 15-tool resource. A server-managed MCP client may use a customer API key with the required memory scopes. The connected application remains visible and revocable in Console.

Use marrow mcp only when the MCP client requires a local stdio server. It is a first-party compatibility adapter over the same Marrow account and 15-tool registry, not a separate local-memory product.

marrow mcp is the shipped local newline-delimited JSON-RPC entrypoint over stdio. Start the MCP client from a process that already inherits MARROW_API_KEY; do not paste a key into MCP client JSON.

marrow mcp

The server exposes exactly 15 manifest-backed tools for peer, session, claim, event, queue, context, and representation workflows. Read tools require memory.read; write tools require memory.write. A wrong-scope or revoked key returns a visible API error and does not silently widen authority.

A coding agent can complete Phase A without an API key by preparing the non-secret marrow mcp host configuration and naming the minimum scopes. The human configures MARROW_API_KEY in the host-managed MCP environment, restarts the host, and resubmits the task. In Phase B, the agent discovers the invariant 15-tool registry. It never asks a user or model to print the key. Use the copyable coding-agent prompt for the complete handoff.

The local MCP server and tool schemas are available with the CLI. Calls to native memory remain scoped by memory.read and memory.write.

#Output and recovery

Human-readable output is the default. Use --json only when automation needs a stable structured response.

• Missing key: configure MARROW_API_KEY in the invoking process.
• Missing live-ingest replay key: add --idempotency-key <key>, or use --dry-run while previewing.
• Legacy plaintext key: supply the environment key once so the client can remove the legacy config field before network use.
• Wrong scope: rotate or create a key with only the required scope.
• Revoked key: replace the environment value; do not restore the old key.
• Device login on Linux or Windows: use the Console for account work.
• Local setup uncertainty: run marrow doctor; it performs no network request.

Proprietary. UNLICENSED means the package is a distribution channel, not an open-source grant.