CLI flags

Every relate CLI flag with its argument, default, scope and environment variable at a stable anchor, plus how flags parse and the environment the CLI reads.

cli

Each flag of the relate CLI has a row on this page at a stable anchor, https://relatedb.ai/docs/reference/cli/flags#<flag> (#read-only, #max-rows); a command's own flag carries the command's name (#serve-mcp, #clone-wal-dir). A row gives the flag's other spellings, its argument, its default, where it applies, and the environment variable that sets its default. The tables are generated from the data file the CLI facts are recorded in, so the page and its markdown twin list the same flags.

Synopsis

relate [OPTIONS] [--database PATH] [QUERY]
relate <COMMAND> [ARGS]
relate query [STATEMENT] [--database PATH]

The query-run flags (OPTIONS) apply to the path-first form and to relate query. A command takes only its own flags, listed under Command flags; relate serve also takes seven query-run flags, named in its table. The sections before the tables explain the flag families whose behavior a one-line row cannot carry.

How flags are parsed

Rule	Behavior
Values	A flag's value is the next argument: `--mode envelope`. The `=` form is an unknown flag (`--mode=envelope` exits 2).
The one attached value	`--read-only` takes its optional value attached, `--read-only=live`. `--read-only live` exits 2 with `Error: --read-only takes its value attached: --read-only=live`.
Position	Query-run flags may come before or after the statement: `relate "RETURN 1 AS ok" --mode envelope` runs.
One statement argument	A second positional statement exits 2 with `Error: unexpected argument: <statement>`. `--command` and a positional statement together exit 2 with `Error: --command cannot be combined with a positional query`.
Other spellings	Short forms `-d` (`--database`), `-c` (`--command`), `-h` (`--help`) and `-v` (`--version`); single-dash forms `-json`, `-csv`, `-jsonl`, `-markdown`, `-noheader`, `-param` and `-version`.
Repeated flags	`--param` and `--fetch-params` repeat, one parameter each; a `--param` name bound twice keeps the last value. `--read-only` may appear once: a second exits 2 with `Error: relate --read-only may be given only once`.
Pairs and output flags	Of `--safe` and `--no-safe`, or `--agent-mode` and `--no-agent-mode`, the last one given wins. Of several output-mode flags (`--mode`, `--format`, `--json`, `--csv`, `--jsonl`, `--markdown`, `--toon`), the last one wins.
Precedence	A flag beats its environment variable, which beats the built-in default.
Unknown flags	Exit 2 with three lines on stderr: `Error: unknown flag: <flag>`, the usage line, and `Run 'relate --help' for more information.` A close match to a real flag adds `Did you mean '<flag>'?` after the first line.
`--`	Every argument after it is positional.

A misspelled flag gets its suggestion:

relate --readonly "RETURN 1 AS ok"
echo "exit=$?"

Error: unknown flag: --readonly
Did you mean '--read-only'?
Usage: relate [OPTIONS] [--database PATH] [QUERY]
Run 'relate --help' for more information.
exit=2

Output

Output modes shows each mode's shape on stdout. Without an output flag, the mode depends on where stdout goes:

stdout	Default mode
A terminal	`table`
A pipe or a file	`jsonl`
A pipe or a file, with agent mode on	`toon`

An explicit mode always overrides the default. --json, --csv, --jsonl, --markdown and --toon are shortcuts for --mode <name>, and --format is an alias of --mode. --output and -o are unknown flags whose suggestion names --format.

Mode	Prints
`table`	A human table; control characters escaped
`csv`	RFC 4180 CSV; a value starting with `=`, `+`, `-` or `@` gets a `'` prefix, so `-5` prints as `'-5`
`json`	One JSON array; indented on a terminal, one compact line when piped
`jsonl`	One JSON object per row
`envelope`	One compact JSON object per result set; fields on the agent mode page
`markdown`	A GitHub-flavored table; `\|` escaped
`cypher`	Each row as a Cypher `CREATE` statement
`toon`	One `rows[N]{cols}:` header, then one line per row; nested values as inline JSON
`speedscope`	A `PROFILE` plan tree as one speedscope profile JSON document

--pretty indents json output when stdout is not a terminal; the other modes ignore it. --noheader drops the header row of table and csv; markdown and toon keep theirs. --width N wraps the table mode to N columns; a value under 20 exits 2, and without it the width is the terminal's, else COLUMNS, else the natural width.

