• Installation
• What Actually Happens
• How AI Agents Discover and Use Tools
• How Tools Are Configured
• Fire Up Specialized Agents for Any Task
• The Problem
• The Solution
• Quick Start
• Built-in Domains
• Key Features
• Configuration System
• Architecture
• Advanced Usage
• Why Craft CLI?
• Contributing

# If using UV (recommended)
uv add craft-cli

# If using pip
pip install craft-cli

# Install globally with UV
uv tool install craft-cli

# Then use anywhere
craft --help

# For the bleeding edge
uv add git+https://github.com/bwl/craft.git

# Or with pip
pip install git+https://github.com/bwl/craft.git

# Verify installation
craft --version

# See what's available
craft --domains

# Try the human-friendly interface
craft --help --noob

Example 1: Deploy a Writing Assistant

$ craft slate namer character --type=protagonist --culture=nordic

→ Smart agent generates 5 culturally appropriate Nordic protagonist names with context and meaning

Example 2: Fire Up a Code Quality Expert

$ craft linting ruff check --fix src/

→ Linting specialist scans your code, finds 23 issues, automatically fixes 19 of them, reports the 4 that need manual attention

Example 3: Summon a Test Engineer

$ craft coding test --coverage

→ Testing expert runs your full test suite, generates coverage report, identifies untested code paths

When Claude (or any AI agent) needs to accomplish something, they can:

1. Explore domains: ./craft --domains shows all available specialist areas
2. Scope by domain: ./craft linting lists only code quality tools
3. Get help: ./craft linting ruff --help explains exactly what each tool does
4. Execute with confidence: ./craft linting ruff check --fix - the system takes over from there

The AI agent just runs ./craft and the framework handles discovery, validation, and execution. No complex tool management needed.

Each tool is defined by a simple YAML file that tells the system:

Example: domains/linting/tools/ruff.yaml

name: "RUFF"
description: "Fast Python linter and code formatter, written in Rust"
command: "uv run ruff check {args}"
help: |
  Usage: craft linting ruff [options] [path]
  
  Options:
    --fix          Automatically fix violations
    --watch        Run in watch mode
    
  Examples:
    craft linting ruff check --fix src/
    craft linting ruff check . --watch

What this means:

• name & description: What the AI agent sees when exploring tools
• command: The actual command that gets executed (with argument substitution)
• help: Context-aware help that explains usage and provides examples

The framework handles all the plumbing - argument passing, error handling, output formatting. You just define what the specialist should do.

⚠️ Friendly Disclaimer: Most of the features promised below exist but some um... we will get back to you soon, dw 😅

Transform any specialized workflow into intelligent, agent-ready commands.

Stop context-switching between tools. Stop explaining your domain knowledge over and over. Craft CLI lets you deploy domain experts instantly - whether that's a coding specialist, a linting expert, or a creative writing assistant.

Every craft command is really saying: "Hey, someone smart who understands this domain - handle this for me."

Domain-specific tools often have great functionality but poor adoption because they:

• Feel like "extra steps" outside normal workflow
• Are easy to forget when focused on other tasks
• Lack integration with existing command-line habits
• Don't provide immediate feedback and guidance

Craft CLI makes domain tools feel like system commands (git, npm, docker) by providing:

• Natural CLI integration - craft linting ruff check --fix
• Rich feedback - Beautiful tables and panels using Rich library
• Contextual help - craft linting ruff --help shows tool-specific guidance
• Tool discovery - craft linting lists all available tools in domain
• AI-optimized output - Clean, parseable default output for agents
• Human-friendly mode - --noob flag for Rich UI when humans need it

# Install from PyPI
uv tool install craft-cli

# Or with pip
pip install craft-cli

# Show help
craft --help

# List available domains  
craft --domains

# List tools in a domain
craft linting

# Run a tool
craft linting ruff check --fix

# Get tool-specific help
craft linting ruff --help

# Use human-friendly Rich UI
craft linting --noob

craft linting ruff check --fix        # "Fix all the issues you find"
craft linting black .                 # "Format this code properly"
craft linting mypy src/               # "Check types thoroughly"

craft coding test --coverage          # "Run comprehensive tests"
craft coding build sync --dev         # "Handle my dependencies"
craft coding git status               # "Show me what's changed"

craft slate namer character --type=protagonist    # "Generate perfect character names"
craft slate embark "New Series" --genre=fantasy   # "Set up my novel project"

