mdb-cli 0.1.0

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 ingested into SQLite backing databases on which SQL queries are actually run.

Subcommands

Subcommand	Behavior
mdb pull <sql-query>	process all 🌀 markers first (pulls), then outputs SQL query results in CSV format
mdb push	process all 🌀 markers first (pulls), then all 💎 markers after (pushes)
mdb push <sql-mutation>	process all 🌀 markers first (pulls), execute the mutation, then all 🌀 and 💎 markers after (pushes)

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:

## 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.

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.