Environment variables

The relate CLI reads environment variables for five jobs: default values for its flags, detecting an agent harnessagent harness The program that runs a model and executes the commands it chooses, such as Claude Code, Codex or Cursor; relate detects one from its environment variables. Read more in the glossary, turning off usage metrics, turning on preview features, and finding its config directory. A flag always beats its variable, and a variable beats the built-in default. A variable set to an empty or blank value counts as unset, with two exceptions the synopsis table names. An invalid value stops the run before any statement executes, with exit code 2 or 1 depending on the variable; a few variables fall back to their default instead, and the tables on this page say which. RELATE_SHARD_TARGET_BYTES is the exception to that order: it is read at the checkpoint, after the run's statements have run and committed.

Synopsis

<NAME>=<value> relate [OPTIONS] [--database PATH] [QUERY]
<NAME>=<value> relate <COMMAND> [ARGS]

Precedence

RELATE_MAX_ROWS=1 caps every statement at one row. --max-rows 0 on the same command beats it and prints every row:

RELATE_MAX_ROWS=1 relate --mode jsonl "UNWIND [1, 2, 3] AS x RETURN x"
RELATE_MAX_ROWS=1 relate --mode jsonl --max-rows 0 "UNWIND [1, 2, 3] AS x RETURN x"

warning: result truncated to 1 rows (the statement returned 3); pass --max-rows 0 for all rows
{"x":1}
{"rowCap":{"kept":1,"total":3}}
{"planCache":"miss","timings":{"elapsed_ms":0.362833,"execute_ms":0.212625,"lex_parse_ms":0.021375,"lower_ms":0.030208,"parse_ms":0.094958,"plan_ms":0.042249999999999996,"result_generation_ms":0.000209,"rewrite_ms":0.007083}}
{"x":1}
{"x":2}
{"x":3}
{"planCache":"miss","timings":{"elapsed_ms":0.30329100000000003,"execute_ms":0.182666,"lex_parse_ms":0.016875,"lower_ms":0.026375,"parse_ms":0.078042,"plan_ms":0.032,"result_generation_ms":0.00041600000000000003,"rewrite_ms":0.005542}}

The same holds for every pair: --no-safe beats RELATE_SAFE_MODE=1, --durability-mode beats RELATE_DURABILITY_MODE, and --load-csv-dir beats RELATE_LOAD_CSV_DIR.

Every variable

Each row is at a stable anchor, https://relatedb.ai/docs/reference/cli/environment-variables#<id> (#env-relate-max-rows). A flag in the last column links its row on the flags page.

Durability and storage

These set the defaults for a persistent store's write path and snapshot. :memory: has no WAL or snapshot, so only RELATE_SNAPSHOT_FORMAT is checked there.

On an existing store, RELATE_SNAPSHOT_FORMAT must name the store's recorded codeccodec The on-disk encoding of a store's snapshot: Parquet (the default), JSON or markdown, fixed when the store is created. Read more in the glossary, or the open fails with exit 1: Failed to open Relate: storage error: snapshot codec mismatch: directory is <codec>, requested <codec>. The message lists rkyv, which the release binary is not built with: RELATE_SNAPSHOT_FORMAT=rkyv fails the open with exit 1 and Failed to open Relate: storage error: rkyv snapshot codec is not compiled into this build (enable the "rkyv-codec" feature). relate serve takes no --checkpoint-interval-secs flag, so RELATE_CHECKPOINT_INTERVAL_SECS is how a server's checkpoint timer is set. Only a checkpoint that writes Parquet shards reads RELATE_SHARD_TARGET_BYTES, so a run on :memory:, a --read-only open, and a json codec store never check it. The durability modes guide covers each mode's loss window.

Limits

These bound one run's memory, traversal depth, printed rows, and local file access. Each is a safety limit, not a store property: a different run can open the same store with different limits.

Size a store and its memory works through the memory limits.

Retired names

Three retired names are refused rather than ignored, because an unset limit means unlimited and a store would otherwise open uncapped. Setting one fails the open with exit 1:

Any variable whose name starts with CYPHERLITE_, the product's former prefix, is refused too when its value is not empty or blank, even a name relate never read. The check runs before anything else, so every command fails with exit 1, --help and --version included, and the message names the matching RELATE_ name:

CYPHERLITE_MAX_ROWS=1 relate "RETURN 1 AS x"
echo "exit=$?"

Error: semantic error: CYPHERLITE_MAX_ROWS is set but ignored; set RELATE_MAX_ROWS
exit=1

Safety and agent mode

RELATE_SAFE_MODE and RELATE_AGENT_MODE take 1 or 0, with surrounding whitespace ignored. Any other value exits 2 before a statement runs.

With RELATE_AGENT_MODE unset, agent mode turns on when stdout is not a terminal and one of these variables is set to a non-empty value: AI_AGENT, AGENT, CLAUDECODE, CLAUDE_CODE, COPILOT_AGENT, COPILOT_CLI, COPILOT_AGENT_SESSION_ID, REPL_ID, GEMINI_CLI, CODEX_SANDBOX, CODEX_THREAD_ID, OPENCODE, AUGMENT_AGENT, GOOSE_PROVIDER or CURSOR_AGENT. It also turns on when EDITOR contains devin, TERM_PROGRAM contains kiro, or PATH contains .pi/agent, each matched case-insensitively. Detection prints nothing. Agent mode, whether set or detected, turns on neither --read-only nor safe mode. The agent mode page has the detection ladder and the two defaults agent mode changes.

