---
id: doccmd
version: "2026.7.19"
license: MIT
license_treatment: permissive
maintenance: active
---

# doccmd — Run commands against code blocks in reStructuredText and Markdown files.

License: permissive · Maintenance: active · Downloads: 176.0K/mo

## What it is and what it does

doccmd is a command-line tool that extracts code blocks from documentation files and runs external commands (linters, formatters, type checkers) against them. It works with reStructuredText, Markdown, MyST, MDX, Djot, and Norg files, automatically handling language detection and code block extraction so you can validate that the code examples in your documentation actually work and conform to your project's standards.

The tool preserves line numbers in error output by padding code blocks before execution, and can strip Python REPL prompts (>>>) when processing interactive console examples. It's designed to integrate into CI/CD pipelines and pre-commit hooks, letting you catch broken or outdated code examples before they reach users. Dependencies include click for CLI scaffolding, beartype for runtime type validation, and dulwich for version control operations.

Use it for:

- Validate that Python code examples in your README actually pass type checking with mypy or ruff.
- Ensure shell script snippets in documentation pass linting tools like shellcheck before release.
- Run formatters (ruff format, gofmt) on code blocks to keep examples style-consistent with your codebase.
- Test interactive Python sessions (pycon blocks) by stripping prompts, running linters, and restoring them.
- Integrate into pre-commit hooks to catch broken documentation examples on every commit.
- Verify code blocks across multiple documentation formats (Sphinx, MyST, plain Markdown) in a single pass.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Runs linters, formatters, and other command-line tools against code blocks embedded in documentation files (reStructuredText, Markdown, MyST, MDX, Djot, Norg).

Yes. The package is actively maintained, has no known vulnerabilities, uses a permissive MIT license, and solves a real problem—keeping documentation code examples in sync with your actual codebase standards. Low install friction and broad format support make it a practical choice for projects that care about documentation quality. Install it if you maintain documentation with embedded code examples and want automated validation.

## Install

pip install doccmd
uv add doccmd
poetry add doccmd

## Installing doccmd

Before you install: Low friction: pure Python wheel with 9 runtime dependencies including click for CLI, beartype for type checking, and dulwich for version control integration. Active maintenance with a release 26 days ago; repository has 28 stars and recent commits.

License in practice: MIT license (permissive): you can use, modify, and distribute this package freely in commercial and private projects with minimal restrictions.

Quickstart:

$ pip install doccmd
$ doccmd --language=python --command="mypy" README.md
$ doccmd --language=shell --command="shellcheck --shell=bash" docs/

Requires Python 3.11 or later; the command-line tool being invoked (e.g., mypy, shellcheck) must be installed separately and available in PATH.

Verify before relying:

- Whether the tool handles nested or indented code blocks correctly across all supported formats.
- Performance characteristics when processing large documentation files with many code blocks.
- Compatibility with custom or non-standard code block syntax extensions.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 176.0K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

lint code blocks in documentation, run formatters on markdown rst, test code examples in docs, documentation code validation, embedded code block checker, sphinx documentation testing, validate code snippets, documentation-testing, code-validation, cli-tool

[View on SkillFed](https://skillfed.io/packages/doccmd) · [View on PyPI](https://pypi.org/project/doccmd/)