okc reads a database schema and produces an OKF bundle — a directory of cross-linked markdown documents that turn your schema into a navigable knowledge graph.
# Introspect any SQLite or PostgreSQL database
$ okc introspect sqlite:///path/to/database.db --out ./my-bundle
# Output:
my-bundle/
├── index.md
├── tables/
│ ├── index.md
│ ├── users.md
│ └── orders.md
└── views/
├── index.md
└── active_orders.md
A focused tool with strong opinions about determinism, portability, and zero configuration.
Same database, same schema — identical bundle every time. No randomness, no drift. Reliable for CI/CD pipelines and version control.
Introspect SQLite and PostgreSQL databases through a shared Source interface. Add new backends without changing the bundle layer.
Generates valid OKF v0.1 documents with type, title, description, resource, tags, and timestamp frontmatter.
Foreign key relationships become navigable markdown links across documents. Every REFERENCES constraint is a hyperlink.
index.md files are generated for every directory, listing both subdirectories and typed entries. Navigation is built in.
Point it at a database URL and get a bundle. No config files, no YAML schemas to write, no DSL to learn.
okc is a Python CLI. Install from PyPI or source, point it at a database, and get an OKF bundle.
# Install from PyPI
$ pip install okc
# Or install from source
$ git clone https://github.com/Auran0s/okc
$ cd okc
$ pip install -e .
# With dev dependencies
$ pip install -e ".[dev]"
# Introspect a SQLite database
$ okc introspect sqlite:///path/to/database.db --out ./my-bundle
# Custom output directory
$ okc introspect sqlite:///path/to/database.db --out ./docs/database
# Introspect PostgreSQL
$ okc introspect postgresql://user:password@localhost:5432/mydb --out ./pg-bundle
# JSON output (for CI/CD)
$ okc introspect --json sqlite:///path/to/database.db
| Argument | Required | Default | Description |
|---|---|---|---|
| url | Yes | — | Database URL (sqlite:// or postgresql://) |
| --out | No | ./okf-bundle | Output directory for generated bundle |
| --quiet | No | false | Suppress stdout (stderr still flows) |
| --json | No | false | Output structured JSON instead of styled terminal |
| --version | No | — | Print version and exit |
Everything you need to understand how okc works and what it produces.
sqlite:///path/to/file.db
postgresql://user:password@host:5432/db
Each concept document captures one database object. Documents are cross-linked, indexed, and validated against directory traversal attacks.
# Directory structure (single schema)
my-bundle/
├── index.md
├── tables/
│ ├── index.md
│ ├── users.md
│ ├── orders.md
│ └── products.md
└── views/
├── index.md
└── active_orders.md
# PostgreSQL multi-schema
my-bundle/
└── tables/
├── index.md
├── public/
│ ├── index.md
│ ├── users.md
│ └── orders.md
└── audit/
├── index.md
└── log.md
# YAML frontmatter
---
type: table
title: users
description: Registered user accounts
resource: sqlite:///path/to/database.db
tags: []
timestamp: "2026-06-17T12:00:00Z"
---