---
title: Quickstart
description: A guided walkthrough from an empty folder to an agent-ready OMGDB store using only real omgdb CLI commands.
---

This walkthrough takes you from an empty folder to a populated, verified, agent-ready store using only commands the `omgdb` binary actually implements. Every step shows the command and a one-line note on what it prints. The example store path is `app.omgdb` throughout.

A store is a directory bundle whose source of truth is an append-only NDJSON op-log (`app.omgdb/oplog.ndjson`). Indexes, vectors, and caches are derived artifacts you can rebuild from that log. See [storage](/docs/storage/) and [architecture](/docs/architecture/) for the full model.

> **Note:** Document, `_id`, filter, projection, pipeline, and update arguments are all passed as JSON **strings**. On a POSIX shell, single-quote them so the shell does not eat the inner double quotes.

## 1. Create a store

The simplest form opens (or creates) a store directory:

```sh
omgdb create app.omgdb
# created store at app.omgdb
```

Optionally seed it from a JSON collection spec with `--from`. The spec defines collections and their validation rules, which are then enforced on insert.

```json
{ "collections": { "users": { "required": ["name"], "fields": { "age": "long" } } } }
```

```sh
omgdb create app.omgdb --from spec.json
# created store at app.omgdb (1 collection(s) defined)
```

> **Note:** `--from` reads the spec as **JSON**, not YAML. Only the `collections` object (with `required` and `fields`) is supported. See [schema validation](/docs/schema-validation/).

## 2. Insert documents

Insert a JSON object into a collection. The assigned `_id` is printed as canonical JSON — an ObjectId rendered `{"$oid":"..."}`.

```sh
omgdb insert app.omgdb users '{"name":"ana","age":30}'
# {"$oid":"018f...c2"}

omgdb insert app.omgdb users '{"name":"bob","age":20}'
# {"$oid":"018f...d7"}
```

The document argument must be a JSON object, or the command errors with `document must be a JSON object`.

## 3. Bulk load with `import-jsonl`

For anything bigger than a handful of documents, stream a JSON Lines file instead of looping `insert`. Each non-empty line must be a JSON object; documents are committed in atomic batches (1,000 per commit by default, tunable with `--batch-size`), so the whole load pays one fsync per batch instead of one per document:

```sh
omgdb import-jsonl app.omgdb users users.jsonl
# {"inserted":50000,"batches":50}
```

Loading 50,000 documents takes about 2 seconds. Single durable inserts are fsync-bound — the same physical wall every embedded database hits — so the batch path is the right tool for bulk data.

## 4. Find with a filter

Find matching documents with a MongoDB-style filter. Each match prints as one canonical-JSON line. The positional filter defaults to `{}` (match all).

```sh
omgdb find app.omgdb users '{"age":{"$gte":25}}'
# {"_id":{"$oid":"018f...c2"},"name":"ana","age":30}
```

Use `--limit N` to cap output and `--project '{"field":1}'` to include (or `0` to exclude) fields. An unknown operator surfaces a clear error naming the bad token (e.g. `$bogus`). The full set is documented in [query operators](/docs/query-operators/).

## 5. Get a document by `_id`

Fetch a single document by its `_id`, parsed as JSON. Pass the ObjectId verbatim:

```sh
omgdb get app.omgdb users '{"$oid":"018f...c2"}'
# {"_id":{"$oid":"018f...c2"},"name":"ana","age":30}
```

If nothing matches, the command exits non-zero with `document not found`.

## 6. Inspect the catalog

List each collection and its document count. With `--json` it emits a machine-readable shape for tools and AI agents.

```sh
omgdb inspect app.omgdb
# users: 2 docs

omgdb inspect app.omgdb --json
# {"collections":[{"name":"users","count":2}]}
```

## 7. Describe the database

`describe` prints a Markdown manual of the live store: each collection, its inferred per-field schema, its indexes and validation spec, and sample documents. This is the page an agent reads to learn a database it has never seen.

```sh
omgdb describe app.omgdb
# ## users
# ... inferred fields (name, age) and sample documents ...
```

See [introspection](/docs/introspection/) for what schema inference covers.

## 8. Import a Markdown file

`import-md` ingests a Markdown file as a single document: YAML frontmatter becomes queryable fields and headings become a stored section tree under `_sections`. It inserts into the named collection and prints the new `_id`.

Given `note.md`:

```text
---
title: Spec
tags: ["a"]
---
# Intro

hello
```

```sh
omgdb import-md app.omgdb docs note.md
# {"$oid":"018f...e9"}

omgdb find app.omgdb docs '{"title":"Spec"}'
# frontmatter is queryable; the document contains _sections
```

More detail in [markdown](/docs/markdown/).

