# dotmd

> The open registry for AI agent best practices.

dotmd is a community platform where developers discover, share, and manage .md instruction files that power AI coding assistants. Think of it as Docker Hub, but for AI rules.

## What dotmd does

- Browse and search community-shared .md instruction files for any framework or workflow
- Download instruction files in multiple formats for all major AI coding assistants
- Star, comment, and fork community contributions
- Version history tracking for all instruction files
- Enterprise-verified rules from organizations like IBM
- Official curated best practices from the dotmd team

## Supported AI Coding Assistants

- **Cursor** — uses `.cursorrules` files
- **Claude Code** — uses `CLAUDE.md` files
- **OpenAI Codex / Agents** — uses `AGENTS.md` files
- **Windsurf** — uses `.windsurfrules` files
- **GitHub Copilot** — uses `.github/copilot-instructions.md` files
- **Google Gemini** — uses `GEMINI.md` files
- **Cline** — uses `.clinerules` files
- **Aider** — uses `.aider.conf.yml` files
- **Continue** — uses `.continue/config.json` files
- **Generic** — uses `rules.md` files

## How to use

1. **Find** — Browse or search for instruction files by framework, language, or workflow at https://mydotmd.io/browse
2. **Copy** — Copy or download the file in your preferred format
3. **Drop** — Place the file in your project root. Your AI assistant follows the instructions automatically.

Alternatively, use the CLI:

```
pip install dotmd
dotmd get <username>/<title>
```

## Key features

- Free and open to all developers
- Official verified files from the dotmd team
- Enterprise files from verified organizations (e.g., IBM)
- Community commenting and starring
- Multi-format download support
- Version history for every rule file
- CLI for terminal-based workflows
- LLM-friendly structured data and documentation

## CLI

dotmd has an official command-line tool for pulling files directly into your project from the terminal.

- Install: `pip install dotmd`
- PyPI: https://pypi.org/project/dotmd/
- GitHub: https://github.com/dotmd-cli/dotmd-cli
- License: MIT

### Commands

- `dotmd get <username>/<title>` — Download a file and save it to the correct location for its format
- `dotmd search <keyword>` — Search the registry by keyword (matches titles)
- `dotmd list [username]` — List public files, optionally filtered by user
- `dotmd info` — Show version, registry details, and supported formats

### Common flags

- `--output PATH` / `-o` — Write to a custom path instead of the default
- `--force` / `-f` — Overwrite if the destination already exists
- `--dry-run` — Preview destination without writing
- `--quiet` / `-q` — Suppress non-error output
- `--json` — Machine-readable JSON output (works with all commands)
- `--username USER` / `-u` — Specify registry username (use with bare title)

### Output file mapping

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

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

### LLM & automation usage

dotmd is designed for automated pipelines and AI agents:
- Pipe-friendly: ASCII banner is suppressed when stdout is not a TTY
- JSON output: every command supports `--json` for structured output
- Exit codes: 0 (success), 1 (API/network error), 2 (usage error), 130 (interrupted)
- Supports `NO_COLOR=1` to disable ANSI codes

## API Access

The dotmd registry data is accessible through the public API. AI agents and tools can:
- Search files by keyword
- List files by user or popularity
- Retrieve file content in any supported format
- Access metadata including stars, tags, and version history

## Links

- Homepage: https://mydotmd.io
- Browse files: https://mydotmd.io/browse
- Documentation: https://mydotmd.io/docs
- Pricing: https://mydotmd.io/pricing
- Sign up: https://mydotmd.io/signup
- CLI (PyPI): https://pypi.org/project/dotmd/
- CLI (GitHub): https://github.com/dotmd-cli/dotmd-cli
- LLM documentation: https://mydotmd.io/llms.txt
- LLM documentation (well-known): https://mydotmd.io/.well-known/llms.txt