mdb-cli 0.1.1

Markdown table workflows w/ SQLite powers ✨

mdb-cli

Markdown table workflows w/ SQLite powers ✨

mdb-cli provides the mdb command-line tool to make markdown tables data-driven and queryable via SQL, using specialized co-located markers 💾 ... with some embedded inline SQL queries to define and dynamically view our project-level data.

• Zero runtime dependencies -- standard library only
• Simple integration -- add markers and get running
• Python 3.11+ required

Installation

Install from PyPI:

# Using pipx (recommended)
pipx install mdb-cli

# Using uv (recommended)
uv tool install mdb-cli

# Using pip
pip install mdb-cli

After installation, verify the tool is available:

mdb --help

For development installation, see CONTRIBUTING.md.

Basic Usage

Marker Syntax

Place inline query markers above tables in your markdown file using the following format:

`💾 [scope] <directive> <sql-query>`

Component	Description
💾	Marker prefix -- identifies the line as an mdb marker
[scope]	Optional named scope identifier of the dataset
<directive>	Directive: 🌀 (feed) or 💎 (tap)
<sql-query>	SQL query to execute against the dataset

Directives

Directive	Name	Instruction
🌀	feed	Include the table below me as part of the dataset
💎	tap	Execute my SQL query on the dataset and render the results as the table below me (table auto-generated if absent)

Under the hood, datasets are dynamically backed by SQLite databases on which SQL queries are actually run 🚀

Subcommands

Subcommand	Behavior
mdb push	process all 🌀 markers first (pulls), then all 💎 markers after (pushes) — reports only changed markers by default
mdb push <sql-mutation>	process all 🌀 markers first (pulls), execute the mutation, then all 🌀 and 💎 markers after (pushes)
mdb pull <sql-query>	process all 🌀 markers first (pulls), then outputs SQL query results in CSV format
mdb status	inspects all 🌀 and 💎 markers, then reports metadata and warnings

Example

Given a project file snacks.md with the following content:

# Snacks

## Inventory

`💾 🌀 SELECT * FROM snacks`

| name               | vibe               | qty |
| ------------------ | ------------------ | --- |
| Hot Cheese Popcorn | chaos energy       | 3   |
| Pocky              | elegant simplicity | 12  |
| Takis              | rolled-up danger   | 7   |
| Goldfish           | the people's snack | 41  |

## Low stock

`💾 💎 SELECT name, qty FROM snacks WHERE qty < 10 ORDER BY qty`

After running:

mdb push

We'll have the snacks.md updated to the following content:

# Snacks

## Inventory

`💾 🌀 SELECT * FROM snacks`

| name               | vibe               | qty |
| ------------------ | ------------------ | --- |
| Hot Cheese Popcorn | chaos energy       | 3   |
| Pocky              | elegant simplicity | 12  |
| Takis              | rolled-up danger   | 7   |
| Goldfish           | the people's snack | 41  |

## Low stock

`💾 💎 SELECT name, qty FROM snacks WHERE qty < 10 ORDER BY qty`

| name               | qty |
| ------------------ | --- |
| Hot Cheese Popcorn | 3   |
| Takis              | 7   |

The 🌀 (feed) marker ingests the snacks data into the (unscoped) dataset, then the 💎 (tap) marker executes the query and surfaces only the snacks running low in stock.

---

Additionally, after running:

mdb pull "SELECT SUM(qty) as total_snacks FROM snacks"

We'll get the output:

total_snacks
63

The 🌀 (feed) marker again ingests the snacks data into the dataset, but the 💎 (tap) marker is not processed.

---

We can also mutate data directly. Running:

mdb push "UPDATE snacks SET qty = qty + 20 WHERE name = 'Takis'"

The 🌀 (feed) marker again ingests the snacks data into the dataset, applies the UPDATE, then both 🌀 (feed) and 💎 (tap) markers push fresh results back out.

So then in the updated snacks.md:

## Inventory

`💾 🌀 SELECT * FROM snacks`

| name               | vibe               | qty |
| ------------------ | ------------------ | --- |
| Hot Cheese Popcorn | chaos energy       | 3   |
| Pocky              | elegant simplicity | 12  |
| Takis              | rolled-up danger   | 27  |
| Goldfish           | the people's snack | 41  |

## Low stock

`💾 💎 SELECT name, qty FROM snacks WHERE qty < 10 ORDER BY qty`

| name               | qty |
| ------------------ | --- |
| Hot Cheese Popcorn | 3   |

Takis got restocked to 27 and dropped off the low-stock list — all from a single command.

---

We can also inspect the current landscape of markers. Running:

mdb status

We'll get a snapshot of the available data:

OK   🌀 snacks (3 cols, 4 rows) [snacks.md:5]
OK   💎 SELECT name, qty FROM snacks WHERE qty < 10 ORDER BY qty (2 cols, 2 rows) [snacks.md:15]
Inspected 1 files, 2 markers: 0 problems

🌀 (feed) and 💎 (tap) markers show table dimensions, query text — and any problems (missing tables, conflicts) are flagged.

Agent Support

mdb-cli includes a built-in agent skill. Install it:

mdb init                          # default: .mdb/skills/mdb/SKILL.md
mdb init .claude/skills           # Claude Code: .claude/skills/mdb/SKILL.md
mdb init .opencode/skills         # OpenCode: .opencode/skills/mdb/SKILL.md
mdb init path/to/agent/skills     # any agent: path/to/agent/skills/mdb/SKILL.md

Within a session, invoke the /mdb slash command to access a comprehensive reference covering marker syntax, subcommand workflows, templates for common operations, and an error reference guide. The skill provides everything an AI coding assistant needs to construct and debug mdb markers without leaving the editor.

Configuration

mdb init also generates a .mdbrc configuration file in the project root. Edit it to set project-level defaults for CLI flags (include, compaction, verbose). CLI flags always override .mdbrc values. See CLI Usage for details.