@marrowid/cli

Marrow CLI

Use the Marrow CLI to add records, run queries, manage API keys, and start MCP over stdio. Connect remote-capable MCP clients directly to https://mcp.marrow.id; use marrow mcp when a client requires a local stdio server. Version 1.0.11 uses separate credentials for account and product work:

• 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.

The CLI runs inside a trusted application process. Keep returned text as data and preserve citations, warnings, and insufficient_evidence when another model consumes it. See the OpenAPI document and the Native Memory API.

Install

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

npm install -g @marrowid/cli@1.0.11
npm exec --package @marrowid/cli@1.0.11 -- marrow --version
marrow --version
marrow --help

If an older global binary is already on PATH, the npm exec check verifies 1.0.11 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

Task	Credential	Storage
Product ingest, query, and native memory commands	Customer API key	MARROW_API_KEY in the process environment
Local stdio MCP	Customer API key	Inherited MARROW_API_KEY; never MCP JSON
Hosted MCP	Interactive authorization or customer API key	MCP client's protected credential store
API-key create, rotate, revoke, and list	CLI account session	macOS Keychain
Browser account and billing work	Browser session	Marrow Console

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.11:

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>

Query Marrow

Ask one concrete question after processing succeeds:

marrow query "What should this workflow remember about onboarding?" \
  --mode answer \
  --preset accuracy

The response includes citations, source labels, excerpts, and warnings. If Marrow returns insufficient_evidence, add relevant material or continue without Marrow.

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. Available scopes are ingest, query, memory.read, and memory.write. Create and rotate show a new secret once; list and revoke never reveal it.

MCP

Connect remote-capable clients to:

https://mcp.marrow.id

People can use interactive authorization to connect an MCP client to their Marrow account. A server-managed client can use an API key with the required memory scopes. Connected applications remain visible and revocable in Console.

Use marrow mcp when the MCP client requires a local stdio server. It connects to the same Marrow account and exposes the same 14 tools as Hosted MCP.

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 14 tools for query, peer, session, claim, event, queue, and representation workflows. The canonical query tool requires query; native-memory reads require memory.read; writes require memory.write. Wrong-scope and revoked-key errors are returned to the client. See the MCP tool table and the short coding-agent prompt.

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 troubleshooting

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.