$ craft linting
PYTHON CODE QUALITY TOOLS TOOLS:
  RUFF: Fast Python linter and code formatter, written in Rust
    Usage: craft linting ruff check .
  BLACK: The uncompromising Python code formatter  
    Usage: craft linting black .
  MYPY: Static type checker for Python
    Usage: craft linting mypy src/

Use: craft linting <tool> --help for tool-specific help
Add --noob flag for Rich UI tables

Beautiful tables, panels, and colors when humans need visual interface:

craft linting --noob

Craft CLI includes built-in domains and supports custom domain paths via configuration files.

Craft CLI comes with these domains out of the box:

• linting: Python code quality tools (ruff, black, mypy)
• coding: Development tools (test, build, git)
• slate: Novel writing tools (embark, namer)

Create .craftrc files to add your own domain paths:

Project-level (./.craftrc):

domain_paths:
  - "./my-project-tools"
  - "./scripts/craft-domains"

config:
  default_human_mode: true

User-level (~/.config/craft/craftrc):

domain_paths:
  - "~/my-craft-domains"
  - "/opt/shared-craft-tools"

include_builtin_domains: true  # Default: true

mkdir -p ~/my-craft-domains/mytools

# ~/my-craft-domains/mytools/mytool.yaml
name: "MYTOOL"
description: "What my tool does"
command: "python mytool.py {args}"
category: "utilities"
help: |
  Usage: craft mytools mytool [options]
  Examples:
    craft mytools mytool --option=value

craft mytools                    # List your tools
craft mytools mytool --help      # Tool help
craft mytools mytool --verbose   # Run your tool

When domains have the same name:

1. Project-level domains (from ./.craftrc)
2. User-level domains (from ~/.config/craft/craftrc)
3. Built-in domains (from package)

On first run, Craft CLI will offer to create an example config:

🚀 Welcome to Craft CLI!
No configuration found. Would you like to create an example config?
This will create ~/.config/craft/craftrc with sensible defaults.
Create example config? (y/N): 

craft-cli package includes:
src/craft_cli/domains/
├── linting/
│   ├── ruff.yaml
│   ├── black.yaml
│   └── mypy.yaml
├── coding/
│   ├── test.yaml
│   ├── build.yaml
│   └── git.yaml
└── slate/
    ├── embark.yaml
    └── namer.yaml

User domains can be anywhere:
~/my-craft-domains/
├── mytools/
│   ├── tool1.yaml
│   └── tool2.yaml
└── devops/
    ├── deploy.yaml
    └── monitor.yaml

name: "TOOL-NAME"
description: "Brief description"
command: "actual-command {args}"
category: "tool_category"
help: |
  Detailed help text with usage examples

Craft CLI automatically finds domains from:

1. Built-in domains (included with package)
2. Project-level config (./.craftrc in current directory)
3. User-level config (~/.config/craft/craftrc)

Domain paths are merged with project-level taking precedence over user-level over built-in.

craft <domain>                    # List domain tools
craft <domain> <tool> [args]      # Run tool with arguments
craft <domain> <tool> --help      # Tool-specific help
craft --domains                   # List all domains
craft --help [--noob]            # Framework help
craft --version                   # Show version

• --noob - Enable Rich UI (tables, panels, colors)
• --verbose - Show command being executed
• --help - Context-sensitive help

• Clean, parseable output - No fluff, just actionable results
• Domain expertise on-demand - Every command taps specialized knowledge
• Natural integration - Works with existing agent workflows seamlessly
• Zero context-switching - The tool understands your domain

• Rich UI option - Beautiful tables and panels when you need them
• Instant expertise - No need to remember complex tool syntax
• Self-documenting - Help and examples built into every command
• Consistent patterns - Learn once, use everywhere

• Unified interface - All domain tools follow the same patterns
• Easy onboarding - New team members get productive immediately
• Extensible architecture - Add new domains without changing the framework
• Built-in documentation - Every tool comes with usage examples

We welcome contributions! See CONTRIBUTING.md for guidelines.

1. Create domain directory structure
2. Add domain config and tool definitions
3. Test with craft your-domain
4. Submit pull request with documentation

• GitHub Issues for bugs and feature requests
• Include domain, tool, and command that caused the issue
• Provide expected vs actual behavior

MIT License - see LICENSE for details.

• Documentation: https://craft-cli.readthedocs.io
• PyPI Package: https://pypi.org/project/craft-cli/
• Source Code: https://github.com/bwl/craft
• Issue Tracker: https://github.com/bwl/craft/issues

Built with ❤️ for AI agents and human developers who want their specialized tools to feel like system commands.