## 9. Create an index

Create a secondary index on one or more fields. Indexes accelerate top-level equality, `$in`, range, and multikey predicates; they hold no authoritative data and can be rebuilt from the log.

```sh
omgdb create-index app.omgdb users name
# created index on `users.name`
```

Multiple fields create a compound index; `--unique` adds a uniqueness constraint; `--partial '<filter-json>'` restricts the index to matching documents:

```sh
omgdb create-index app.omgdb users tenant email --unique
# created unique compound index on `users.(tenant,email)`
```

See [indexes](/docs/indexes/) for what each variant accelerates and how the planner proves an index safe before using it.

## 10. Explain a query

`explain` shows how a filter will be executed — index scan versus full scan — by compiling the filter and reporting the chosen plan.

```sh
omgdb explain app.omgdb users '{"name":"ana"}'
# describes whether the users.name index is used or a full scan is needed
```

For a "why-not" view of per-predicate selectivity, use `omgdb diagnose app.omgdb users '<filter>'`; for machine-readable index recommendations, `omgdb suggest-indexes`.

## 11. Vector search a text field

`vsearch` ranks documents by similarity of a text field to a query using the bundled offline embedder. Each hit prints as `<score>\t<document>`.

```sh
omgdb vsearch app.omgdb docs text "database search" --k 5
# 0.7421	{"_id":{"$oid":"..."},"text":"database search and indexing", ...}
```

Use `--filter '<json>'` to pre-filter candidates (hybrid search). To persist embeddings for reuse, run `omgdb vsync app.omgdb docs text`, which writes a sidecar collection `docs.__vectors`.

> **Note:** The bundled embedder is a deterministic, dependency-free hashing baseline — not a neural model — so relevance is approximate. See [vector search](/docs/vector-search/) and [context packs](/docs/context-packs/).

## 12. Verify the store

`verify` re-reads the op-log and proves that replaying it reproduces the state — every record and every derived cache. This is the integrity check that makes the text-canonical design trustworthy.

```sh
omgdb verify app.omgdb
# OK: 4 record(s), 3 document(s) in 2 collection(s); log reproduces state
```

It exits non-zero with `INCONSISTENT` if replay does not reproduce the state. If a write was interrupted, the torn trailing fragment is preserved to `oplog.torn.bak` and trimmed from the log on open, noted with a `WARN` on stderr — nothing is silently dropped. To recover a genuinely corrupt log, see `omgdb repair` in [storage](/docs/storage/).

## Peek at the text-canonical log

Because the op-log is plain NDJSON with a per-record CRC32, you can read it directly. Each line is `<canonical-json>\t<crc32-hex>`:

```sh
cat app.omgdb/oplog.ndjson
# {"lsn":0,"ts":{"$date":1719900000000},"op":"insert","ns":"users","id":{"$oid":"018f...c2"},"doc":{"_id":{"$oid":"018f...c2"},"name":"ana","age":30}}	1a2b3c4d
# {"lsn":1,"ts":{"$date":1719900012000},"op":"insert","ns":"users","id":{"$oid":"018f...d7"},"doc":{"_id":{"$oid":"018f...d7"},"name":"bob","age":20}}	5e6f7a8b
# ...
```

This file is the entire authoritative state of the database. Everything else — including the `.cache` sidecars you may see next to it — is derived and rebuildable.

## Point an agent at it

To drive the store from a coding agent, run the MCP (Model Context Protocol) stdio server. The capability ceiling is set with `--scope` (`read`, `read-write` (default), or `dangerous`).

```sh
omgdb mcp --scope read-write
# JSON-RPC over stdio; serverInfo name "omgdb"; tools include vsearch and aggregate
```

The combination of `describe` (the manual), `explain`/`diagnose` (the debugger), `verify` (the proof), and the MCP server is what makes a store agent-ready. See [mcp](/docs/mcp/) and [agent mutations](/docs/agent-mutations/).

## Where to next

- [Data model](/docs/data-model/) — the value types and canonical JSON.
- [Query operators](/docs/query-operators/) — the full filter language.
- [Update operators](/docs/update-operators/) — the full set, from `$set` and `$inc` to `$push`, `$rename`, and `$pop`.
- [Aggregation](/docs/aggregation/) — pipeline stages and expressions.
- [Indexes](/docs/indexes/) — what is and isn't accelerated.
- [Vector search](/docs/vector-search/) and [context packs](/docs/context-packs/) — semantic retrieval.
- [Agent mutations](/docs/agent-mutations/) — plan / apply / rollback.
- [MCP](/docs/mcp/) — the agent server and its tools.
- [Storage](/docs/storage/) and [architecture](/docs/architecture/) — how the log, replay, and recovery work.