CLI Reference — StrataDB Docs

Docs menu · Reference

Interim page. Maintained by hand until it is generated from the resolved command index (IDL). Where this page and strata agents commands --json disagree, the command index wins.

strata is a single binary. It opens one file-backed database — or an in-memory one — and runs commands against it. There is no server and no daemon.

For the full list of commands, see the Command Reference. This page covers how you invoke the binary itself.

Invocation forms

strata ./my-db kv put greeting hello   # one-shot command against a durable database
strata ./my-db                         # open the interactive REPL (on a TTY)
strata --cache kv put greeting hello   # one-shot against an ephemeral in-memory database
strata --cache                         # REPL against an ephemeral database
strata agents guide                    # a command that needs no database

A one-shot invocation runs a single command and exits. Passing a database path with no command opens the REPL when standard input is a terminal; when input is piped, strata reads one command per line instead.

Targeting a database

strata never opens the current directory implicitly. A command that touches data must name its target one of three ways, in priority order:

A path — the positional argument or --db <path>. Always wins. A relative or absolute directory; it is created if it does not exist.
STRATA_DB=<path> — an environment variable, used when no path is passed.
--cache — an explicit in-memory database. Nothing is persisted. Cannot be combined with a path or --db.

A data command with no target refuses:

$ strata ping
error: [invalid_argument.cli.no_database]: no database specified
  hint: pass a path (strata ./mydb kv put …), set STRATA_DB, or use --cache for ephemeral

A handful of commands need no database at all — strata init, strata agents guide, strata config path, and the like.

See Database Configuration for what durable and cache mode mean, and Durability for the underlying model.

Global options

These appear before the command. --branch and --space are also accepted after any command that operates on data, so either position works.

Option	Description
`[DB]`	Positional durable database path
`--db <PATH>`	Durable database path. Cannot be combined with the positional path
`--cache`	Use an in-memory cache database for this process
`--branch <BRANCH>`	Default branch for commands that accept a branch
`--space <SPACE>`	Product space for commands that accept a space
`--json`	Emit compact JSON
`--raw`	Emit script-friendly raw output where possible
`-h, --help`	Print help
`-V, --version`	Print the version

Branches and spaces are the two organizing dimensions of a database. See Branches, Branch Management, and Spaces.

Output formats

Every command emits one of three shapes, chosen by the global flag.

Human (default)

Readable output. Stored bytes are decoded to text when they are valid UTF-8.

$ strata ./my-db kv put greeting hello
created greeting applied=true

$ strata ./my-db kv get greeting
hello

`--json`

One compact envelope per command, shaped {"type": …, "data": …}. KV keys and values, and continuation cursors, are base64 strings on the wire.

$ strata --json ./my-db kv get greeting
{"data":{"timestamp":3,"value":"aGVsbG8=","version":3},"type":"kv_versioned_value"}

Failures are also envelopes, printed on stderr with a non-zero exit:

$ strata --json ./my-db vector get missing k1
{"error":{"class":"not_found","code":"not_found.engine.vector_collection","retryable":false,"message":"vector collection does not exist","docs_url":"https://stratadb.org/e/not_found.engine.vector_collection", …}}

`--raw`

Bare values, for scripts and pipelines.

$ strata --raw ./my-db kv get greeting
hello

Continuation cursors are opaque base64 tokens. Pass a printed cursor back verbatim through --cursor to fetch the next page. Time-travel reads take --as-of <commit>, where the value is the commit clock from a write receipt (data.commit.timestamp, a small integer), not a wall-clock time; see Commits.

Command families

Every command belongs to a family. The Command Reference lists them all.

Command	Description
`init`	Prepare the Strata home directory and print next steps
`doctor`	Check the installation and, when a database is targeted, its health
`agents`	Self-describing surface for agents: guide, catalogs, repo onboarding
`mcp`	Model Context Protocol server commands
`ping`	Lightweight liveness check
`info`	Print database information
`health`	Print health facts
`metrics`	Print metrics facts
`describe`	Print a compact database description
`config`	Configuration reads
`remote`	Show where this database was cloned from (its remote origin)
`clone`	Clone a dataset from a hub into a new local database
`branch`	Branch lifecycle commands
`space`	Product space commands
`kv`	KV commands
`json`	JSON document commands
`vector`	Vector commands
`event`	Event log commands
`graph`	Graph core commands
`arrow`	Arrow import/export commands
`inference`	Model execution: local GGUF models and cloud providers
`command`	Raw serialized executor command

Interactive REPL

Opening a database with no command on a terminal starts the REPL. The prompt shows the current branch and space:

strata:default/default>

Each line is a command in the same grammar as the one-shot form — kv put a 1, branch list, vector query docs "[0.1,0.2]" -k 5. Lines beginning with # are ignored. A few words are handled by the REPL itself rather than as database commands:

Word	Effect
`use <branch>`	Switch the current branch (validated to exist)
`use <branch>/<space>` or `use <branch> <space>`	Switch branch and space
`help`	Print the full command help
`clear`	Clear the screen
`quit` / `exit`	Leave the REPL

Ctrl-D also exits. History is written to ~/.strata_history (override with STRATA_HISTORY).

Commands from the old CLI

Several verbs from the pre-V1 CLI are recognized but not part of the V1 surface. They refuse with a clear message rather than being silently unknown:

$ strata --cache txn
error: `txn` is recognized from the old CLI, but is not available in the V1 CLI surface yet

The recognized-but-refused verbs are begin, commit, rollback, txn, search, recipe, flush, compact, up, down, and uninstall. In V1 writes auto-commit, so there are no explicit transaction verbs; there is no state-cell capability.