CLI Reference

The OMGDB command-line interface is a single binary named omgdb. It is a thin, LLM-friendly wrapper over the embedded engine: create a store, insert and fetch documents, run MongoDB-style queries and aggregations, introspect and repair the op-log, embed and search text, plan auditable mutations, and serve the database to agents over MCP.

Almost every command follows the same shape: a subcommand, the store directory, then any positional or flag arguments. Documents, _ids, filters, projections, pipelines, and update specs are always passed as JSON strings.

omgdb <command> <store-path> [args...]

This page is the authoritative reference for the omgdb binary. There is no omg binary, and there are no init, ask, import, or debug-query commands — see the notes on each related command below for the real equivalents.

Command summary

OMGDB exposes the following subcommands, grouped by area. Multi-word commands use kebab-case (import-md, create-index, plan-update).

Stores & CRUD

These commands create stores and read or write individual documents. See the data model for how documents, _ids, and BSON-style types are represented.

create

Create (open) a store at <path>. With --from, OMGDB reads a JSON collection-spec file and defines each named collection, which then enforces validation on insert.

omgdb create <path> [--from <spec>]

On success it prints created store at <path>, noting how many collections were defined when --from is used.

Note: The --from spec is parsed as JSON, not YAML. Only collection definitions ({"collections":{...}} with required/fields) are supported.

# spec.json: {"collections":{"users":{"required":["name"],"fields":{"age":"long"}}}}
omgdb create app.omgdb --from spec.json
omgdb insert app.omgdb users '{"name":"ana","age":30}'
omgdb validate app.omgdb users   # prints 'valid'

insert

Insert a JSON object document into <collection>. The document is assigned an _id (an ObjectId unless you supply your own _id), and the assigned id is printed as canonical JSON, e.g. {"$oid":"..."}. The argument must be a JSON object, or the command fails with document must be a JSON object.

omgdb insert <path> <collection> <json>

omgdb insert app.omgdb users '{"name":"ana"}'   # prints {"$oid":"..."}

get

Fetch a single document by its _id. The id argument is parsed as JSON — an ObjectId {"$oid":"..."} or a bare scalar such as 7. The matched document is printed as canonical JSON; if there is no match the command exits non-zero with document not found.

omgdb get <path> <collection> <id>

omgdb get app.omgdb users '{"$oid":"..."}'

find

Find documents matching a MongoDB-style JSON filter. The positional filter defaults to {} (match all). Each match is printed as one canonical-JSON line. An unknown operator surfaces a clear error naming the offending token.

omgdb find <path> <collection> [filter] [--limit <N>] [--project <json>]

omgdb find app.omgdb users '{"age":{"$gte":25}}'

inspect

Print each collection and its document count. By default it prints text lines of the form <ns>: <n> docs (or (empty store) for an empty store). With --json it emits {"collections":[{"name":..,"count":..},..]} as canonical JSON.

omgdb inspect <path> [--json]

omgdb inspect app.omgdb --json

Aggregation

aggregate

Run an aggregation pipeline given as a JSON array of stages. Each output document is printed as canonical JSON, one per line.

omgdb aggregate <path> <collection> <pipeline>

omgdb aggregate app.omgdb emp '[{"$group":{"_id":"$dept","total":{"$sum":"$sal"}}},{"$sort":{"_id":1}}]'

Introspection

These commands describe, export, explain, and diagnose a store without changing it. See introspection for the underlying concepts.

describe

Print a Markdown manual of the database: collections, inferred schema, and sample documents. Output includes section headers such as ## <collection>.

omgdb describe <path>

omgdb describe app.omgdb

dump

Print a deterministic canonical export of every document in the store. Useful for diffs and golden snapshots.

omgdb dump <path>

omgdb dump app.omgdb

explain

Explain how a query filter will be executed — index scan versus full scan. The MongoDB-style JSON filter is compiled and its execution plan printed. See indexes for what makes a filter index-eligible.