Store and storage

--database PATH names the store A relate database: a directory, a single .rl file, or :memory:, opened with --database. Read more in the glossary: a directory (a snapshot plus a WAL Append-only log each commit goes to before it applies; under the default full durability mode it is synced first, so a crash loses no acknowledged write. Read more in the glossary), a single-file .rl store, or :memory:, the default. It is never a URL; a remote store is a --load source.

Flag	Behavior
`--load SOURCE`	Loads a store from a local `.rl` file, a directory, or an `https` URL to a `.rl` file. Into `:memory:`, the store opens read-only and the source is released after the load. Into a `--database` path that does not exist yet, the source is copied there and the store opens normally. A URL is fetched to a private temporary copy that is not kept.
`--read-only[=snapshot\|live]`	Opens an existing store without writing, checkpointing or migrating it; every write exits 6. `snapshot`, the default, freezes the state at open; `live` follows a directory store's WAL and is refused for `.rl` and `:memory:`. A directory store can be open read-only beside its writer; a `.rl` store only while no writer holds it.
`--namespace NAME`	The namespace a statement without `USE` targets: `neo4j` (default), `system` or `system_ontologies`.
`--wal-dir DIR`	The WAL directory of a directory store, default `<DATABASE>/wal`.
`--snapshot-format F`	The codec of an empty directory store: `parquet` (default), `json` or `markdown`. `parquet-wide` is the `parquet` codec with one typed column per common property key; it also applies to an existing `parquet` store, which its next checkpoint converts, and the store stays wide. An existing store keeps its recorded codec; naming a different one exits 1 with `storage error: snapshot codec mismatch: directory is <codec>, requested <codec>`. Also accepted by `relate serve`.
`--markdown-body-properties LIST`	The properties a `markdown` store writes as note bodies; default `body`.
`--durability-mode MODE`	`full` (default) syncs each commit before it is acknowledged. `everysecond` can lose about the last second of acknowledged writes in a crash. `snapshot` can lose every write since the last completed checkpoint.
`--checkpoint-interval-secs N`	The timed checkpoint period, default `300`; `0` turns the timer off. Persistent stores only. Not accepted by `relate serve`, which reads only `RELATE_CHECKPOINT_INTERVAL_SECS`.

The durability modes guide covers choosing a loss window, and storage formats covers the store forms.

Safety

--read-only and --safe are off unless given, and agent detection switches neither on.

Flag	Default	Refuses or bounds	Exit code
`--read-only`	off	Every write: `WriteOnReadOnlyAccessDatabase`	6
`--safe`	off	A new named node without a label, and a `MATCH` read whose final `RETURN` or `WITH` has no `LIMIT` and no reducing aggregate (`collect()` does not count): `SafeModeViolation`. Also a remote `--load` source.	6; 2 for the remote `--load`
`--load-csv-dir PATH`	denied	Local `LOAD CSV` outside `PATH`; a file over 8 MiB, a limit no flag raises	1
`--max-traversal-depth N`	`500`	An explicit hop bound over `N` (1 through 2000): `TraversalDepthExceeded`	6
`--fetch-params N=SRC`	unset	A fetched file over 64 MiB, or a fetch over 60 seconds. There is no URL allowlist: the fetch runs in the CLI process with the same trust as `--param`.	1

--no-safe turns safe mode off, including when RELATE_SAFE_MODE=1 set it. The errors behind the exit code The number a relate run returns to the shell; each nonzero value names a class of failure, such as 2 for usage, 5 for conflict, 6 for a rejected statement. Read more in the glossary are in the errors reference.

Memory limits

A SIZE is a number of bytes, or a number with mb, mib, gb or gib. A statement that exceeds --logical-graph-size-limit or --expression-memory-limit fails with the error kind capacity and exit code 1, and is not retryable.

Flag	Default	Bounds
`--logical-graph-size-limit SIZE`	unlimited	The live graph plus its indexes, in logical bytes; `0` is unlimited
`--expression-memory-limit SIZE`	`256 MiB`	One value a statement builds; `none` or `0` turns the cap off
`--concurrent-logical-workspace-limit SIZE`	admission off	A shared workspace pool; a positive value turns query admission on, and `0` is rejected

