CLI reference

This page maps the CLI; 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

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>; with multiple declarations the positional name selects one. A stored server query is its registry name alone. Parameters come inline, --params '{"name":"Ada"}', or from a file, --params-file params.json. --set NAME=VALUE, repeatable, gives a session setting a value for the run of query, mutate, branch merge, commit changes, changes poll, and load. The source may instead be one branch statement, mutate -e 'branch create b0' or query -e 'branch list' (writes through mutate, the listing through query; no --branch, --snapshot, --if-commit, name, or params; see Work with branches), or one explain statement, query -e 'explain query q() { … }', answering the plan as rows under the query's own target and params; see Explain.

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 use the JSON result spelling; table, csv, and kv print strings unquoted. --format json prints the envelope pretty and the rows array compact; a refusal follows Diagnostics.

Machine-readable read and write positions

query --json returns graph_commit_id when its read snapshot has a graph head. The id and rows share one pinned snapshot; use that id for a later conditional mutation.

Successful mutate --json and load --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.

--json and read --format json preserve structured errors on stdout. Data-write failures report whole-command outcomes and exits. Verified HTTP conditional mismatches exit 4; embedded mismatches exit 1 because writable open can complete earlier work.

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 against a server, 1 on an embedded --store run; 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 --json
omnigraph upgrade ./graph.omni --json
omnigraph schema upgrade-system-columns ./graph.omni --check --json

--store is an alternative to the positional storage URI. omnigraph upgrade converts a standalone v8, v9 (release 0.11.x) or v13 graph to v14, offline and in place, keeping branches and commit history; stop every process using the graph and retain a verified whole-root backup first. --check writes nothing; --to-format accepts 14 only. check_passed, already_current (a v14 graph) and completed exit 0; check_failed (unsupported_source for any other format below 14, newer_than_binary above 14, unsupported_target) and recovery_required (a pending attempt, finished as recovery.action says, or leftover recovery files) exit 1. The report names the formats, the route, the work counts, findings and the recovery action. Server and cluster addressing are refused; see storage upgrade. schema upgrade-system-columns is a separate operation on a served graph: system-column upgrade.

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.

In a selected managed folder, implicit load --graph <ID> uses the separate cached data credential. It requires change, plus branch_create when --from is present. Managed loads bound input to 32 MiB, responses to 8 MiB, and one request to 300 seconds; uncertain writes are never automatically retried. See managed bulk loading for limits, permissions, ordinary addressing, and reconciliation.

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

Add --managed to select the managed service explicitly. Without it, cluster uses self-hosted configuration or an explicit server/root and ignores managed folder context. The flag can appear before or after the subcommand.

omnigraph login --api ORIGIN reuses valid cached access or prints a WorkOS AuthKit verification URL and user code. The OS keychain holds provider-bound access and rotating refresh credentials; old opaque sessions are not reused. Access lasts at most 15 minutes; silent renewal ends eight hours after sign-in. Normal commands never open browser login. Login JSON reports identity and expiry metadata, never credentials. Temporary errors preserve cached access; an uncertain refresh is never replayed and may require explicit login. See the authentication contract for binding, coordination and refresh bounds.

omnigraph logout --api ORIGIN requests provider-session revocation and clears local credentials. Its provider_revocation_confirmed result reports whether revocation succeeded. Accepted runs continue. Named-server login is unchanged.

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

--managed requires its own context, except creation and explicit-origin operation lookup; --direct is rejected. Managed API failures never trigger local deployment. Service-only create, push, delete, undo-delete, token, operation, history, and cancel require --managed. Local validate, observe, force-unlock, and upgrade-ledger reject it. Managed plan takes --rev and managed apply requires --plan; self-hosted deployment flags cannot be combined with them. Use cluster operation --managed OPERATION_ID [--wait] for service lifecycle observation; cluster status --managed [RUN_ID] reads cluster projections or a managed run. Self-hosted cluster status --deployment-id ID addresses a separate deployment receipt.

Managed data access

After login and cluster selection, use graphs list to discover graphs, then query, mutate, load, or commit reads with --graph from the managed folder. Missing or expired identity credentials are acquired before the operation; applied Cedar policy decides permissions. See managed data access for offline behavior, identity binding, discovery and 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.