CLI reference

Every rekall command and flag — login, ingest, search, stores, docs, mcp, keys — with realistic output examples. The CLI is a client for the Rekall API.

The rekall CLI is an API client: the SKIM engine runs server-side, and the CLI talks to it over the Rekall API. It's the fastest way to ingest folders from the terminal and to explore reasoning traces interactively. Download it from the Downloads page in your dashboard, then run rekall login to authenticate.

Global flags & environment

Flag / env	Description
`--json`	Emit machine-readable JSON (search emits the `SearchResult` verbatim).
`REKALL_API_KEY`	API key, used as a fallback when you are not logged in. A key stored by `rekall login` takes precedence over this.
`REKALL_API_URL`	API base URL. Defaults to `https://api.rekall.sh/v1`; point it at an enterprise self-hosted deployment (e.g. `https://rekall.internal.acme.com/v1`). `REKALL_BASE_URL` is accepted as a legacy alias.
`REKALL_STUDIO_URL`	Studio base URL for the `rekall login` approval page. Defaults to `https://studio.rekall.sh`.

Key precedence

When you are logged in, the key stored in ~/.rekall/config.json always wins over REKALL_API_KEY. The environment variable is only used as a fallback when no login is present. rekall whoami shows which one is active.

rekall --version
# rekall 0.2.0 · client → api.rekall.sh

Fail with the fix

Every CLI error tells you exactly how to resolve it, e.g. No store 'demo'. Run: rekall ingest ./docs --store demo.

Try it with the sample corpus

The CLI bundles a 13-article corpus — wiki- and blog-style pieces on football (including a well-documented night in Bilbao), the NBA, and technology — written so that the interesting questions genuinely span documents: multi-hop, cross-doc, needle-deep-in-article. Ingest it into any store with --demo and run the suggested queries:

rekall ingest --demo --store demo
rekall search "which club ended a seventeen year trophy drought in Bilbao and who scored the winner?" --store demo --trace

Output

✓ ingested 13 sample documents into store demo · searchable now

  these need reasoning across documents — try:
  rekall search "tottenham's record scorer left without a trophy — when did he finally win one?" --store demo --trace
  rekall search "which manager promised to win a trophy in his second season and what happened to him?" --store demo --trace
  rekall search "who was drafted 41st overall and went on to win a unanimous Finals MVP?" --store demo --trace
  rekall search "when is a CPU actually faster than a GPU for AI inference?" --store demo --trace

Browser-based device-code auth. rekall login prints an 8-character code and a Studio approval link (and tries to open your browser), then waits while you sign in to Studio and approve it. On approval it stores the minted key in ~/.rekall/config.json (mode 0600); subsequent commands target the cloud. Only the key prefix is ever printed — never the full secret.

rekall login
# ● Rekall login
#   your code:  ABCD2345
#   approve at: https://studio.rekall.sh/cli-login?code=ABCD2345
#
#   waiting for approval in the browser…
# ✓ logged in — key rk_1a2b3c4d5… saved to ~/.rekall/config.json

rekall logout removes the stored key. rekall whoami shows the active key prefix, the API URL, and where each came from (login vs environment):

rekall whoami
# ● authenticated
#   key:     rk_1a2b3c4d5…
#   source:  login (~/.rekall/config.json)
#   API URL: https://api.rekall.sh/v1 (login config)

Point rekall login at a self-hosted deployment with REKALL_API_URL, and at a self-hosted Studio with REKALL_STUDIO_URL.

`rekall ingest`

rekall ingest <path...> [--store <name>] [--watch] [--format auto|text|pdf|md|image] [--strict]

Ingest files, folders, or globs into a store (created if absent). Whole documents, no chunking, queryable immediately.

Flag	Default	Description
`--store <name>`	default store	Override the target store. Created if absent — and then becomes the default.
`--watch`	off	Re-ingest on file change; documents stay live.
`--format`	`auto`	Force extraction format; `auto` detects pdf/md/html/docx/txt.
`--strict`	off	Abort on the first per-doc failure instead of reporting at the end.

rekall ingest ./docs "./reports/**/*.pdf" --store demo

Output

  ingesting  ████████████████████  287/291   70 docs/s
✓ 287 documents ingested · queryable now  (4.1 s)
  4 skipped (unsupported/empty/too large) — run with --strict to fail instead

See the Ingestion guide for formats, upsert, and streaming.

`rekall add`

rekall add [text] [--id <id>] [--store <name>] [--meta key=value]...

Add raw text directly — no file needed. Text comes from the argument, or from stdin when the argument is - (or omitted and piped). Same upsert semantics as every ingest path; without --id, a stable id is derived from the text.

rekall add "Vendors are reviewed quarterly by the security team." --id vendor-note
pbpaste | rekall add --id clipboard-note --meta topic=vendors
rekall add - < meeting-notes.txt

Output

✓ added vendor-note (53 chars) — searchable now

`rekall ingest-db`

rekall ingest-db <database.sqlite> [--store <name>] [--tables t1,t2] [--row-limit N] [--no-rows]

