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:

Served writes ignore --as: the server derives the actor from the bearer token.

Commands

The CLI guide gives end-to-end examples. Maintenance safety is covered in Maintenance.

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 can be supplied inline or from a file:

--params '{"name":"Ada"}'
--params-file params.json

Read output supports table, json, jsonl, csv, and kv. --json is the stable machine-readable form for commands that do not use --format.

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.

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.

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.

Compatibility aliases

These aliases are compatibility-only. Use the canonical names in new automation.