Metadata-Version: 2.4
Name: mdb-cli
Version: 0.1.0
Summary: Markdown table workflows w/ SQLite powers ✨
Project-URL: Homepage, https://atomanoid.github.io/mdb/
Project-URL: Repository, https://github.com/atomanoid/mdb
Project-URL: Documentation, https://atomanoid.github.io/mdb/
Author: atomanoid
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Text Processing :: Markup :: Markdown
Classifier: Typing :: Typed
Requires-Python: >=3.11
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
Description-Content-Type: text/markdown

<p align="center">
  <!-- <img src="https://raw.githubusercontent.com/atomanoid/mdb/main/docs/assets/floppy.svg" alt="floppy disk" width="128"> -->
  <img src="https://raw.githubusercontent.com/gist/atomanoid/2e8135956d498969842907b1b149c72f/raw/f9d3aa40f4ebf7b347de617263ac1c7492bd6203/mdb-floppy.svg" alt="floppy disk" width="128">

</p>

<h1 align="center"><code>mdb-cli</code></h1>

<h3 align="center">Markdown table workflows w/ SQLite powers ✨</h3>

`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](https://pypi.org/project/mdb-cli/):

```bash
# 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:

```bash
mdb --help
```

For development installation, see [CONTRIBUTING.md](https://github.com/atomanoid/mdb/blob/main/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:

```markdown
# 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:

```bash
mdb push
```

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

```markdown
# 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:

```bash
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:

```bash
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:

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