relate CLI

relate is one binary with two kinds of run. A query run executes Cypher statements against one storestore A relate database: a directory, a single .rl file, or :memory:, opened with --database. Read more in the glossary and prints their results; a command (relate <command>) 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

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

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

Each command's name links to its reference page. A dash in the Guide column means no guide covers the command; relate <command> --help and relate agent-context <command> 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>' command is not included in this build of relate.

Each command's usage line, as its --help prints it:

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 <name> [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 <name> [--lang sh|py|ts|rust]
relate extension install <name> [--github REPO@TAG|@SHA] [--url URL] [--from DIR] [--version V] [--force] [--re-approve | --approve SHA]
relate extension list [--available | --trust]
relate extension remove <name> [--forget-pin]
relate extension check <dir>

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 gives each one's argument, default, and environment variable.

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 transactiontransaction 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. Read more in the glossary and .checkpoint writes a checkpointcheckpoint 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. Read more in the glossary. Dot commands gives each one's effect, output, failure and exit code.

Detail pages

On a machine without network access, relate --help, relate <command> --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 envelopeenvelope One compact JSON object per result set, printed by --mode envelope, that keeps the column list even when there are no rows. Read more in the glossary:

relate --mode envelope "RETURN 1 AS ok"

{"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:

printf 'RETURN 1 AS a;\nRETURN 2 AS b;\n' | relate query --mode envelope

{"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:

relate --version

Relate v0.1.2
License: Apache 2.0 (binary)

See also

• Script the CLI: stdin scripts, exit codes and --timeout in a shell script
• Drive relate from an agent: the envelope, the error object and the row cap from an agent's side
• Install relate: getting the binary