CLI Overview
The refrakt CLI provides tools for generating content, inspecting rune output, auditing themes, and managing your project. Install it alongside your other refrakt.md packages:
npm install @refrakt-md/cli
This makes the refrakt command available in your project scripts and via npx refrakt.
Commands
| Command | Purpose |
|---|---|
| inspect | Preview identity transform output and audit CSS coverage |
| reference | Emit rune syntax reference for human contributors and AI agents |
| write | Generate Markdown content using AI |
| extract | Generate API reference docs from TypeScript or Python source (via @refrakt-md/docs plugin) |
| contracts | Generate and validate structure contracts |
| scaffold-css | Generate CSS stub files for a new theme |
| validate | Validate your project's sites — config resolution, then content |
| format | Indent nested runes by the indentation rule — --check for CI |
stale | Rank documentation references by commits to the target since the page last changed |
migrate snippets | Convert lines= snippet and file-ref invocations to anchors, verifying byte-identical output |
snippet review | Stamp and check review markers on embedded source — --check has its own exit code |
| theme | Install themes, show theme info, and validate theme config and manifest |
| edit | Launch the browser-based content editor |
| plugins list | List installed plugins and their commands |
| plugins validate | Validate a plugin before publishing |
Quick examples
# Preview the HTML output for a rune
refrakt inspect hint --type=warning
# Dump a full rune reference into AGENTS.md
refrakt reference dump
# Generate a docs site with AI
refrakt write -d content/ "Set up a docs site with guides and a blog"
# Generate API reference from source code
refrakt docs extract ./src -o ./content/api
# Audit CSS coverage across all runes
refrakt inspect --all --audit
# Audit metadata dimensions across all runes
refrakt inspect --all --audit-dimensions
# Generate structure contracts for CI
refrakt contracts -o contracts/structures.json --config .
# Rank documentation by how far its subject has moved since the page changed
refrakt stale --top 10
# Launch the content editor
refrakt edit
# Validate a plugin before publishing
refrakt plugins validate ./my-plugin
Plugin commands
Plugins can extend the CLI with additional subcommands. These are available when the plugin is installed.
| Plugin | Command | Purpose |
|---|---|---|
@refrakt-md/docs | refrakt docs extract | Generate API reference docs from TypeScript or Python source |
@refrakt-md/plan | refrakt plan | Project planning — status, next item, update, create, next-id, validate, init, history, migrate |
Run refrakt --help to see all available commands and options.