Branches

Branches are the primary unit of isolation in Omnigraph. Every repository starts with a main branch. You create additional branches to propose changes, run agent tasks, or experiment without affecting the canonical state.

Creating a branch

Create a new branch from an existing one:

omnigraph branch create --uri ./repo.omni --from main feature-x

The new branch feature-x starts at the same snapshot as main. No data is copied — the branch is a pointer that shares storage with its parent until a write causes a table to diverge.

Options

The final positional argument is the name of the new branch.

Listing branches

List all branches in a repository:

omnigraph branch list --uri ./repo.omni

{
  "branches": [
    "feature-x",
    "main"
  ]
}

The branch list is intentionally minimal. Use omnigraph snapshot ./repo.omni --branch <name> to inspect a branch's current manifest version and table state.

Reading from a branch

Any read command accepts a --branch flag to target a specific branch instead of the default (main):

omnigraph read --uri ./repo.omni \
    --query queries.gq \
    --name friends_of \
    --params '{"name": "Alice"}' \
    --branch feature-x

If --branch is omitted, the read runs against main.

Writing to a branch

Load and mutation commands also accept --branch:

omnigraph load ./repo.omni --data updates.jsonl --branch feature-x

omnigraph change --uri ./repo.omni \
    --query mutations.gq \
    --name mark_completed \
    --params '{"slug": "auth"}' \
    --branch feature-x

Each write advances the branch to a new snapshot. Other branches are unaffected.

Agent runs

Transactional runs are recorded automatically for write operations and can also be managed explicitly by server-side workflows. The CLI currently exposes run inspection and lifecycle commands, not run create.

List runs

omnigraph run list ./repo.omni

This shows the known run ids, status, target branch, and internal run branch.

Inspect a run

Check the status and metadata of a run:

omnigraph run show --uri ./repo.omni <run-id>

Publish a run

When a run is still pending, publish it to merge the staged changes back to its target branch:

omnigraph run publish --uri ./repo.omni <run-id>

Publishing validates all mutations against the schema before merging. If validation fails, the run stays open and the error is returned.

Abort a run

If the run produced incorrect results, discard it:

omnigraph run abort --uri ./repo.omni <run-id>

The branch and its mutations are discarded. No changes reach main.