CLI reference

This page is a map of the omnigraph command surface. The installed binary is the exact reference:

omnigraph --help
omnigraph <command> --help
omnigraph <command> <subcommand> --help

Addressing a graph

Most graph commands accept one of these scopes:

A bare local path is accepted where a graph URI is expected. --server and --store are mutually exclusive. A store already identifies one graph, so it cannot be combined with --graph.

Common global flags:

A served write refuses --as ("--as is not allowed on a served write"): the server resolves the actor from the bearer token. Drop it, or use --store <uri>.

Commands

The CLI guide gives end-to-end examples. Maintenance safety is covered in Maintenance. rebuild-full-text-indexes accepts --branch (default main), --json, and --as for actor attribution. Direct maintenance does not load server policy; see the rebuild procedure.

Query inputs and output

For ad-hoc source, pass --query <FILE> or -e/--query-string <GQ>. When the source contains multiple declarations, the positional name selects one. For a stored server query, omit the source and pass its registry name. Parameters come inline, --params '{"name":"Ada"}', or from a file, --params-file params.json.

The source may instead be one branch statement, mutate -e 'branch create b0' or query -e 'branch list' (control writes through mutate, the listing through query), which takes no --branch, --snapshot, --if-commit, name, or params; see Work with branches.

Read output supports table, json, jsonl, csv, and kv. --json is the stable machine-readable form for commands that do not use --format. Result cells come from the JSON spelling in JSON result spelling; table, csv, and kv print strings unquoted. --format json prints the envelope pretty and the rows array compact, verbatim.

Machine-readable read and write positions

When the read snapshot has an effective graph head, omnigraph query --json returns its graph_commit_id in the complete read envelope. The id and rows come from the same pinned snapshot; use that id when a later mutation must be conditional on the state that was read.

Successful mutate --json, load --json, and compatibility ingest --json responses include commit, the exact commit published by that attempt. It contains graph_commit_id, optional graph_branch, graph_manifest_version, optional parent and merged-parent ids, optional actor_id, and created_at in Unix microseconds. A successful mutation that changes no entities returns "commit": null.

Conditional mutations

omnigraph query find_person --query queries.gq --store graph.omni --json
omnigraph mutate update_person --query queries.gq --store graph.omni \
  --if-commit <graph_commit_id> --json

--if-commit runs the mutation only while the target branch is still at that commit. Any intervening commit on the branch invalidates the condition, even when it changed unrelated data. A mismatch has no effect and exits with code 4; JSON output includes precondition_failure with expected and optional actual commit ids. Re-read and decide again instead of retrying blindly.

Storage upgrade

omnigraph upgrade ./graph.omni --check --to-format 8 --json
omnigraph upgrade ./graph.omni --to-format 8 --json

--store is an alternative to the positional storage URI. Target format defaults to 8: qualified v6 inputs run v6 → v7 → v8, and v7 inputs run v7 → v8. Explicit target 7 remains available, but the current binary refuses normal open of v7. --check performs read-only preflight and reports output-dependent checks in work.deferred_checks; execution validates those before the affected handler has effects. Execution requires stopped writers, stopped maintenance and a verified whole-root backup. A failed check, refusal or required recovery exits 1. JSON reports the route, formats, findings, durable boundary, recovery action and work categories. Server and cluster addressing are refused. See storage migration.

Load modes

load --mode is required:

--branch <NAME> selects an existing branch. Add --from <BASE> to create a missing branch from an explicit base. Overwrite is destructive and may require --yes for non-local storage.

Change-feed commands, cursor checkpointing, and baseline recovery are described in Changes and Change Feeds.

Blob commands

omnigraph blob get  <node|edge> <TYPE> <ID> <PROPERTY> [scope] [options]
omnigraph blob stat <node|edge> <TYPE> <ID> <PROPERTY> [scope] [options]

get accepts --branch or --snapshot, --offset, --length, and --out <PATH>. stat accepts --branch or --snapshot and --json. See Blob values.

Operator configuration

The default path is ~/.omnigraph/config.yaml. Set OMNIGRAPH_HOME to use a different directory.

operator:
  actor: act-alice

defaults:
  output: table
  server: prod
  default_graph: knowledge

servers:
  prod:
    url: https://graph.example.com

clusters:
  company:
    root: s3://company-data/omnigraph

profiles:
  prod-knowledge:
    server: prod
    default_graph: knowledge
  company-admin:
    cluster: company
    default_graph: knowledge
  local-dev:
    store: file:///tmp/dev.omni