Size a store and its memory works through a sizing.

Timeouts

--timeout DURATION bounds each statement's wall-clock time. A bare number is seconds; ms, s and m suffixes and fractions are accepted; 0 turns the bound off, and unset means no bound. A statement that runs longer is cancelled and exits 7 with Error: query timed out after <duration> on stderr; the error object's code is timeout, its kind is execution, and retryable is false. A value that is not a duration exits 2:

relate --timeout soon "RETURN 1 AS ok"
echo "exit=$?"

Error: invalid --timeout: 'soon' is not a duration (try 500ms, 10s, 2m)
exit=2

relate serve has its own deadlines instead: --tx-idle-timeout-secs (default 60), --header-deadline-secs (default 10) and --body-deadline-secs (default 60), in its table.

Agent ergonomics

--agent-mode and --no-agent-mode turn agent mode CLI defaults for a detected agent harness on a non-terminal stdout, or forced on: at most 100 rows printed per statement, the cut reported, TOON in a pipe. Read more in the glossary on or off: the 100-row cap default and the piped toon default. --max-rows N sets the cap directly; 0 prints every row. The agent mode page has the detection rules and what each output mode prints when the cap cuts a result.

Query-run flags

The flags of the path-first form and of relate query. The relate query reference has the session forms and their errors.

