Marrow CLI

The Marrow CLI is a hosted API client for the public account workflow. It keeps the surface small: configure a key, ingest a source, check job status, query evidence, and manage keys.

Install

npm view @marrowid/cli version
npm install -g @marrowid/cli
marrow --help

Continue only after the version lookup returns a version. If the package is not available to your registry yet, wait for access before running the install command.

The package installs the marrow command and requires Node.js 20 or newer. If your shell cannot find marrow after a global install, check that your npm global bin directory is on PATH:

npm config get prefix

You can still run the installed package through npm:

npm exec -- marrow --help

Before continuing, verify the three discovery commands work:

marrow --help
marrow api --help
marrow api configure --help

Configure

Create an account at console.marrow.id, copy the one-time API key from the console, and store it locally:

marrow api configure
marrow api config

The hosted API endpoint is https://api.marrow.id by default. Use --api-base-url or MARROW_API_BASE_URL only when Marrow support gives you a different endpoint.

api configure stores the hosted API endpoint and API key in ~/.marrow/config.json with file mode 0600. It uses a hidden prompt by default and never prints the stored key back. For non-interactive automation, set MARROW_API_KEY for that one setup command only, then unset it.

api config reads the local configuration and reports the config path, endpoint, and whether a key is present. It never prints the key.

Set MARROW_CONFIG_PATH=/path/to/config.json for isolated test or CI runs that must not read or write your normal ~/.marrow/config.json.

Ingest

Preview a public URL before writing anything:

marrow api ingest-url --dry-run --dated-at 2026-05-16 https://example.com/my-bio

Queue the live ingest when the preview looks right:

marrow api ingest-url \
  --dated-at 2026-05-16 \
  https://example.com/my-bio

For a local Markdown, text, PDF, HTML, or JSON file:

marrow api ingest-file --dry-run --dated-at 2026-05-16 ./source.md
marrow api ingest-file --dated-at 2026-05-16 ./source.md

Live ingest requires a source date. Use the authored, published, or otherwise source-relevant date for the material.

If the file is writing you authored in your own voice, add --style-sample to the dry run and live ingest commands. Do not use that flag for third-party articles, interviews, transcripts, scraped pages, or material written by someone else.

Ingest commands print a short human-readable status by default. Add --json only when an integration needs the structured API response.

Job Status

Queued ingest appears in the recent jobs list. Poll until the job reaches succeeded, failed, or quarantined:

marrow api ingest-jobs --limit 5
marrow api ingest-job <job_id>

Use --json on the live ingest command when an integration needs the returned job id for marrow api ingest-job <job_id>.

Query

After an ingest succeeds, ask one concrete evidence question:

marrow api query "What evidence supports my current work?" --limit 5 --evidence-limit 3

The default output is a compact extractive answer with numbered citations and source excerpts. It is not a generated chat answer. Add --json only when an integration needs the structured API response.

Usage

Check credits and request limits from the CLI:

marrow api usage

The default output is human-readable and shows remaining credits, request limits, and UTC reset dates. The command uses the public /v1/account/usage endpoint and works with account, ingest, or query scoped keys. Add --json only when an integration needs the structured response.

API Keys

List keys, create a replacement, or revoke an old key:

marrow api api-keys
marrow api create-api-key --name "Laptop CLI"
marrow api create-api-key --name "Query only" --scope query
marrow api create-api-key --name "Ingest and query" --scope ingest --scope query
marrow api revoke-api-key <api_key_id>
marrow api rotate-api-key <api_key_id>
marrow api delete-api-key <api_key_id>

Omit scope flags to create an ingest,query key. Repeat --scope to add one or more explicit public scopes. Existing automation may keep using the legacy comma-separated --scopes ingest,query form.

Add account only for keys that need account overview or API key lifecycle access. Do not use any scopes outside account, ingest, and query; the public CLI rejects them.

Scope summary:

| Scope | Use for | | :-------- | :------------------------------------------------------------- | | account | Account overview, key listing, key creation, rotation, revoke | | ingest | Source submission and ingest job status | | query | Source-backed evidence retrieval |

marrow api usage works with account, ingest, or query scoped keys. Key management commands require the current key to include account. If your current key does not include account, create the replacement in the console or configure an account-scoped key first.

revoke-api-key disables a key so it can no longer authenticate. Use it for lost, rotated, or retired keys. delete-api-key only removes an already revoked or expired key record from the account list; it is not a substitute for revocation.