• 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
• Creating Custom Domains
• Architecture
• Advanced Usage
• Why Craft CLI?
• Contributing

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

mkdir -p domains/mytools/tools

# domains/mytools/config.yaml
name: "My Custom Tools"
description: "Tools for my specific workflow"
base_path: "/path/to/my/scripts"

# domains/mytools/tools/mytool.yaml
name: "MYTOOL"
description: "What my tool does"
command: "python {base_path}/mytool.py {args}"
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

domains/
├── linting/
│   ├── config.yaml
│   └── tools/
│       ├── ruff.yaml
│       ├── black.yaml
│       └── mypy.yaml
├── coding/
│   ├── config.yaml
│   └── tools/
│       ├── test.yaml
│       ├── build.yaml
│       └── git.yaml
└── mytools/
    ├── config.yaml
    └── tools/
        └── mytool.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 domain directories in:

1. Current working directory
2. Parent directories (walks up the tree)
3. Package installation location

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/slate-tui/craft-cli
• Issue Tracker: https://github.com/slate-tui/craft-cli/issues

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