omgdb explain <path> <collection> <filter>

omgdb explain app.omgdb users '{"name":"ana"}'

diagnose

Diagnose why a query matches what it does — the “why-not” debugger. It reports per-predicate selectivity for the filter and prints the report as canonical JSON.

omgdb diagnose <path> <collection> <filter>

omgdb diagnose app.omgdb users '{"age":{"$gte":25}}'

validate

List documents in <collection> that violate the collection’s validation rules. Prints valid: no violations in “ when clean; otherwise prints <id>: <reason> per offender and exits non-zero with <n> document(s) violate validation rules.

omgdb validate <path> <collection>

omgdb validate app.omgdb users

verify

Verify op-log integrity and that replaying the log reproduces the live state. On success it prints OK: <records> record(s), <documents> document(s) in <collections> collection(s); log reproduces state. If a torn trailing record (from an interrupted write) was skipped on open, a WARN is written to stderr. It exits non-zero with INCONSISTENT: ... if replay does not reproduce live state.

omgdb verify <path>

omgdb verify app.omgdb

Durability

These commands operate on the op-log and the on-disk archive format. See storage for the op-log layout and transactions for the durability model.

repair

Recover a corrupt op-log. Because a corrupt store cannot be opened, repair operates directly on the raw log file at <path>/oplog.ndjson.

omgdb repair <path> [--truncate] [--yes]

With no flags it is a non-destructive dry run: it prints OK: log is intact (<n> record(s)); nothing to repair, or CORRUPT at byte <g> of <total>: <reason> plus the recoverable prefix count, and advises re-running with --truncate --yes. With --truncate --yes it backs up the original to oplog.ndjson.corrupt.bak, truncates to the recoverable prefix, and prints repaired: kept <n> record(s); .... Using --truncate without --yes refuses with refusing to modify the log without —yes“.

Limitation: repair manipulates oplog.ndjson directly and must be run only when the store is closed.

omgdb verify app.omgdb                      # fails on a corrupt log
omgdb repair app.omgdb                      # dry-run: prints CORRUPT, no changes
omgdb repair app.omgdb --truncate --yes     # backs up to oplog.ndjson.corrupt.bak, prints 'repaired'
omgdb verify app.omgdb                      # now OK

compact

Compact the op-log to its minimal form, dropping superseded history. Prints compacted: <before> -> <after> records.

omgdb compact <path>

omgdb compact app.omgdb

pack

Bundle a store directory into a single, legible .omgdb archive file at <output>. The archive begins with the magic line OMGDB-PACK v1, then FILE <rel> <len>\n<bytes>\n entries. It includes oplog.ndjson plus the pending/ and changes/ sidecars in deterministic order; transient LOCK, *.bak, and *.repairing files are excluded. Prints packed <path> into <output>.

omgdb pack <path> <output>

omgdb pack app.omgdb archive.omgdb

unpack

Unpack a .omgdb archive <input> into a fresh store directory <path>. Prints unpacked <n> file(s) into <path>. It refuses if <path> already contains a store (an oplog.ndjson is present) and rejects archives with bad magic or unsafe (absolute, .., or root) entry paths.

omgdb unpack <input> <path>

Note: unpack argument order is <input> then <path> (archive first, destination second) — the reverse of pack’s <path> then <output>.

omgdb pack app.omgdb archive.omgdb
omgdb unpack archive.omgdb dest.omgdb
omgdb verify dest.omgdb
omgdb find dest.omgdb c {}

Indexes

create-index

Create a secondary equality index on <collection>.<field>. Prints created index on .“.

omgdb create-index <path> <collection> <field>

omgdb create-index app.omgdb users name

Markdown

import-md

Import a Markdown file as a single document: YAML frontmatter becomes queryable fields and headings become stored sections under a _sections field. The document is inserted into <collection> and its assigned _id is printed as canonical JSON.

