---
title: CLI flags
description: "relate, the embedded Cypher graph database (relatedb.ai): 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."
type: reference
surfaces:
  - cli
status: stable
verified: 0.1.2
verified_by:
  - cli
canonical_url: https://relatedb.ai/docs/reference/cli/flags/
prerequisites: []
related:
  - reference/cli
  - reference/cli/agent-mode
  - reference/cli/exit-codes-and-errors
  - guides/operate/durability-modes
  - guides/cli/scripting
  - reference/cli/output-modes
  - reference/cli/environment-variables
last_updated: 2026-11-09
---

# 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.

> Verified against relate 0.1.2. If your `relate --version` is newer, read https://relatedb.ai/docs/reference/changelog/#since-0.1.2

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

```text
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](#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:

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

```text
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](https://relatedb.ai/docs/reference/cli/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](https://relatedb.ai/docs/reference/cli/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](https://relatedb.ai/docs/reference/cli/agent-mode/#the-envelope) |
| `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](https://relatedb.ai/docs/reference/glossary/#store): a directory (a snapshot plus a [WAL](https://relatedb.ai/docs/reference/glossary/#wal)), 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](https://relatedb.ai/docs/reference/glossary/#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](https://relatedb.ai/docs/guides/operate/durability-modes/) covers choosing a loss window, and [storage formats](https://relatedb.ai/docs/reference/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 codes](https://relatedb.ai/docs/reference/glossary/#exit-code) are in the [errors reference](https://relatedb.ai/docs/reference/errors/#engine-safe-mode-violation).

## 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](https://relatedb.ai/docs/guides/operate/sizing-and-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:

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

```text
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](https://relatedb.ai/docs/reference/glossary/#agent-mode) 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](https://relatedb.ai/docs/reference/cli/agent-mode/) 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](https://relatedb.ai/docs/reference/cli/query/) 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`](https://relatedb.ai/docs/reference/cli/flags/#env-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`](https://relatedb.ai/docs/reference/cli/flags/#env-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`](https://relatedb.ai/docs/reference/cli/flags/#env-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`](https://relatedb.ai/docs/reference/cli/flags/#env-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`](https://relatedb.ai/docs/reference/cli/flags/#env-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`](https://relatedb.ai/docs/reference/cli/flags/#env-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`](https://relatedb.ai/docs/reference/cli/flags/#env-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`](https://relatedb.ai/docs/reference/cli/flags/#env-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`](https://relatedb.ai/docs/reference/cli/flags/#env-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`](https://relatedb.ai/docs/reference/cli/flags/#env-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`](https://relatedb.ai/docs/reference/cli/flags/#env-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. |

A — under Since: the data does not record the release that added the flag.

## Command flags

Each command's own flags. `relate query` takes the query-run flags; `relate telemetry` and `relate agent-context` take no flags beyond `--help`.

### `relate clone`

The [`relate clone` reference](https://relatedb.ai/docs/reference/cli/clone/) has the layouts each pairing writes and its errors.

| Flag | Argument | Default | Scope | Since | Description |
| --- | --- | --- | --- | --- | --- |
| `--wal-dir` | `DIR` | `<SOURCE>/wal` | `relate clone` | — | Source WAL of a directory source; fails with a `.rl` source. |
| `--to-snapshot-format` | `parquet\|json\|markdown` | the source codec | `relate clone` | — | Destination snapshot codec (`parquet`, `json` or `markdown`); transcodes the published checkpoint. |
| `--markdown-body-properties` | `LIST` | the source's recorded configuration, else body | `relate clone` | — | Body properties of a markdown destination (`LIST` or `Label=LIST`; entries separated by `;`). |

A — under Since: the data does not record the release that added the flag.

### `relate info`

The [`relate info` reference](https://relatedb.ai/docs/reference/cli/info/) has the fields it prints and its errors.

| Flag | Argument | Default | Scope | Since | Description |
| --- | --- | --- | --- | --- | --- |
| `--database`, `-d` | `PATH` | `required` | `relate info` | — | Store to inspect: a directory or a `.rl` file. |
| `--json` | — | off | `relate info` | — | One JSON object instead of the key/value table. |

A — under Since: the data does not record the release that added the flag.

### `relate pull`

The [`relate pull` reference](https://relatedb.ai/docs/reference/cli/pull/) has the credentials, the query rules and the errors.

| Flag | Argument | Default | Scope | Since | Description |
| --- | --- | --- | --- | --- | --- |
| `--from` | `FILE` | the process environment | `relate pull` | — | Env file with `NEO4J_URI`, `NEO4J_USERNAME`, `NEO4J_PASSWORD`, `NEO4J_DATABASE`; omitted, those process environment variables are used. |
| `--query` | `Q` | `required` | `relate pull` | — | A statement, a `;`-separated list, a file path, or `-` for stdin; every statement must `RETURN` graph elements. All run in one process, with one checkpoint at the end. |
| `--param` | `N=V` | unset | `relate pull` | — | Bind a source query parameter (repeatable). |
| `--allow-plaintext` | — | off | `relate pull` | — | Permit Basic auth to a non-loopback `http://` Query API (insecure; prints a warning). |
| `--database`, `-d` | `PATH` | `required` | `relate pull` | — | Destination directory or `.rl` file; not `:memory:`. |

A — under Since: the data does not record the release that added the flag.

### `relate push`

The [`relate push` reference](https://relatedb.ai/docs/reference/cli/push/) has the selectors, the merge keys, the dry-run plan and the errors.

| Flag | Argument | Default | Scope | Since | Description |
| --- | --- | --- | --- | --- | --- |
| `--to` | `CREDS` | `required` | `relate push` | — | Env file (`NEO4J_URI`, `NEO4J_USERNAME`, `NEO4J_PASSWORD`, optional `NEO4J_DATABASE`), or a Query API URI with the username and password from the process environment. |
| `--database`, `-d` | `PATH` | `required` | `relate push` | — | Source store directory or `.rl` file; not `:memory:`. |
| `--query` | `Q` | the whole store | `relate push` | — | Push only what the statements return (nodes, relationships, paths); a `;`-list, file path, or `-` for stdin. One of `--query`, `--labels`, `--types`. |
| `--labels` | `L1,L2` | unset | `relate push` | — | Only nodes with these labels, and the relationships between them. |
| `--types` | `T1,T2` | unset | `relate push` | — | Only relationships of these types, with both their endpoints. |
| `--batch-size` | `N` | `5000` | `relate push` | — | Rows per batched statement. |
| `--nodes-update` | `POLICY` | `add` | `relate push` | — | `add` (`SET +=`, keeps remote-only properties), `replace` (`SET =`) or `skip` (create missing only), per label or global. |
| `--rels-update` | `POLICY` | `add` | `relate push` | — | The same policies, per relationship type or global. |
| `--updated-at` | `NAME[,NAME]` | unset | `relate push` | — | Candidate timestamp properties; when both sides carry one, a strictly newer remote row is skipped. |
| `--rel-mode` | `MODE` | `keyed` | `relate push` | — | `keyed` (merge on the type's resolved key), `structural` (one relationship of a type between two nodes) or `create` (non-idempotent). |
| `--merge-key` | `LABEL:PROP[,PROP]` | the constraint-derived key | `relate push` | — | Merge key for one label (repeatable). |
| `--rel-key` | `TYPE:PROP[,PROP]` | the constraint-derived key | `relate push` | — | Merge key for one relationship type (repeatable). |
| `--unkeyed-labels` | `ACTION` | `skip` | `relate push` | — | `skip` (reported and counted) or `create` (non-idempotent) for a label with no merge key. |
| `--dry-run` | — | off | `relate push` | — | Print the plan without touching the remote. |
| `--json` | — | off | `relate push` | — | Print the run report as one JSON object instead of the table. |
| `--allow-plaintext` | — | off | `relate push` | — | Permit Basic auth to a non-loopback `http://` Query API (insecure; prints a warning). |

A — under Since: the data does not record the release that added the flag.

### `relate skill`

The [`relate skill` reference](https://relatedb.ai/docs/reference/cli/skill/) has the agent directories and the errors.

| Flag | Argument | Default | Scope | Since | Description |
| --- | --- | --- | --- | --- | --- |
| `--agent` | `NAME` | all detected agents | `relate skill` | — | Scope the action to one agent (case-insensitive). |
| `--force` | — | `refuse` | `relate skill` | — | Clobber `<skills dir>/relate` even when the command would refuse it; a usage error on `list` and `check`. |

A — under Since: the data does not record the release that added the flag.

### `relate upgrade`

The [`relate upgrade` reference](https://relatedb.ai/docs/reference/cli/upgrade/) has what it checks and replaces, and its errors.

| Flag | Argument | Default | Scope | Since | Description |
| --- | --- | --- | --- | --- | --- |
| `--yes` | — | off | `relate upgrade` | — | Install the skill bundle after the upgrade when none is installed yet, without a prompt. |
| `--check` | — | off | `relate upgrade` | — | Read-only report of the current and latest versions. |

A — under Since: the data does not record the release that added the flag.

### `relate run`

The [`relate run` reference](https://relatedb.ai/docs/reference/cli/run/) has how an action runs and its errors.

An installed extension's own flags come from its manifest; `relate run --help` lists the installed actions.

| Flag | Argument | Default | Scope | Since | Description |
| --- | --- | --- | --- | --- | --- |
| `--database`, `-d` | `PATH` | `:memory:` | `relate run` | — | Store to import into; an explicit `--database` exits after the import, and without it a terminal opens the shell on the in-memory graph. |

A — under Since: the data does not record the release that added the flag.

### `relate serve`

The [`relate serve` reference](https://relatedb.ai/docs/reference/cli/serve/) has the listeners, the startup lines and the errors.

| Flag | Argument | Default | Scope | Since | Description |
| --- | --- | --- | --- | --- | --- |
| `--database`, `-d` | `PATH` | `required` | `relate serve` | — | The store to serve: a directory, a `.rl` file, or `:memory:`. |
| `--host` | `HOST` | `127.0.0.1` | `relate serve` | — | Bind host for every served surface; a non-loopback value exposes the plaintext surfaces and prints a startup WARNING. |
| `--http` | `PORT` | unset | `relate serve` | — | HTTP Query API v2 on HOST:PORT. |
| `--mcp` | `PORT\|stdio` | unset | `relate serve` | — | MCP: `stdio` runs the stdio transport in the foreground (no auth); `PORT` serves streamable HTTP. |
| `--bolt` | `PORT` | unset | `relate serve` | — | Bolt and Bolt-over-WebSocket on HOST:PORT. |
| `--bolt-identity` | `STRING` | `Relate/<version>` | `relate serve` | — | HELLO SUCCESS `server` agent string for the Bolt surface. Environment: [`RELATE_IDENTITY`](https://relatedb.ai/docs/reference/cli/flags/#env-relate-identity). |
| `--read-only` | `[=snapshot\|live]` | unset | `relate serve` | — | Open the existing store read-only: no writer lease, never creates it, every write fails; `live` tails the WAL (directories only). The MCP surface does not list `write_cypher`. |
| `--load` | `SOURCE` | unset | `relate serve` | — | Load a store from a source (a local `.rl`, a directory, or an http(s) URL to a `.rl`) into `--database`. |
| `--auth` | `USER:PASSWORD\|none` | a generated token | `relate serve` | — | One basic-auth credential shared by every served listener; `none` disables authentication. HTTP transport only for MCP. Environment: [`RELATE_AUTH`](https://relatedb.ai/docs/reference/cli/flags/#env-relate-auth). |
| `--origin` | `ORIGIN` | loopback + https://browser.neo4j.io and https://console.neo4j.io | `relate serve` | — | Allow a browser Origin on the HTTP surface (repeatable; an explicit list replaces the default). |
| `--tx-idle-timeout-secs` | `N` | `60` | `relate serve` | — | Seconds an HTTP managed transaction may sit idle before it expires (404/`42N90`); `0` disables. Environment: [`RELATE_TX_IDLE_TIMEOUT_SECS`](https://relatedb.ai/docs/reference/cli/flags/#env-relate-tx-idle-timeout-secs). |
| `--max-open-transactions` | `N` | `128` | `relate serve` | — | Cap on open HTTP managed transactions; a begin over the cap answers 429/`42N91`; `0` is unlimited. Environment: [`RELATE_MAX_OPEN_TRANSACTIONS`](https://relatedb.ai/docs/reference/cli/flags/#env-relate-max-open-transactions). |
| `--max-connections` | `N` | `128` | `relate serve` | — | Process-wide session cap shared by every listener; `0` is unlimited. Environment: [`RELATE_MAX_CONNECTIONS`](https://relatedb.ai/docs/reference/cli/flags/#env-relate-max-connections). |
| `--ws-max-connections` | `N` | unlimited | `relate serve` | — | Cap on concurrent Bolt-over-WebSocket sessions. Environment: [`RELATE_WS_MAX_CONNECTIONS`](https://relatedb.ai/docs/reference/cli/flags/#env-relate-ws-max-connections). |
| `--ws-allow-origin` | `ORIGIN` | loopback plus https://browser.neo4j.io and https://console.neo4j.io with auth on; loopback only with --auth none | `relate serve` | — | Allow only the named Origins on Bolt-over-WebSocket upgrades (repeatable; an exact http(s) URL or * for any; replaces the default list). |
| `--header-deadline-secs` | `N` | `10` | `relate serve` | — | Absolute deadline for a complete HTTP or MCP request header block; `0` disables. Environment: [`RELATE_HEADER_DEADLINE_SECS`](https://relatedb.ai/docs/reference/cli/flags/#env-relate-header-deadline-secs). |
| `--body-deadline-secs` | `N` | `60` | `relate serve` | — | Absolute deadline for a complete HTTP or MCP request body; `0` disables. Environment: [`RELATE_BODY_DEADLINE_SECS`](https://relatedb.ai/docs/reference/cli/flags/#env-relate-body-deadline-secs). |
| `--snapshot-format` | `parquet\|json\|markdown\|parquet-wide` | `RELATE_SNAPSHOT_FORMAT`, else parquet | `relate serve` | — | Snapshot codec for the served store, with the values and resolution of the query session's `--snapshot-format`; `parquet-wide` opts the store into wide-column `parquet` parts, and the manifest keeps it wide. Environment: [`RELATE_SNAPSHOT_FORMAT`](https://relatedb.ai/docs/reference/cli/flags/#env-relate-snapshot-format). |
| `--concurrent-logical-workspace-limit`, `--max-traversal-depth`, `--safe`, `--no-safe`, `--logical-graph-size-limit`, `--expression-memory-limit`, `--durability-mode` | — | as the query-run flags | `relate serve` | — | The query session's flags of the same name, applied to the serve open with the same resolution. |

A — under Since: the data does not record the release that added the flag.

### `relate extension`

The [`relate extension` reference](https://relatedb.ai/docs/reference/cli/extension/) has each subcommand, the provenance marker and the errors.

| Flag | Argument | Default | Scope | Since | Description |
| --- | --- | --- | --- | --- | --- |
| `--lang` | `sh\|py\|ts\|rust` | `py` | `relate extension` | — | `init`: the template language. |
| `--github` | `REPO@TAG\|@SHA` | unset | `relate extension` | — | `install`: a GitHub release pinned to a commit; the tag's commit and the asset's SHA-256 are recorded. |
| `--url` | `URL` | unset | `relate extension` | — | `install`: the tarball at an `https` URL (third party). |
| `--from` | `DIR` | unset | `relate extension` | — | `install`: an unpacked package directory (local; no network, no signature). |
| `--version` | `V` | the newest listed | `relate extension` | — | `install`: the channel version. |
| `--force` | — | off | `relate extension` | — | `install`: clobber a target directory without the install marker. |
| `--re-approve` | — | off | `relate extension` | — | `install --github`: re-approve whatever the pin resolves to now. |
| `--approve` | `SHA` | unset | `relate extension` | — | `install --github`: re-approve only this commit. |
| `--available` | — | off | `relate extension` | — | `list`: the channel's catalog (the signed `extensions.json` index); fails closed offline. |
| `--trust` | — | off | `relate extension` | — | `list`: the recorded GitHub pins. |
| `--forget-pin` | — | off | `relate extension` | — | `remove`: also clear the name's recorded GitHub pin. |

A — under Since: the data does not record the release that added the flag.

## Environment variables

Every environment variable the CLI reads, with the flag or command it serves. A flag beats its variable. [Environment variables](https://relatedb.ai/docs/reference/cli/environment-variables/) adds the variables this table does not list and what an invalid value does. The [CLI errors](https://relatedb.ai/docs/reference/errors/#cli-errors) list the message an invalid value prints and its exit code.

| Variable | Effect | Default | Used by |
| --- | --- | --- | --- |
| `DO_NOT_TRACK` | `1`/`true` disables anonymous usage metrics; beats every other layer. | — | usage metrics |
| `RELATE_TELEMETRY` | `0`/`false`/`off` disables, `1`/`true`/`on` enables anonymous usage metrics. | — | usage metrics |
| `RELATE_AGENT_MODE` | `1` turns agent ergonomics on, `0` off; any other value exits 2. | — | [`--agent-mode / --no-agent-mode`](https://relatedb.ai/docs/reference/cli/flags/#agent-mode) |
| `RELATE_MAX_ROWS` | Default row cap per statement; `0` is unlimited; a bad value exits 2. | — | [`--max-rows`](https://relatedb.ai/docs/reference/cli/flags/#max-rows) |
| `RELATE_SAFE_MODE` | `1` turns safe mode on, `0` off; any other value exits 2. | off | [`--safe / --no-safe`](https://relatedb.ai/docs/reference/cli/flags/#safe) |
| `RELATE_PREVIEW` | Comma-separated preview Cypher features to enable (for example `ontology`, `hybrid-search`); an unknown name fails the open with exit 1. | nothing enabled | `relate query engine` |
| `RELATE_SNAPSHOT_FORMAT` | Default snapshot codec for an empty directory; on an existing store a different value fails the open (exit 1). | — | [`--snapshot-format`](https://relatedb.ai/docs/reference/cli/flags/#snapshot-format) |
| `RELATE_CHECKPOINT_INTERVAL_SECS` | Default timed checkpoint period. | `300` | [`--checkpoint-interval-secs`](https://relatedb.ai/docs/reference/cli/flags/#checkpoint-interval-secs) |
| `RELATE_DURABILITY_MODE` | Default commit durability policy: `full`, `everysecond` or `snapshot`; any other value exits 2. | `full` | [`--durability-mode`](https://relatedb.ai/docs/reference/cli/flags/#durability-mode) |
| `RELATE_LOGICAL_GRAPH_SIZE_LIMIT` | Default live graph and index cap; `0` or unset is unlimited. | unlimited | [`--logical-graph-size-limit`](https://relatedb.ai/docs/reference/cli/flags/#logical-graph-size-limit) |
| `RELATE_EXPRESSION_MEMORY_LIMIT` | Default per-allocation expression cap; `none`/`0` disables it. | 256 MiB | [`--expression-memory-limit`](https://relatedb.ai/docs/reference/cli/flags/#expression-memory-limit) |
| `RELATE_CONCURRENT_LOGICAL_WORKSPACE_LIMIT` | Default concurrent logical-workspace pool; a positive size turns admission on; `0` exits 2. | admission off | [`--concurrent-logical-workspace-limit`](https://relatedb.ai/docs/reference/cli/flags/#concurrent-logical-workspace-limit) |
| `RELATE_MAX_TRAVERSAL_DEPTH` | Default traversal-depth admission limit, 1 through 2000. | `500` | [`--max-traversal-depth`](https://relatedb.ai/docs/reference/cli/flags/#max-traversal-depth) |
| `RELATE_LOAD_CSV_DIR` | Fallback CSV directory when the flag is absent; neither set means local files are denied. An empty or blank value fails the open (exit 1, `Failed to open Relate: semantic error: LOAD CSV invalid configuration`). | denied | [`--load-csv-dir`](https://relatedb.ai/docs/reference/cli/flags/#load-csv-dir) |
| `RELATE_HELP_EXAMPLES` | `0`, `false`, `off` or `no` drops the Examples section from every help page. | — | [`--help`](https://relatedb.ai/docs/reference/cli/flags/#help) |
| `RELATE_AUTH` | Basic-auth credential (`user:password` or `none`) for every served network surface; `--auth` overrides it. | a generated token | `relate serve` |
| `RELATE_PATTERN_ENGINE` | Diagnostic pattern-engine switch: `auto`, `nfa` or `walk`. Not a supported tuning knob. | `auto` | `relate query engine` |
| `RELATE_BULK_BATCH_THRESHOLD` | Estimated touched-entity count at which an eligible global bulk write switches to batched commits. | `10000` | `relate query engine` |
| `RELATE_BULK_BATCH_BUDGET` | Estimated touched-entity budget per batch commit of an eligible global bulk write. | `25000` | `relate query engine` |
| `GITHUB_TOKEN` | Optional bearer token for release-asset downloads; required while the repository is internal. | — | `relate upgrade`, `relate extension install` |
| `RELATE_RELEASES_JSON_URL` | Override the release-metadata URL (dev and test). | `https://relatedb.ai/releases.json` | `relate upgrade` |
| `RELATE_EXTENSIONS_JSON_URL` | Override the extension channel-index URL (dev and test). | `https://relatedb.ai/extensions.json` | `relate extension install`, `relate extension list --available` |
| `RELATE_RELEASE_DOWNLOAD_URL` | Override the base of the direct release-download route (dev and test). | `https://github.com/relatedb/relate/releases/download` | `relate upgrade`, `relate extension install` |
| `RELATE_GITHUB_API_URL` | Override the base of the GitHub API asset route (dev and test). | `https://api.github.com` | `relate upgrade`, `relate extension install` |
| `NEO4J_URI` | Source Query API URI when `--from` is omitted. | — | `relate pull` |
| `NEO4J_USERNAME` | Source username when `--from` is omitted (`NEO4J_USER` also accepted); for `relate push`, when `--to` is a Query API URI rather than an env file. | — | `relate pull`, `relate push` |
| `NEO4J_PASSWORD` | Source password when `--from` is omitted; for `relate push`, when `--to` is a Query API URI rather than an env file. | — | `relate pull`, `relate push` |
| `NEO4J_DATABASE` | Source database name when `--from` is omitted; for `relate push`, when `--to` is a Query API URI rather than an env file. | `neo4j` | `relate pull`, `relate push` |
| `RELATE_MIXPANEL_ENDPOINT` | Overrides the Mixpanel /track URL (development and testing); https:// for any host, http:// only for a loopback host; a rejected value turns usage metrics off for the run, with one stderr warning. | `https://api.mixpanel.com/track` | usage metrics |
| `RELATE_MIXPANEL_TOKEN` | Overrides the compiled-in Mixpanel project token (development and testing). | — | usage metrics |
| `RELATE_TX_IDLE_TIMEOUT_SECS` | Default HTTP managed-transaction idle timeout. | `60` | [`relate serve --tx-idle-timeout-secs`](https://relatedb.ai/docs/reference/cli/flags/#serve-tx-idle-timeout-secs) |
| `RELATE_MAX_OPEN_TRANSACTIONS` | Default cap on open HTTP managed transactions. | `128` | [`relate serve --max-open-transactions`](https://relatedb.ai/docs/reference/cli/flags/#serve-max-open-transactions) |
| `RELATE_MAX_CONNECTIONS` | Default process-wide session cap. | `128` | [`relate serve --max-connections`](https://relatedb.ai/docs/reference/cli/flags/#serve-max-connections) |
| `RELATE_WS_MAX_CONNECTIONS` | Default cap on Bolt-over-WebSocket sessions. | unlimited | [`relate serve --ws-max-connections`](https://relatedb.ai/docs/reference/cli/flags/#serve-ws-max-connections) |
| `RELATE_HEADER_DEADLINE_SECS` | Default HTTP/MCP header deadline. | `10` | [`relate serve --header-deadline-secs`](https://relatedb.ai/docs/reference/cli/flags/#serve-header-deadline-secs) |
| `RELATE_BODY_DEADLINE_SECS` | Default HTTP/MCP body deadline. | `60` | [`relate serve --body-deadline-secs`](https://relatedb.ai/docs/reference/cli/flags/#serve-body-deadline-secs) |
| `RELATE_IDENTITY` | Default Bolt HELLO server agent string. | `Relate/<version>` | [`relate serve --bolt-identity`](https://relatedb.ai/docs/reference/cli/flags/#serve-bolt-identity) |
| `RELATE_MARKDOWN_BODY_PROPERTIES` | The markdown codec's body properties for an open without the flag; a value that does not parse fails the open (exit 1). | `body` | [`--markdown-body-properties`](https://relatedb.ai/docs/reference/cli/flags/#markdown-body-properties) |
| `RELATE_SHARD_TARGET_BYTES` | The target Parquet shard size at a checkpoint, 1 to 1073741824. Read at each checkpoint that writes Parquet shards, after the run's statements have committed; an invalid or empty value fails that checkpoint (exit 1). A `:memory:` run, a `--read-only` open and a `json`-codec store never read it. | `268435456` | `relate query engine` |
| `XDG_CONFIG_HOME` | When set, non-empty and absolute, the config directory is `$XDG_CONFIG_HOME/relate/`. | — | usage metrics, `relate extension`, `relate skill` |
| `HOME` | The fallback config directory `~/.config/relate/`, and the base of the agent directories `relate skill install` writes to. | — | usage metrics, `relate extension`, `relate skill` |
| `COLUMNS` | The table wrap width when stdout is not a terminal; a value under 20 is ignored. | — | [`--width`](https://relatedb.ai/docs/reference/cli/flags/#width) |
| `CI` | A value other than empty, `0` or `false` reports the usage-metrics invoker as `ci`. | — | usage metrics |
| `RELATE_MEMORY_LIMIT` | Retired: setting it fails the open (exit 1) with `Failed to open Relate: semantic error: RELATE_MEMORY_LIMIT is set but ignored; set RELATE_LOGICAL_GRAPH_SIZE_LIMIT`. | — | `relate query engine` |
| `RELATE_TOKEN_ADMISSION` | Retired: setting it fails the open (exit 1) with `Failed to open Relate: semantic error: RELATE_TOKEN_ADMISSION is set but ignored; set RELATE_CONCURRENT_LOGICAL_WORKSPACE_LIMIT`. | — | `relate query engine` |
| `RELATE_CONCURRENT_PEAK_TOKEN_LIMIT` | Retired: setting it fails the open (exit 1) with `Failed to open Relate: semantic error: RELATE_CONCURRENT_PEAK_TOKEN_LIMIT is set but ignored; set RELATE_CONCURRENT_LOGICAL_WORKSPACE_LIMIT`. | — | `relate query engine` |

## See also

- [relate CLI](https://relatedb.ai/docs/reference/cli/): the commands and the query-run flag families
- [Exit codes and errors](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/): what each exit code means and the error object
- [Agent mode](https://relatedb.ai/docs/reference/cli/agent-mode/): detection, the row cap, and the envelope
- [Script the CLI](https://relatedb.ai/docs/guides/cli/scripting/): the flags in shell scripts, with exit codes and `--timeout`

## Terms used on this page

- **store**: A relate database: a directory, a single `.rl` file, or `:memory:`, opened with `--database`.
- **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.
- **codec**: The on-disk encoding of a store's snapshot: Parquet (the default), JSON or markdown, fixed when the store is created.
- **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.
- **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.