Sync a SQLite database into a store as searchable documents: a schema overview (written by the enrich LLM when REKALL_ENRICH_* is configured, deterministic DDL otherwise), one document per table, and one document per row — with every text column as filterable metadata. Upserts by stable id, so re-running is an incremental sync.

rekall ingest-db shop.sqlite --store shop
rekall search "blue jeans" --filter color=blue --store shop

Rekall acts as the retrieval layer for text-to-SQL: it returns the right tables, columns and candidate rows; your LLM writes the actual SQL. Validation: 7/7 answerable queries on the reference experiment.

`rekall search`

rekall search "<query>" [--store <name>] [--hops 4] [--max-results 5] [--min-score 0.5] [--filter k=v] [--trace] [--json] [-i]

Run the reasoning loop. Human output by default (always shows the latency / hops / confidence line); --json for scripts.

Flag	Default	Description
`--store <name>`	default store	Override which store to search.
`--hops <n>`	`6`	`max_hops` ceiling (1–8). The loop stops the moment it finds the answer.
`--max-results <n>`	`5`	Maximum passages to return (1–50), relevance-ordered.
`--min-score <s>`	`0`	Drop passages below this relevance probability (0–1).
`--filter <k=v>`	—	Metadata equality filter, repeatable — all pairs must match exactly. `--filter color=blue --filter type=t-shirt` searches only blue t-shirts.
`--answer`	off	Synthesize a grounded short answer from the evidence, with passage citations — or `unknown` when unsupported. Needs `REKALL_ENRICH_*` locally, or a server-side answer backend.
`--trace`	off	Render the hop-by-hop reasoning tree. Near-zero cost.
`--json`	off	Emit the `SearchResult` JSON verbatim.
`-i`	off	Interactive REPL (readline) for repeated queries.

rekall search "which supplier contract conflicts with the 2026 policy?" --store demo --trace

Output

● 2 passages · 2 hops · confidence 0.87 · 4.2 ms

  1. supplier_a.pdf     score 0.92   hop 1
     "…Supplier A payment terms are net-90 as amended in §4.2…"
  2. policy_2026.md     score 0.81   hop 2
     "…all supplier payment terms must not exceed net-60…"

  reasoning trace
  hop 1 → supplier_a.pdf   (matches query)
  hop 2 → policy_2026.md   (conflict found, given hop 1)
  ✓ sufficient — stopped after 2 of 4 max hops

--json for scripts

rekall search "late payment penalties" --store demo --json | jq '.confidence, .hops_used, .latency_ms'

`rekall stores`

Manage stores. store works as an alias.

rekall stores list             # ● marks the default store
rekall stores create <name>    # created stores become the default
rekall stores use <name>       # set the default store for this project
rekall stores stats [name]     # defaults to the default store
rekall stores delete <name>    # always explicit — no default here

The default store

Every command that takes --store treats it as an override. Without it, the store resolves to: the configured default (rekall stores use <name>) → the only store, when exactly one exists. Creating a store makes it the default. The resolved store is always announced on stderr — visible to you, invisible to anything piping stdout:

$ rekall search "why has finance flagged Acme's payment terms?"
store: demo (default — override with --store)
● 2 passages · 2 hops · confidence 0.87 · 4.2 ms
…

rekall stores stats demo

store demo  (st_8c2hd0)
  documents   287
  size        5.0 MB
  created     2026-07-04T12:00:00Z

`rekall docs`

Manage documents within a store.

rekall docs list                    # every document: id, tokens, ingested-at
rekall docs show <id>               # one document: size, metadata, preview
rekall docs show <id> --text        # …with the full content
rekall docs delete <id>             # remove it — searchable set updates instantly

All take --store <name> to override the default store.

rekall docs list --store demo

id            n_tokens   ingested_at
supplier_a    4213       2026-07-04T12:00:00Z
policy_2026   1876       2026-07-04T12:00:01Z
… 285 more

`rekall serve` (Enterprise)

rekall serve --port 8080

rekall serve runs the SKIM engine itself — the same API as the managed cloud, on your own CPU. It requires a licensed model artifact and is available only under an enterprise self-hosting license, so it is not part of the standard client. Full details, including the REKALL_MODEL_URI / REKALL_DATA_DIR configuration, are in the Self-hosting (Enterprise) guide.

`rekall mcp`

rekall mcp

Run a stdio MCP server exposing your stores as tools for Claude Code / Desktop / Cursor. See the MCP guide.

`rekall keys`

Manage API keys on an enterprise self-hosted deployment. On the managed cloud, create and revoke keys in the dashboard instead.

rekall keys create      # prints a new rk_… key once — store it
rekall keys list
rekall keys revoke <key>

rekall keys create

✓ created key rk_8c2hd0…  (shown once — save it now)

Global flags & environment

Try it with the sample corpus

`rekall ingest`

`rekall add`

`rekall ingest-db`

`rekall search`

`rekall stores`

The default store

`rekall docs`

`rekall serve` (Enterprise)

`rekall mcp`

`rekall keys`

Next steps

Ingestion

Search

Errors

On this page