Flag	Argument	Default	Scope	Since	Description
`--database`, `-d`	`PATH`	`:memory:`	query run	—	The store target: a directory, a `.rl` file (legacy `.cl` files still open), or `:memory:`. Never a URL; a remote store is a `--load` source.
`--command`, `-c`	`CYPHER`	unset	query run	—	One statement or a `;`-separated list; the same as the positional QUERY, and the two cannot be combined.
`--load`	`SOURCE`	unset	query run	—	Load a store's content from a source (a local `.rl` file, a directory, or an http(s) URL to a `.rl` file) into the target: into `:memory:` it is an ephemeral read-only open; into a new `-d PATH` it creates the store.
`--mode`	`MODE`	table on a terminal; jsonl when stdout is piped or redirected; toon instead of jsonl when agent mode is on	query run	—	Output mode: `table`, `csv`, `json`, `jsonl`, `envelope`, `markdown`, `cypher`, `toon`, `speedscope`. An explicit mode always overrides the default.
`--format`	`MODE`	as --mode	query run	—	Alias of `--mode` (the neo4j-cli spelling). `--output` and `-o` are unknown flags whose did-you-mean names `--format`.
`--json` also `-json`	—	off	query run	—	Shortcut for `--mode json`: one object per result set with the rows in `data`; indented on a terminal, one compact line when piped.
`--csv` also `-csv`	—	off	query run	—	Shortcut for `--mode csv`.
`--jsonl` also `-jsonl`	—	off	query run	—	Shortcut for `--mode jsonl`.
`--markdown` also `-markdown`	—	off	query run	—	Shortcut for `--mode markdown`.
`--toon`	—	off	query run	—	Shortcut for `--mode toon`.
`--pretty`	—	off	query run	—	Force indented `json` output when stdout is not a terminal; ignored by the other modes.
`--noheader` also `-noheader`	—	off	query run	—	Suppress column headers.
`--param` also `-param`	`N=V`	unset	query run	—	Bind a Cypher parameter (repeatable). A value that parses as JSON keeps its JSON type (`true`, `null` and numbers included); a value that starts with a digit, `-`, `"`, `[` or `{` and does not parse exits 2; any other value binds as a string.
`--fetch-params`	`N=SRC`	unset	query run	—	Fetch an http(s) URL or read a file, parse it as JSON, and bind it as parameter N (repeatable; 64 MiB cap, 60 s timeout). A CLI-process fetch with no URL allowlist.
`--snapshot-format`	`parquet\|json\|markdown\|parquet-wide`	parquet (json in builds without the parquet feature)	query run	—	Snapshot codec for an empty directory; an existing store keeps its recorded codec, and a different codec fails the open (exit 1). `parquet-wide` is the `parquet` codec with one typed column per common property key (format version 5): on an empty directory it creates a wide store, on an existing `parquet` store the next checkpoint re-encodes every part, and the manifest keeps the store wide after that. Environment: `RELATE_SNAPSHOT_FORMAT`.
`--markdown-body-properties`	`LIST`	`body`	query run	—	Body properties of a markdown-codec store (`LIST` or `Label=LIST`; entries separated by `;`; the first is written bare, the rest as `##` sections).
`--wal-dir`	`PATH`	`<DATABASE>/wal`	query run	—	Local WAL directory for a directory store; rejected for `.rl` files.
`--checkpoint-interval-secs`	`N`	`300`	query run	—	Timed checkpoint period; `0` disables the timer. Persistent stores only. Environment: `RELATE_CHECKPOINT_INTERVAL_SECS`.
`--durability-mode`	`full\|everysecond\|snapshot`	`full`	query run	—	Commit durability policy. `everysecond` can lose about the last second of acknowledged writes in a crash; `snapshot` can lose every write since the last completed checkpoint. Environment: `RELATE_DURABILITY_MODE`.
`--logical-graph-size-limit`	`SIZE`	unlimited	query run	—	Live graph and index cap in logical bytes; `0` or unset is unlimited. Environment: `RELATE_LOGICAL_GRAPH_SIZE_LIMIT`.
`--expression-memory-limit`	`SIZE`	256 MiB	query run	—	Per-allocation expression cap; `none` or `0` disables it. Environment: `RELATE_EXPRESSION_MEMORY_LIMIT`.
`--concurrent-logical-workspace-limit`	`SIZE`	admission off	query run	—	Shared logical-workspace pool; a positive value turns query admission on; `0` is rejected. Environment: `RELATE_CONCURRENT_LOGICAL_WORKSPACE_LIMIT`.
`--max-traversal-depth`	`N`	`500`	query run	—	Largest explicit traversal hop bound (1 through 2000); a larger bound fails at admission with `TraversalDepthExceeded`. Environment: `RELATE_MAX_TRAVERSAL_DEPTH`.
`--safe`, `--no-safe`	—	off	query run	—	Opt-in safe mode: refuses a new named node without a label, and a `MATCH` read whose final `RETURN`/`WITH` has no `LIMIT` and no reducing aggregate, as `SafeModeViolation` (exit 6). Environment: `RELATE_SAFE_MODE`.
`--timeout`	`DURATION`	unset (no bound)	query run	—	Per-statement wall-clock bound: a bare number is seconds, `ms`/`s`/`m` suffixes, fractions allowed; `0` disables. A timed-out statement exits 7 with `code: "timeout"`.
`--max-rows`	`N`	100 under a detected agent harness with stdout not a terminal; otherwise unlimited	query run	—	Rows printed per statement; `0` is unlimited. A cut result warns on stderr, names the cut in-band in the machine modes, and exits 0. Environment: `RELATE_MAX_ROWS`.
`--width`	`N`	the terminal width, else COLUMNS, else the natural width	query run	—	Wrap the human `table` output to N columns; a value under 20 exits 2.
`--read-only`	`[=snapshot\|live]`	off	query run	—	Open an existing store without writing, checkpointing or migrating. `snapshot` (default) freezes the state at open; `live` tails a directory store's WAL (refused for `.rl` and `:memory:`). Attached form only; once only. A write fails with exit 6.
`--load-csv-dir`	`PATH`	denied	query run	—	Allow local `LOAD CSV` only for regular files under this directory; per-file limit 8 MiB. Environment: `RELATE_LOAD_CSV_DIR`.
`--namespace`	`NAME`	`neo4j`	query run	—	Session namespace for the run: `neo4j`, `system` or `system_ontologies` (case-insensitive). Not accepted by `pull`.
`--agent-mode`, `--no-agent-mode`	—	detected (stdout not a terminal and an agent harness variable set)	query run	—	Turn agent ergonomics (the row-cap default and the piped `toon` default) on or off unconditionally; overrides `RELATE_AGENT_MODE` and detection. Environment: `RELATE_AGENT_MODE`.
`--help`, `-h`	—	—	query run	—	Print usage to stdout and exit 0; after a command word, that command's help.
`--version` also `-version`, `-v`	—	—	query run	—	Print `Relate v<version>` and `License: Apache 2.0 (binary)`; with `--json`, one JSON object with `arch`, `license`, `name`, `os`, `version`.
`--`	—	—	query run	—	Treat all following arguments as positional.