omgdb import-md <path> <collection> <file>

omgdb import-md app.omgdb docs note.md
omgdb find app.omgdb docs '{"title":"Spec"}'   # frontmatter is queryable; output contains _sections

Vectors

The vector commands use the offline omgdb_vector::HashingEmbedder — a deterministic, dependency-free embedder, not an external transformer service. Relevance is therefore approximate. See vector search and context packs.

vsearch

Semantic search: rank documents in <collection> by similarity of <field> to <query>. Prints <score:.4>\t<doc-canonical-json> per hit.

omgdb vsearch <path> <collection> <field> <query> [--k <N>] [--filter <json>]

omgdb vsearch app.omgdb docs text "database search" --k 5

context

Build a token-budgeted context pack for a task: retrieve the most relevant chunks of <field> for <query> and print the bundle as canonical JSON. The output JSON contains the keys citations, chunks, and budgetTokens.

omgdb context <path> <collection> <field> <query> [--budget <N>] [--filter <json>]

omgdb context app.omgdb docs text "database search" --budget 500
# stdout JSON contains "citations", "chunks", "budgetTokens":500

vsync

Persist embeddings for <field> into the sidecar collection <collection>.__vectors (with provenance). Prints synced <n> embedding(s) into .__vectors“. The vectors form an ordinary, inspectable collection (visible in inspect as e.g. docs.__vectors).

omgdb vsync <path> <collection> <field>

omgdb vsync app.omgdb docs text

vstale

List _ids whose persisted embedding for <field> is stale — missing, built from a different model, or built from text that has since changed. Each stale _id is printed as canonical JSON to stdout, and a summary <n> stale embedding(s) is printed to stderr.

omgdb vstale <path> <collection> <field>

omgdb vstale app.omgdb docs text   # stderr: '1 stale embedding(s)'
omgdb vsync app.omgdb docs text    # stdout: 'synced 1 embedding(s) into `docs.__vectors`'
omgdb vstale app.omgdb docs text   # stderr: '0 stale embedding(s)'

Mutations

The plan-update → apply → rollback trio implements an auditable change workflow keyed by an opaque token (from plan-update) and change id (from apply). See agent mutations for the full workflow.

plan-update

Dry-run an update: plan the changes without writing. Takes a MongoDB-style JSON filter and an update spec ($set / $unset / $inc) and prints {token, matched, sample} as canonical JSON. The token feeds into apply.

omgdb plan-update <path> <collection> <filter> <update>

omgdb plan-update app.omgdb users '{"age":{"$gte":25}}' '{"$set":{"active":true}}'

apply

Apply a previously planned change by its <token> (from plan-update). Prints the apply result, including a change id, as canonical JSON.

omgdb apply <path> <token>

omgdb apply app.omgdb <token-from-plan-update>

rollback

Roll back a previously applied change by its <change_id> (from apply). Prints rolled back <n> document(s).

omgdb rollback <path> <change_id>

omgdb rollback app.omgdb <change-id-from-apply>

Agent

mcp

Run an MCP (Model Context Protocol) server over stdio for LLM agents. It speaks newline-delimited JSON-RPC 2.0, reports serverInfo name omgdb, and answers initialize, tools/list, and tools/call.

omgdb mcp [--scope <scope>]

A read server advertises and permits only the read tools (find, aggregate, describe, explain, diagnose, vsearch, context_pack); read-write adds the mutation tools (insert, plan_update, apply, rollback). Tools above the ceiling are neither advertised in tools/list nor permitted in tools/call.

Note: No tool actually requires dangerous scope, so --scope dangerous advertises and permits exactly the same tools as --scope read-write. There is no destructive (drop/delete) tool implemented.

omgdb mcp
# stdin (JSON-RPC, newline-delimited):
# {"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
# {"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
# stdout contains serverInfo, "name":"omgdb", and tools incl. vsearch, aggregate