Preview features

RELATE_PREVIEW turns on preview featurespreview feature A Cypher feature from a not-yet-settled proposal that relate ships switched off; it runs only when RELATE_PREVIEW names it when the store opens. Read more in the glossary: a comma-separated list of feature names, read once when the store opens. Unset or empty turns on nothing. With coll-zip named, the coll.zip function exists:

RELATE_PREVIEW=coll-zip relate --mode envelope "RETURN coll.zip([1, 2], ['a', 'b']) AS pairs"

{"columnTypes":["LIST"],"columns":["pairs"],"notifications":[],"planCache":"miss","rows":[{"pairs":[[1,"a"],[2,"b"]]}],"timings":{"elapsed_ms":0.500958,"execute_ms":0.357792,"lex_parse_ms":0.024290999999999997,"lower_ms":0.034375,"parse_ms":0.092541,"plan_ms":0.042917000000000004,"result_generation_ms":0.000959,"rewrite_ms":0.007333},"truncated":false}

An unknown name fails the open with exit 1, and the message lists every name the binary knows:

RELATE_PREVIEW=bogus relate --mode jsonl "RETURN 1 AS ok"
echo "exit=$?"

Failed to open Relate: semantic error: SemanticError: invalid RELATE_PREVIEW value: unknown preview feature 'bogus' (known features: hybrid-search, local-callables, graph-type-opt-props, graph-type-default-values, graph-type-implied-labels, ontology, obfuscated-literals, mixed-label-syntax, float16-coordinate-types, chronological-comparisons, complex-search-patterns, coll-zip, coll-has, gql-stddev-aliases)
{"error":{"code":"fatal_error","exit_code":1,"kind":"semantic","message":"semantic error: SemanticError: invalid RELATE_PREVIEW value: unknown preview feature 'bogus' (known features: hybrid-search, local-callables, graph-type-opt-props, graph-type-default-values, graph-type-implied-labels, ontology, obfuscated-literals, mixed-label-syntax, float16-coordinate-types, chronological-comparisons, complex-search-patterns, coll-zip, coll-has, gql-stddev-aliases)","retryable":false}}
exit=1

On relate serve, the variable is the server process's setting: a feature it turns on is on for every connected client.

Usage metrics

The CLI's anonymous usage metrics, its telemetrytelemetry The anonymous usage metrics the relate CLI sends: on by default, off with DO_NOT_TRACK=1, RELATE_TELEMETRY=0 or relate telemetry off. Read more in the glossary, are on by default. The first layer that decides wins:

A RELATE_TELEMETRY value outside those six falls through to the next layer. relate telemetry status names the layer that decided:

DO_NOT_TRACK=1 RELATE_TELEMETRY=1 relate telemetry status

disabled (DO_NOT_TRACK)

Two more variables exist for development and testing: RELATE_MIXPANEL_ENDPOINT replaces the /track URL (an https:// URL, or http:// for a loopback host only; a rejected value turns metrics off for the run with one warning on stderr), and RELATE_MIXPANEL_TOKEN replaces the project token. Since relate 0.1.0 an exit writes its events to the spool instead of waiting for a delivery, so RELATE_TELEMETRY_FLUSH_MS is gone. Each event's invoker property is agent when CLAUDECODE, CURSOR_AGENT, GEMINI_CLI or OPENCODE is set, else ci when CI is set to a value other than empty, 0 or false, else human. The privacy and telemetry page lists every event and property.

Paths and terminal

The config directory follows XDG_CONFIG_HOME. In this run, the config file in ./cfg/relate/ turns metrics off, and DO_NOT_TRACK is removed from the command's environment so the file is the layer that decides:

mkdir -p cfg/relate
printf '{"telemetry":false}\n' > cfg/relate/config.json
env -u DO_NOT_TRACK XDG_CONFIG_HOME="$PWD/cfg" relate telemetry status

disabled (config file)

COLUMNS wraps a piped table. The widest column shrinks, and its cell continues on the next line:

COLUMNS=20 relate --mode table "UNWIND ['engineer', 'maintainer'] AS role RETURN role, size(role) AS len"

+------------+-----+
| role       | len |
+------------+-----+
| "engineer" | 8   |
| "maintaine | 10  |
| r"         |     |
+------------+-----+

Command variables

Each of these is read by one or two commands, and its row in every variable names them (NEO4J_USER appears inside the NEO4J_USERNAME row):

The four URL variables are for development and testing. Each replaces one default URL, and an empty value means the default.

Engine diagnostics

Three variables tune the query engine and are read once at open. They exist for measurement, not for routine tuning.

See also

• CLI flags: the flag each variable sets a default for
• Agent mode: detection and the defaults it changes
• Privacy and telemetry: what the usage metrics hold and every way to turn them off
• Errors: each invalid-value message with its cause and remedy
• Script the CLI: pinning the output mode and limits in a script