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 theme config and manifest |
| theme | Install themes and show theme info |
| 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 .
# 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, validate, serve, build |
Run refrakt --help to see all available commands and options.