aliases:
  experts:
    server: prod
    graph: knowledge
    query: find_experts
    args: [topic]
    params:
      limit: 20
    format: table

Each profile binds exactly one of server, cluster, or store. Select it with --profile or OMNIGRAPH_PROFILE. Explicit flags override values filled by a profile.

Bearer tokens never belong in config.yaml. Store a token with omnigraph login <server> or provide OMNIGRAPH_BEARER_TOKEN for the current invocation.

Managed cluster commands

omnigraph login --api ORIGIN prints a verification URL and user code to stderr. Complete the browser login while the CLI polls. The resulting opaque service session is stored in the OS keychain under the canonical API origin: macOS Keychain, Windows Credential Manager, or encrypted Secret Service on Linux and BSD. There is no plaintext fallback. Sessions expire within 15 minutes, and the CLI stores no refresh token; run login again after expiry. An unavailable keychain refuses the operation. Login JSON includes identity and expiry, never a token or device secret.

omnigraph logout --api ORIGIN revokes that session and removes only that origin's local entry. If revocation fails, the local entry is still removed and the error reports revocation_confirmed: false; the remote session remains subject to its expiry. Accepted runs continue after logout. The existing login SERVER --token and logout SERVER commands retain their named-server credential behavior.

omnigraph use CLUSTER_ID --api ORIGIN [--config DIR] [--json] verifies access to the cluster, then atomically writes DIR/.omnigraph/context:

version: 1
cluster: CLUSTER_ID
api: https://control.example

The context contains no secret. Cluster commands read it only from the selected --config directory, which defaults to .. Parent directories are not searched. Unknown fields, versions, malformed files, symbolic links, and files over 16 KiB are refused. API addresses must be origins without credentials, path, query, or fragment. HTTPS is required except for exact localhost, 127.0.0.1, and [::1] API hosts used for local integration.

See managed lifecycle for creation, upload, deletion, undo and operation status.

All accept --config DIR and --json. Managed plan and apply accept --idempotency-key KEY, --no-wait, and --timeout SECONDS. Without a supplied key, plan or apply generates one and prints it to stderr before submission. Reuse that key with the same body to recover from an uncertain response; changing the body under a key is refused by the API. Retry cancellation or abandonment using the same run id. Plan and apply do not upload local files or infer a revision from uncommitted changes; cluster push explicitly prepares managed source. A saved plan retains the service's change lease until it is applied, abandoned, or expires under the API's rules.

Plan and apply normally poll every two seconds for up to 300 seconds. --timeout accepts 1–3600 seconds. Reaching the deadline stops only the local wait; inspect cluster status RUN_ID to continue following the run. --no-wait prints the accepted run and exits 0. Every HTTP request has a 10-second deadline and an 8 MiB response limit; redirects are refused. --json prints one API envelope to stdout with its provenance and requested/effective/observed labels intact. Progress and idempotency keys use stderr; refusals use a JSON problem object with a type field.

Status and history reads exit 0 when retrieved successfully. Abandoning a saved plan preserves its converged result and exits 0. Managed apply does not prompt for an additional approval: the API checks the authenticated caller's permissions. --as, --server, --profile, --graph, --store, and the global --cluster selector do not apply to these managed cluster operations.

For unattended execution, provide an explicitly scoped automation token and its API origin together:

export OMNIGRAPH_CONTROL_API=https://control.example
# Supply OMNIGRAPH_CONTROL_TOKEN through your CI secret mechanism.
omnigraph cluster apply --plan PLAN_RUN_ID --idempotency-key DEPLOYMENT_KEY --json

The canonical OMNIGRAPH_CONTROL_API must match the selected context. A missing or mismatched pair refuses before any request. These credentials are separate from OMNIGRAPH_BEARER_TOKEN, named servers, and operator profiles.

Without a context, existing direct cluster commands behave as before. --direct explicitly selects that path, ignoring even a malformed context; cluster.yaml still owns the storage root. Managed-only arguments with --direct or without a context refuse. Other cluster verbs, including approve, observe, refresh, and force-unlock, refuse when a managed context is present. API failures never trigger direct execution.

Managed data access

Use cluster token to cache scoped data authority, then query or mutate with --graph from the managed folder. See managed data access for permissions, offline behavior, expiry, and local credential clearing.

Confirmation rules

cleanup changes nothing until --confirm is present. Destructive operations against non-local storage also require interactive confirmation or --yes; in non-interactive and JSON modes they fail closed. The same non-local consent rule applies to overwrite loads and branch deletion, verb or statement.

Compatibility aliases