mirror of https://github.com/ModernRelay/omnigraph.git synced 2026-06-09 01:35:18 +02:00

Ragnor Comerford 6f25c4f9f8

Address reviewer feedback (Cursor + cubic) on PR #60

All eight comments verified against source and applied:

- AGENTS.md: pull @docs/{invariants,lance,testing}.md imports out of
  the markdown blockquote. Claude Code's @-import parser expects @ at
  column 0; the leading "> " of a blockquote silently broke
  recognition, so the claimed auto-include did nothing. (Cursor,
  Medium severity.)
- docs/cli-reference.md: command-family count 13 → 17. The current
  enum Command in crates/omnigraph-cli/src/main.rs has 17 top-level
  variants. (cubic P2.)
- docs/ci.md: Homebrew tap update is a regular `git push`, not a
  force-push (release.yml:117 is `git push origin HEAD:main`). (cubic
  P2.)
- docs/errors.md: add the Storage variant to the NanoError list — it
  exists at error.rs:88-89 but the doc enumerated only 10 of 11.
  (cubic P2.)
- docs/storage.md: clarify tombstone semantics. There is no
  tombstone_version column; state.rs:180 reads the tombstone version
  from the table_version column on rows where object_type =
  table_tombstone. (cubic P2.)
- docs/branches-commits.md: split the GraphCommit pseudo-struct from
  the underlying storage. actor_id is joined in-memory from
  _graph_commit_actors.lance, not a column on _graph_commits.lance.
  (cubic P2.)
- docs/schema-language.md: rename IR_VERSION to SCHEMA_IR_VERSION to
  match the actual constant name in catalog/schema_ir.rs:11.
  (cubic P3.)
- docs/testing.md: engine integration test count 16 → 15 (matches
  `ls crates/omnigraph/tests/*.rs`). (cubic P3.)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-04-29 00:09:06 +02:00

2.9 KiB

Raw Blame History

CLI Reference (`omnigraph`)

A reference for the omnigraph binary's command surface and omnigraph.yaml schema. For a quick-start guide, see cli.md.

17 top-level command families, 40+ subcommands. All commands accept either a positional URI, --uri, or a --target <name> resolved against omnigraph.yaml.

Top-level commands

Command	Purpose
`init`	`--schema <pg>` → initialize a repo (also scaffolds `omnigraph.yaml` if missing)
`load`	bulk load a branch (`--mode overwrite\|append\|merge`)
`ingest`	branch-creating transactional load (`--from <base>`)
`read`	run named query (params via `--params`, `--params-file`, or alias args)
`change`	run mutation query
`snapshot`	print current snapshot (per-table version + row count)
`export`	dump to JSONL on stdout (`--type T`, `--table K` filters)
`branch create \| list \| delete \| merge`	branching ops
`commit list \| show`	inspect commit graph
`run list \| show \| publish \| abort`	transactional run ops
`schema plan \| apply \| show (alias: get)`	migrations
`query lint \| check`	offline / repo-backed validation
`optimize`	non-destructive Lance compaction
`cleanup --keep N --older-than 7d --confirm`	destructive version GC
`embed`	offline JSONL embedding pipeline
`policy validate \| test \| explain`	Cedar tooling
`version` / `-v`	print `omnigraph 0.3.x`

`omnigraph.yaml` schema

project: { name }
graphs:
  <name>:
    uri: <local|s3://|http(s)://>
    bearer_token_env: <ENV_NAME>
server:
  graph: <name>
  bind: <ip:port>
cli:
  graph: <name>
  branch: <name>
  output_format: json|jsonl|csv|kv|table
  table_max_column_width: 80
  table_cell_layout: truncate|wrap
query:
  roots: [<dir>, …]   # search path for .gq files
auth:
  env_file: ./.env.omni
aliases:
  <alias>:
    command: read|change
    query: <path-to-.gq>
    name: <query-name>
    args: [<positional-name>, …]
    graph: <name>
    branch: <name>
    format: <output-format>
policy:
  file: ./policy.yaml

Output formats (read command)

json — pretty-printed object with metadata + rows
jsonl — one metadata line then one JSON object per row
csv — RFC 4180-ish quoting
table — fitted text table, honors table_max_column_width + table_cell_layout
kv — grouped per-row key/value blocks

Param resolution

Precedence (high to low): explicit --params / --params-file, alias positional args, omnigraph.yaml defaults. JS-safe-integer handling is built in (is_js_safe_integer_i64, JS_MAX_SAFE_INTEGER_U64) so 64-bit ids round-trip safely through JSON clients.

Bearer token resolution (CLI)

graphs.<name>.bearer_token_env
OMNIGRAPH_BEARER_TOKEN global env
auth.env_file referenced .env

Duration parsing (cleanup)

s | m | h | d | w units, e.g. --older-than 7d.

2.9 KiB Raw Blame History

CLI Reference (omnigraph)