CLI

The Omnigraph CLI is a single Rust binary that manages graph repositories, loads data, runs queries, and controls branching — all from the terminal. No server, no Docker, no runtime dependencies.

Install from source

git clone https://github.com/ModernRelay/omnigraph.git
cd omnigraph
cargo build --release -p omnigraph-cli

The compiled binary is at target/release/omnigraph. Add it to your PATH or copy it to a directory that is already on your PATH.

Commands

Command	Purpose
`init`	Create a new repository from a schema file
`load`	Load JSONL data into a repository
`read`	Run a read query against a branch or snapshot
`change`	Run a mutation against a branch
`branch create`	Create a new branch from an existing one
`branch list`	List all branches in a repository
`branch merge`	Merge one branch into another
`snapshot`	Inspect the current state of a branch
`search`	Run a search query across indexed fields
`run create`	Create an isolated agent run
`run show`	Inspect the state and mutations of a run
`run publish`	Merge a completed run back to its parent branch
`run abort`	Discard a run and its mutations
`diff`	Compare graph state between two snapshots

Basic usage pattern

Most commands follow the same shape:

omnigraph <command> <repository-path> [options]

The repository path is always a positional argument pointing to a .omni directory on the local filesystem:

omnigraph read ./repo.omni --query queries.gq --name my_query

Local vs. remote mode

By default, the CLI operates directly on local files. When Omnigraph is running in server mode, commands can target a remote instance by specifying a URL instead of a file path:

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

The same commands and flags work in both modes.

Configuration

An omnigraph.yaml file in your project root can define aliases and defaults:

target: ./repo.omni

aliases:
  unblocked: 
    command: read
    query: queries.gq
    name: unblocked_tasks
  complete:
    command: change
    query: mutations.gq
    name: mark_completed

With this config, you can run:

omnigraph unblocked --json
omnigraph complete --params '{"slug": "auth"}'

Instead of spelling out the full command each time.

Output formats

Most commands support an output format flag:

Flag	Format
(default)	Human-readable table
`--json`	JSON array of objects
`--jsonl`	One JSON object per line (newline-delimited)
`--csv`	Comma-separated values with a header row

Example with table output (default):

omnigraph read ./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 ./repo.omni --query queries.gq --name friends_of --params '{"name": "Alice"}' --json

[
  { "name": "Bob", "age": 32 },
  { "name": "Carol", "age": 28 },
  { "name": "Dave", "age": 45 }
]