CLI

Install the Omnigraph binaries, understand the command surface, and configure local or remote targets.

The Omnigraph CLI is the main operator surface for local graphs and remote servers. It manages graphs, loads data, runs queries, applies mutations, and controls branching from the terminal.

Omnigraph ships as two binaries:

omnigraph
omnigraph-server

Install

Quick install:

curl -fsSL https://raw.githubusercontent.com/ModernRelay/omnigraph/main/scripts/install.sh | bash

Homebrew:

brew tap ModernRelay/tap
brew install ModernRelay/tap/omnigraph

For release channels, source builds, and platform-specific details, see Install.

Commands

Command	Purpose
`version`	Print the CLI version
`embed`	Generate, clean, or refresh explicit seed embeddings
`init`	Create a new graph from a schema file
`load`	Load JSONL data into a local graph
`ingest`	Load JSONL into a named review branch
`schema plan` / `schema apply`	Plan or apply supported schema migrations
`snapshot`	Inspect the current state of a branch
`export`	Export a branch snapshot as JSONL
`branch create` / `list` / `delete` / `merge`	Manage branches
`read`	Run a read query against a branch or snapshot id
`change`	Run a mutation against a branch
`commit list` / `show`	Inspect graph commit history
`optimize`	Compact small Lance fragments across every table
`cleanup`	Remove old Lance versions (destructive; requires `--confirm`)
`policy validate` / `test` / `explain`	Validate and explain policy decisions
`query lint` / `check`	Lint or schema-check `.gq` query files

Basic usage pattern

Commands use one of three patterns:

omnigraph <command> [URI] [options]
omnigraph <command> --uri <URI> [options]
omnigraph <group> <subcommand> [options]

Read and change commands use explicit flags:

omnigraph read --uri ./graph.omni --query queries.gq --name my_query

Local vs remote mode

Read, change, branch, snapshot, export, commit, and ingest commands can target a remote Omnigraph server by pointing --uri or a configured target at an HTTP endpoint:

omnigraph read --uri http://localhost:8080 --query queries.gq --name my_query

Graph-creation commands such as init and direct local loads via load operate on storage directly rather than through the HTTP server.

Configuration

An omnigraph.yaml file in your project root can define named graphs, defaults, and query aliases:

graphs:
  local:
    uri: ./graph.omni
  dev:
    uri: http://127.0.0.1:8080
    bearer_token_env: OMNIGRAPH_BEARER_TOKEN

cli:
  graph: local
  branch: main

query:
  roots:
    - queries
    - .

With this config, you can define aliases and run shorter commands against local or remote graphs without repeating the full argument list every time.

Global flags

Flag	Purpose
`--as <ACTOR>`	Set the actor identity for engine-layer policy evaluation on direct-engine writes. Overrides `cli.actor` from `omnigraph.yaml`. No-op against remote HTTP URIs. Those resolve the actor from the bearer token.

Server binary

omnigraph-server is a separate binary that serves a graph over HTTP.

omnigraph-server <graph-uri> [options]

Flag	Description
`--bind <ip:port>`	Address to listen on (default `127.0.0.1:8080`)
`--unauthenticated`	Allow the server to start without bearer tokens (otherwise it refuses)
`--target <name>`	Resolve the graph URI from `omnigraph.yaml` `graphs.<name>`
`--config <path>`	Load configuration from a non-default `omnigraph.yaml`

See Deployment and Operations → Server for the full HTTP surface, auth model, and runtime states.

Output formats

read supports table, key-value, CSV, JSONL, and JSON output. Use --json for structured JSON or --format for the other renderers:

Flag	Format
(default)	Human-readable table
`--json`	Structured JSON payload with metadata and rows
`--format kv`	Key-value rendering
`--format csv`	Comma-separated values with a header row
`--format jsonl`	Metadata line followed by one JSON object per row
`--format table`	Explicit table rendering

Example with table output:

omnigraph read --uri ./graph.omni --query queries.gq --name friends_of --params '{"name": "Alice"}'

3 rows from branch main via friends_of

NAME          AGE
Bob           32
Carol         28
Dave          45

Example with JSON output:

omnigraph read --uri ./graph.omni --query queries.gq --name friends_of --params '{"name": "Alice"}' --json

{
  "query_name": "friends_of",
  "target": {
    "branch": "main",
    "snapshot": null
  },
  "row_count": 3,
  "columns": ["name", "age"],
  "rows": [
    { "name": "Bob", "age": 32 },
    { "name": "Carol", "age": 28 },
    { "name": "Dave", "age": 45 }
  ]
}

On this page