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 repositories and remote servers. It manages graph repositories, 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 repository from a schema file
`load`	Load JSONL data into a local repository
`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
`run list` / `show` / `publish` / `abort`	Inspect or manage transactional runs
`commit list` / `show`	Inspect graph commit history
`policy validate` / `test` / `explain`	Validate and explain policy decisions

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 ./repo.omni --query queries.gq --name my_query

Local vs remote mode

Read, change, branch, snapshot, export, run, 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

Repository-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 aliases, defaults, and targets:

targets:
  local:
    uri: ./repo.omni
  dev:
    uri: http://127.0.0.1:8080
    bearer_token_env: OMNIGRAPH_BEARER_TOKEN

cli:
  target: local
  branch: main

query:
  roots:
    - queries
    - .

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

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 ./repo.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 ./repo.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 }
  ]
}