Metadata-Version: 2.4
Name: dotmd
Version: 0.1.0
Summary: CLI for the mydotmd.io AI rule registry — fetch and share .md instruction files.
Author: dotmd contributors
License: MIT License
        
        Copyright (c) 2024 dotmd contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Homepage, https://mydotmd.io
Project-URL: Repository, https://github.com/dotmd/dotmd-cli
Project-URL: Bug Tracker, https://github.com/dotmd/dotmd-cli/issues
Project-URL: Changelog, https://github.com/dotmd/dotmd-cli/releases
Keywords: dotmd,ai,llm,cursor,claude,copilot,windsurf,rules,instructions,registry,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer[all]>=0.12.0
Requires-Dist: requests>=2.31.0
Requires-Dist: pyfiglet>=1.0.2
Requires-Dist: pillow>=10.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Dynamic: license-file

<div align="center">

# dotmd

**The open `.md` registry CLI**

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

[![PyPI version](https://img.shields.io/pypi/v/dotmd.svg)](https://pypi.org/project/dotmd/)
[![Python versions](https://img.shields.io/pypi/pyversions/dotmd.svg)](https://pypi.org/project/dotmd/)
[![CI](https://github.com/dotmd/dotmd-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/dotmd/dotmd-cli/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

</div>

---

`dotmd` is a command-line tool for the [mydotmd.io](https://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](#install)
- [Quick Start](#quick-start)
- [Commands](#commands)
  - [get](#dotmd-get)
  - [search](#dotmd-search)
  - [list](#dotmd-list)
  - [info](#dotmd-info)
- [Output File Mapping](#output-file-mapping)
- [Configuration](#configuration)
- [LLM & Automation Usage](#llm--automation-usage)
- [Contributing](#contributing)

---

## Install

**Requires Python 3.8+**

```bash
pip install dotmd
```

Verify the install:

```bash
dotmd --version
```

---

## Quick Start

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

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

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

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

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

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

```bash
# 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](https://no-color.org/) convention.

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and pull request guidelines.

---

## License

[MIT](LICENSE) © dotmd contributors
