--- title: relate CLI description: "relate, the embedded Cypher graph database (relatedb.ai): The relate command line on one page, with its invocation forms, every command and its usage line, the query-run flags by family, and where each detail lives." type: reference surfaces: - cli status: stable verified: 0.1.2 verified_by: - cli canonical_url: https://relatedb.ai/docs/reference/cli/ prerequisites: [] related: - reference/cli/flags - reference/cli/exit-codes-and-errors - reference/cli/agent-mode - guides/cli/scripting last_updated: 2026-11-09 --- # relate CLI The relate command line on one page, with its invocation forms, every command and its usage line, the query-run flags by family, and where each detail lives. > Verified against relate 0.1.2. If your `relate --version` is newer, read https://relatedb.ai/docs/reference/changelog/#since-0.1.2 `relate` is one binary with two kinds of run. A query run executes Cypher statements against one [store](https://relatedb.ai/docs/reference/glossary/#store) and prints their results; a command (`relate `) does one job, such as copying a store or serving it, and exits. This page lists the invocation forms, every command the binary's `relate --help` prints, the query-run flags by family and the shell dot commands, with a link to the page that holds each detail. ## Synopsis ```text relate [OPTIONS] [--database PATH] [QUERY] relate [ARGS] relate query [STATEMENT] [--database PATH] ``` | Form | What runs | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `relate [OPTIONS] [QUERY]` | The path-first query run. `QUERY` (or `-c`, `--command`) is one statement or a `;`-separated list. With no `QUERY`, a terminal opens the interactive shell; piped or redirected stdin prints the top-level help and exits 0. | | `relate query [STATEMENT]` | The same query session as a command word. With no `STATEMENT`, it reads a script from stdin, or opens the interactive shell on a terminal. | | `relate [ARGS]` | A command: it does its job and exits. Each command takes its own flags, listed on the [flags page](https://relatedb.ai/docs/reference/cli/flags/#command-flags). | `--database` (short form `-d`) names the store: a directory, a single-file `.rl` store, or `:memory:`, the default. The word `query` as the first positional is the command; a directory named `query` is `--database ./query`. ## Commands The twelve commands of the binary these pages are verified against, in the order `relate --help` prints them. The second column is the binary's own one-line summary. | Command | Summary from `relate --help` | Its flags | Guide | | ------------------------------------------------------------------------ | -------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | | [`query`](https://relatedb.ai/docs/reference/cli/query/) | Run a statement session (oneshot, stdin, or shell) | [Query-run flags](https://relatedb.ai/docs/reference/cli/flags/#query-run-flags) | [Script the CLI](https://relatedb.ai/docs/guides/cli/scripting/) | | [`clone`](https://relatedb.ai/docs/reference/cli/clone/) | Copy a database into a new store and exit | [`relate clone`](https://relatedb.ai/docs/reference/cli/flags/#relate-clone) | [Back up and restore](https://relatedb.ai/docs/guides/storage/backup-and-restore/) | | [`info`](https://relatedb.ai/docs/reference/cli/info/) | Print store metadata for a database without opening it | [`relate info`](https://relatedb.ai/docs/reference/cli/flags/#relate-info) | [Storage formats](https://relatedb.ai/docs/reference/storage/formats/) | | [`pull`](https://relatedb.ai/docs/reference/cli/pull/) | Copy a Neo4j/Aura subgraph into a database | [`relate pull`](https://relatedb.ai/docs/reference/cli/flags/#relate-pull) | [Pull from Neo4j](https://relatedb.ai/docs/guides/neo4j/pull-from-neo4j/) | | [`push`](https://relatedb.ai/docs/reference/cli/push/) | Copy a database subgraph into Neo4j/Aura | [`relate push`](https://relatedb.ai/docs/reference/cli/flags/#relate-push) | [Push to Neo4j](https://relatedb.ai/docs/guides/neo4j/push-to-neo4j/) | | [`skill`](https://relatedb.ai/docs/reference/cli/skill/) | Install, inspect, or remove the embedded agent skill bundle | [`relate skill`](https://relatedb.ai/docs/reference/cli/flags/#relate-skill) | [Install the agent skill](https://relatedb.ai/docs/guides/agents/install-the-skill/) | | [`upgrade`](https://relatedb.ai/docs/reference/cli/upgrade/) | Update the relate binary (alias: update) | [`relate upgrade`](https://relatedb.ai/docs/reference/cli/flags/#relate-upgrade) | — | | [`telemetry`](https://relatedb.ai/docs/reference/cli/telemetry/) | Manage anonymous usage metrics (on, off, status) | none | [Privacy and telemetry](https://relatedb.ai/docs/reference/privacy-and-telemetry/) | | [`run`](https://relatedb.ai/docs/reference/cli/run/) | Run an installed extension action into a store the host owns | [`relate run`](https://relatedb.ai/docs/reference/cli/flags/#relate-run) | [Install and run an extension](https://relatedb.ai/docs/guides/extensions/install-and-run/) | | [`serve`](https://relatedb.ai/docs/reference/cli/serve/) | Host the HTTP Query API and MCP surfaces on a database | [`relate serve`](https://relatedb.ai/docs/reference/cli/flags/#relate-serve) | [Connect over MCP](https://relatedb.ai/docs/guides/agents/connect-over-mcp/) | | [`agent-context`](https://relatedb.ai/docs/reference/cli/agent-context/) | Print the compact agent briefing (commands, flags, exit codes) | none | [Agent mode](https://relatedb.ai/docs/reference/cli/agent-mode/#the-agent-context-briefing) | | [`extension`](https://relatedb.ai/docs/reference/cli/extension/) | Scaffold, install, check, list, or remove command extensions | [`relate extension`](https://relatedb.ai/docs/reference/cli/flags/#relate-extension) | [Write an extension](https://relatedb.ai/docs/guides/extensions/write-an-extension/) | Each command's name links to its reference page. A dash in the Guide column means no guide covers the command; `relate --help` and `relate agent-context ` describe it on any machine. `relate --help` lists only the commands compiled into the binary. A command left out of a build exits 2 with `Error: the '' command is not included in this build of relate`. Each command's usage line, as its `--help` prints it: ```text relate query [STATEMENT] [--database PATH] relate clone [--wal-dir DIR] [--to-snapshot-format F] [--markdown-body-properties LIST] SOURCE DEST relate info --database PATH [--json] relate pull [--from FILE] --query Q [--param N=V] [--allow-plaintext] --database PATH relate push --to CREDS --database PATH [--query Q | --labels L1,L2 | --types T1,T2] [--batch-size N] [--nodes-update POLICY] [--rels-update POLICY] [--updated-at NAME[,NAME]] [--rel-mode MODE] [--merge-key LABEL:PROP[,PROP]] [--rel-key TYPE:PROP[,PROP]] [--unkeyed-labels ACTION] [--dry-run] [--json] [--allow-plaintext] relate skill install|remove|list|check [--agent NAME] [--force] relate upgrade [--yes] [--check] relate update [--yes] [--check] (alias of upgrade) relate telemetry on|off|status relate run [flags] relate serve --database PATH [--host HOST] [--http PORT] [--origin ORIGIN] [--mcp PORT|stdio] [--bolt PORT [--bolt-identity STRING] [--ws-allow-origin ORIGIN] [--ws-max-connections N]] [--read-only[=FRESHNESS]] [--load SOURCE] [--auth USER:PASSWORD] [--concurrent-logical-workspace-limit SIZE] [--max-traversal-depth N] [--expression-memory-limit SIZE] [--safe | --no-safe] [--logical-graph-size-limit SIZE] [--durability-mode MODE] relate agent-context [COMMAND] relate extension init [--lang sh|py|ts|rust] relate extension install [--github REPO@TAG|@SHA] [--url URL] [--from DIR] [--version V] [--force] [--re-approve | --approve SHA] relate extension list [--available | --trust] relate extension remove [--forget-pin] relate extension check ``` ## Query-run flags by family The query-run flags apply to the path-first form and to `relate query`, before or after the statement. The [flags page](https://relatedb.ai/docs/reference/cli/flags/) gives each one's argument, default, and environment variable. | Family | Flags | Detail | | ---------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | Store | `--database`, `--load`, `--read-only`, `--namespace`, `--wal-dir`, `--snapshot-format`, `--markdown-body-properties` | [Store and storage](https://relatedb.ai/docs/reference/cli/flags/#store-and-storage) | | Durability | `--durability-mode`, `--checkpoint-interval-secs` | [Store and storage](https://relatedb.ai/docs/reference/cli/flags/#store-and-storage) | | Statement input | `QUERY`, `--command`, `--param`, `--fetch-params` | [How flags are parsed](https://relatedb.ai/docs/reference/cli/flags/#how-flags-are-parsed) | | Output | `--mode`, `--format`, `--json`, `--csv`, `--jsonl`, `--markdown`, `--toon`, `--pretty`, `--noheader`, `--width` | [Output](https://relatedb.ai/docs/reference/cli/flags/#output) | | Safety | `--read-only`, `--safe`, `--no-safe`, `--load-csv-dir`, `--max-traversal-depth` | [Safety](https://relatedb.ai/docs/reference/cli/flags/#safety) | | Memory limits | `--logical-graph-size-limit`, `--expression-memory-limit`, `--concurrent-logical-workspace-limit` | [Memory limits](https://relatedb.ai/docs/reference/cli/flags/#memory-limits) | | Timeouts | `--timeout` | [Timeouts](https://relatedb.ai/docs/reference/cli/flags/#timeouts) | | Agent ergonomics | `--agent-mode`, `--no-agent-mode`, `--max-rows` | [Agent mode](https://relatedb.ai/docs/reference/cli/agent-mode/) | | Help | `--help`, `--version`, `--` | [Query-run flags](https://relatedb.ai/docs/reference/cli/flags/#query-run-flags) | ## Shell dot commands A line that starts with a dot is a shell command, not Cypher: `.begin`, `.commit`, `.rollback`, `.checkpoint`, `.info`, `.timer`, `.help` and `.quit`. They work in the interactive shell and in a script piped to `relate query`, one per line; `.begin` opens an explicit [transaction](https://relatedb.ai/docs/reference/glossary/#transaction) and `.checkpoint` writes a [checkpoint](https://relatedb.ai/docs/reference/glossary/#checkpoint). [Dot commands](https://relatedb.ai/docs/reference/cli/dot-commands/) gives each one's effect, output, failure and exit code. ## Detail pages | Page | Holds | | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | [Flags](https://relatedb.ai/docs/reference/cli/flags/) | Every flag of the query run and of each command, with its argument, default, scope and environment variable; every environment variable the CLI reads | | [Exit codes and errors](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/) | One anchor per [exit code](https://relatedb.ai/docs/reference/glossary/#exit-code), the error object a failed query run prints, and how the two relate | | [Agent mode](https://relatedb.ai/docs/reference/cli/agent-mode/) | How the CLI detects an agent harness, the defaults it changes, the row cap, the envelope and `relate agent-context` | | [Errors](https://relatedb.ai/docs/reference/errors/) | Every error message, with its cause, remedy, retry advice, and exit code | | [Environment variables](https://relatedb.ai/docs/reference/cli/environment-variables/) | Every environment variable the CLI reads, what it sets, and what an invalid value does | | [Output modes](https://relatedb.ai/docs/reference/cli/output-modes/) | Each `--mode` value, its shape on stdout, and how values print in it | | [Dot commands](https://relatedb.ai/docs/reference/cli/dot-commands/) | The shell dot commands, their output and their errors | On a machine without network access, `relate --help`, `relate --help` and `relate agent-context [COMMAND]` print the same facts for the installed binary. `RELATE_HELP_EXAMPLES=0` drops the `Examples:` section from every help page. ## Examples A one-statement query run on the default in-memory store, printed as an [envelope](https://relatedb.ai/docs/reference/glossary/#envelope): ```bash verify relate --mode envelope "RETURN 1 AS ok" ``` ```text {"columnTypes":["INTEGER"],"columns":["ok"],"notifications":[],"planCache":"miss","rows":[{"ok":1}],"timings":{"elapsed_ms":0.351167,"execute_ms":0.203625,"lex_parse_ms":0.023166000000000003,"lower_ms":0.0295,"parse_ms":0.09595899999999999,"plan_ms":0.040874999999999995,"result_generation_ms":0.00041600000000000003,"rewrite_ms":0.006667},"truncated":false} ``` `relate query` with no statement reads a script from piped stdin, one envelope per statement: ```bash verify printf 'RETURN 1 AS a;\nRETURN 2 AS b;\n' | relate query --mode envelope ``` ```text {"columnTypes":["INTEGER"],"columns":["a"],"notifications":[],"planCache":"miss","rows":[{"a":1}],"timings":{"elapsed_ms":0.331042,"execute_ms":0.19675,"lex_parse_ms":0.020125,"lower_ms":0.027959,"parse_ms":0.087084,"plan_ms":0.038167,"result_generation_ms":0.00033299999999999996,"rewrite_ms":0.006583},"truncated":false} {"columnTypes":["INTEGER"],"columns":["b"],"notifications":[],"planCache":"miss","rows":[{"b":2}],"timings":{"elapsed_ms":0.02425,"execute_ms":0.004041,"lex_parse_ms":0.003792,"lower_ms":0.003416,"parse_ms":0.01325,"plan_ms":0.0051660000000000005,"result_generation_ms":0.000083,"rewrite_ms":0.000417},"truncated":false} ``` The version line names the release: ```bash verify relate --version ``` ```text Relate v0.1.2 License: Apache 2.0 (binary) ``` ## See also - [Script the CLI](https://relatedb.ai/docs/guides/cli/scripting/): stdin scripts, exit codes and `--timeout` in a shell script - [Drive relate from an agent](https://relatedb.ai/docs/guides/agents/drive-relate-from-an-agent/): the envelope, the error object and the row cap from an agent's side - [Install relate](https://relatedb.ai/docs/get-started/install/): getting the binary ## Terms used on this page - **store**: A relate database: a directory, a single `.rl` file, or `:memory:`, opened with `--database`. - **transaction**: A unit of work that commits as a whole or not at all; each statement is its own transaction unless an explicit `begin` … `commit` groups several. - **checkpoint**: The step that writes a fresh snapshot of committed state and recycles old WAL segments: every 300 seconds by default, on clean exit, and on `.checkpoint`. - **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. - **envelope**: One compact JSON object per result set, printed by `--mode envelope`, that keeps the column list even when there are no rows.