Marfa CLI

@withmarfa/cli — command-line interface for the Marfa API. Manage items, edges, metadata, blobs, types, keys, webhooks, tenant config, and connections from the terminal.

Install

npm install -g @withmarfa/cli
# or: pnpm add -g @withmarfa/cli
# or: yarn global add @withmarfa/cli

Installs the marfa binary on your PATH. Confirm with marfa --help.

From source (development)

git clone https://github.com/withmarfa/cli && cd cli
pnpm install
pnpm build
node dist/index.js --help    # or symlink dist/index.js into your PATH

Configuration

Set these environment variables or pass --url / --key flags:

| Variable | Description | | --- | --- | | MARFA_API_URL | Marfa server URL (required, or pass --url) | | MARFA_API_KEY | API key for authentication (alternative to marfa auth login) | | MARFA_INSTANCE | Config-file instance name under ~/.marfa/<instance>.json (default: default) | | MARFA_CLI_CLIENT_ID | OAuth client ID for marfa auth login (default: marfa-cli) |

Authentication

marfa supports two auth paths.

Interactive (recommended for humans). marfa auth login runs the OAuth Device Authorization Grant — it prints a URL and code, you approve in a browser, tokens are stored at ~/.marfa/<instance>.json (mode 0600) and refreshed automatically. Pick a different instance with --instance <name> (or MARFA_INSTANCE) to keep separate sessions per server.

marfa --url https://marfa.example.com auth login
marfa auth whoami
marfa items list             # uses the stored OAuth tokens transparently
marfa auth logout

API key (recommended for scripts / CI). Set MARFA_API_URL + MARFA_API_KEY (or pass --url / --key) and skip auth login entirely.

export MARFA_API_URL=https://marfa.example.com
export MARFA_API_KEY=marfa_k1_...
marfa items list

OAuth tokens take precedence when present and their issuer matches the resolved URL; the API key is the fallback.

Usage

marfa items list
marfa items create --type core.note --prop title="Hello"
marfa items create --type core.highlight --prop text="..." --edge references:<doc-id>
marfa items create --type core.note --prop title="With files" --attach ./diagram.png --attach ./notes.pdf
marfa items update <id> --source-id <new-source-id>
marfa items list --tier library
marfa items list --edge parent-of=<id>
marfa edges create <source-id> <target-id> --type about
marfa items search "query"
marfa blobs upload ./file.png
marfa health
marfa export --output backup.json

# scoped admin operations
marfa keys create --label app-cred --source app-1 \
  --type-perm core.note=write --extension-perm app.cursor=write
marfa metadata extensions set <id> connection.runtime --data '{"cursor":"abc"}'
marfa tenant config get
marfa webhooks deliveries <webhook-id>
marfa connections list
marfa connections uninstall <connection-id>

Run marfa --help for the full command list.

marfa docs

Thin wrapper around the Marfa docs MCP HTTP API. Same surface, same vocabulary as the docs MCP server — agents and humans read from one source of truth.

marfa docs search "items"               # hybrid search across docs
marfa docs search "edges" --limit 25    # cap results
marfa docs get /reference/items         # fetch a single page as markdown
marfa docs list                         # list docs topics (the taxonomy)

--docs-url <url> overrides the default https://docs.marfa.so (or set MARFA_DOCS_URL) — self-hosters point at their own docs MCP. Output follows the rest of the CLI: human-readable on a TTY, JSON when piped (or with --json).

Threads → edges

threads was removed in v3. A thread is whatever item is the target of in-thread edges:

• Create the root item (any type — commonly core.note), then marfa edges create <member-id> <root-id> --type in-thread for each member.
• List members: marfa items list --edge in-thread=<root-id>.
• The in-thread edge carries an optional position property for ordering.

License

MIT