dotmd 0.1.0

CLI for the mydotmd.io AI rule registry — fetch and share .md instruction files.

dotmd

The open .md registry CLI

Fetch and share the AI instruction files that power your coding assistants.

---

dotmd is a command-line tool for the mydotmd.io registry — like Docker Hub, but for .md instruction files. Browse, search, and pull the rules that configure AI coding assistants like Cursor, Claude, Windsurf, Copilot, and more.

╭──────────────────────────────────────────────────────────────────────╮
│   ____        _                    _                                 │
│  |  _ \  ___ | |_  _ __ ___   __| |                                  │
│  | | | |/ _ \| __|| '_ ` _ \ / _` |                                  │
│  | |_| | (_) | |_ | | | | | | (_| |                                  │
│  |____/ \___/ \__||_| |_| |_|\__,_|                                  │
│                                                                      │
│  Share your .md instruction files.                                   │
╰──────────────────────────────────────────────────────────────────────╯

---

Table of Contents

• Install
• Quick Start
• Commands
  • get
  • search
  • list
  • info
• Output File Mapping
• Configuration
• LLM & Automation Usage
• Contributing

---

Install

Requires Python 3.8+

pip install dotmd

Verify the install:

dotmd --version

---

Quick Start

# Browse what's available
dotmd list

# Search by keyword
dotmd search react typescript

# Fetch a rule into your project
dotmd get dotmd/react-best-practices

# See where it was written
dotmd info

---

Commands

dotmd get

Fetch a rule from the registry and write it to the correct local instruction file for your AI tool.

# Full slug: <username>/<title>
dotmd get dotmd/react-best-practices

# Bare title — auto-resolved when only one match exists
dotmd get react-best-practices

# Explicit username with bare title
dotmd get react-best-practices --username dotmd

# Preview destination without writing (dry run)
dotmd get dotmd/react-best-practices --dry-run

# Write to a custom path
dotmd get dotmd/react-best-practices --output .cursorrules

# Overwrite an existing file
dotmd get dotmd/react-best-practices --force

# Suppress all output (useful in scripts)
dotmd get dotmd/react-best-practices --quiet

# Machine-readable JSON output
dotmd get dotmd/react-best-practices --json

Options:

Flag	Short	Description
--username USER	-u	Registry username (use with bare title)
--output PATH	-o	Write to a specific path instead of the default
--force	-f	Overwrite destination if it already exists
--dry-run		Preview destination without writing
--quiet	-q	Suppress non-error output
--json		Emit JSON to stdout

---

dotmd search

Search the registry for rules by keyword. Matches against rule titles.

# Single keyword
dotmd search python

# Multiple keywords (AND match)
dotmd search react typescript performance

# Limit results
dotmd search react --limit 5

# JSON output for scripting
dotmd search react --json

Options:

Flag	Short	Description
--limit N	-n	Max results (default: 20, max: 100)
--json		Emit JSON to stdout

---

dotmd list

List rules for a specific user, or all public rules in the registry.

# All public rules
dotmd list

# Rules for a specific user
dotmd list dotmd

# Limit results
dotmd list --limit 50

# JSON output
dotmd list dotmd --json

Options:

Flag	Short	Description
--limit N	-n	Max results (default: 100, max: 200)
--json		Emit JSON to stdout

---

dotmd info

Show version, registry details, supported formats, and configuration.

dotmd info

# Skip the ASCII art banner
dotmd info --plain

# JSON output
dotmd info --json

---

Output File Mapping

When you run dotmd get, the rule is written to the standard location for its format type:

Format	Written to
claude.md	CLAUDE.md
cursorrules	.cursorrules
windsurfrules	.windsurfrules
agents.md	AGENTS.md
copilot	.github/copilot-instructions.md
gemini	GEMINI.md
cline	.clinerules
aider	.aider.conf.yml
continue	.continue/config.json

Use --output PATH to override the destination for any rule.

---

Configuration

dotmd works out of the box with no configuration. If your deployment requires authentication, set these environment variables:

# Supabase anon key (required for authenticated registries)
export DOTMD_SUPABASE_ANON_KEY="your-supabase-anon-key"

# Override the Supabase REST base URL (optional)
export DOTMD_SUPABASE_BASE_URL="https://your-project-ref.supabase.co/rest/v1"

# Aliases
export DOTMD_API_KEY="..."          # alias for DOTMD_SUPABASE_ANON_KEY
export DOTMD_BASE_URL="..."         # alias for DOTMD_SUPABASE_BASE_URL

# Disable color output (follows https://no-color.org/)
export NO_COLOR=1

Auto-discovery: If the default endpoint fails, dotmd automatically attempts to discover the current Supabase REST URL and anon key from https://mydotmd.io and retries.

---

LLM & Automation Usage

dotmd is designed to work cleanly in automated pipelines and as a tool for AI agents:

Pipe-friendly: When stdout is not a TTY (piped, redirected, or called by an LLM), the ASCII art banner is automatically suppressed and only plain text is emitted.

JSON output: Every command supports --json for structured, machine-readable output:

# Get a rule and parse the result
dotmd get dotmd/react-best-practices --json | jq .destination

# Search and pipe to another tool
dotmd search react --json | jq '.results[].title'

# Dry run to check destination before writing
dotmd get dotmd/react-best-practices --dry-run --json

Exit codes:

Code	Meaning
0	Success
1	API or network error
2	Usage error (bad arguments, file exists without --force, ambiguous title)
130	Interrupted (Ctrl+C)

NO_COLOR support: Set NO_COLOR=1 to disable all ANSI color codes, following the no-color.org convention.

---

Contributing

See CONTRIBUTING.md for development setup, testing, and pull request guidelines.

---

License

MIT © dotmd contributors