█████╗ ███╗ ██╗██╗ ██╗██╗██╗
██╔══██╗████╗ ██║██║ ██║██║██║
███████║██╔██╗ ██║██║ ██║██║██║
██╔══██║██║╚██╗██║╚██╗ ██╔╝██║██║
██║ ██║██║ ╚████║ ╚████╔╝ ██║███████╗
╚═╝ ╚═╝╚═╝ ╚═══╝ ╚═══╝ ╚═╝╚══════╝
# Anvil CLI
[](https://github.com/yourusername/anvil-cli/actions)
[](https://badge.fury.io/py/anvil-cli)
[](https://www.python.org/downloads/)
[](https://github.com/astral-sh/ruff)
[](https://opensource.org/licenses/MIT)
A powerful CLI tool for creative development workflows. Anvil provides essential utilities for designers and developers, with an extensible plugin architecture.
## ✨ Features
- 🎨 **Color Palette Extraction** - Extract color palettes from any image
- 🎭 **Creative Sketching** - Generate creative content from text prompts
- 🔌 **Plugin Architecture** - Extensible with custom and third-party plugins
- 💾 **Smart Caching** - SQLite-based caching for performance
- 🎯 **Rich CLI Experience** - Beautiful output with colors and emojis
- ⚡ **Fast & Reliable** - Built with modern Python and comprehensive testing
## 🚀 Quick Start
### Installation
Install anvil using pipx (recommended):
```bash
pipx install anvil-cli
Or using pip:
pip install anvil-clianvil --helpYou should see the beautiful ASCII logo and help information!
Anvil features a powerful interactive REPL (Read-Eval-Print Loop) that provides a Claude Code-style shell experience.
Run anvil without any arguments to launch the interactive shell:
anvilOr use the dedicated shell command:
anvil-shell┌─────────────────────────────────────────────────────────────┐
│ Welcome to anvilCLI! │
│ │
│ /help for help, /status for your current setup │
│ │
│ cwd: /Users/you/projects │
└─────────────────────────────────────────────────────────────┘
* Tip: Start with small features or bug fixes, ask Anvil to propose a plan, and verify its suggested edits *
>
Available slash commands:
/help,?- Show help message/status- Display current working directory and Python version/exit,/quit- Exit the shell
Regular commands: Any other input is forwarded to the normal anvil CLI, so you can run commands like:
> sketch "modern login page"
> palette grab image.jpg
> versionThe REPL keeps running after each command, making it perfect for iterative workflows and experimentation.
The sketch command uses v0's API to generate modern web applications from text prompts.
You have several convenient ways to set your v0 API key:
Option 1: Global Configuration (Recommended)
# Get your API key from v0.dev
anvil sketch config --set-key YOUR_V0_API_KEY --globalThis saves your key to ~/.anvil/.env and works for all projects.
Option 2: Project-specific Configuration
# Set for current project only
anvil sketch config --set-key YOUR_V0_API_KEYThis creates a .env file in your current directory.
Option 3: Manual .env File
Create a .env file in your project or home directory:
# In your project directory
echo "V0_API_KEY=YOUR_V0_API_KEY" > .env
# Or globally at ~/.anvil/.env
mkdir -p ~/.anvil
echo "V0_API_KEY=YOUR_V0_API_KEY" > ~/.anvil/.envOption 4: Environment Variable (Temporary)
export V0_API_KEY=YOUR_V0_API_KEYCheck Your Configuration
anvil sketch config --showBasic usage:
anvil sketch create "Create a Next.js todo app with dark mode"Preview only (don't create files):
anvil sketch create "Build a React dashboard with charts" --no-files- Streaming responses: See the AI response in real-time as it's generated
- Automatic file creation: Parses code blocks and creates files in your current directory
- Smart file detection: Automatically detects file types and names based on content
- Multiple formats: Supports v0's
file="filename"format and other common formats - Rich terminal output: Beautiful, colored output with progress indicators
# Create a simple website
anvil sketch create "Build a landing page for a coffee shop with hero section, menu, and contact form"
# Generate a React component
anvil sketch create "Create a reusable button component in React with TypeScript"
# Build a full-stack app
anvil sketch create "Make a Next.js blog with authentication and a CMS"
# Generate utility functions
anvil sketch create "Create Python utility functions for data processing"
# Analyze existing codebase for improvements
anvil sketch doctor
# Analyze specific project directory
anvil sketch doctor ./my-react-appThe command will:
- 🚀 Call the v0 API with your prompt
- 📺 Stream the response in real-time in your terminal
- 📁 Parse any code blocks from the response
- ✅ Create the appropriate files in your current directory
Anvil automatically recognizes and parses multiple code block formats:
v0 Format (Primary):
```tsx file="app/page.tsx"
export default function Home() {
return <div>Hello World</div>
}
```
Colon Format:
```tsx:components/Button.tsx
export default function Button() {
return <button>Click me</button>
}
```
Direct Filename:
```styles.css
body { margin: 0; }
```
All formats will create the appropriate directory structure and files automatically.
The doctor command analyzes your existing codebase and provides improvement suggestions:
# Analyze current directory
anvil sketch doctor
# Analyze specific directory
anvil sketch doctor /path/to/project
# Get analysis without the full output (summary only)
anvil sketch doctor --no-analysisWhat it does:
- 🔍 Scans your project files (automatically excludes node_modules, .git, etc.)
- 📊 Sends your codebase to v0 for analysis
- 💡 Receives detailed suggestions for improvements, best practices, and optimizations
- 🎯 Identifies potential issues, code smells, and enhancement opportunities
Supported file types:
- Python (.py), JavaScript/TypeScript (.js, .jsx, .ts, .tsx)
- Styles (.css, .scss, .sass, .less)
- Markup (.html, .vue, .svelte)
- Config (.json, .yaml, .toml, .md)
- And many more...
Example output:
- Code quality improvements
- Security recommendations
- Performance optimizations
- Architecture suggestions
- Best practices compliance
Extract color palettes from images:
# Extract colors from an image
anvil palette grab ./path/to/image.jpg
# Works with various formats (PNG, JPG, GIF, etc.)
anvil palette grab screenshot.pngOutput:
🎨 Extracting colors from: ./path/to/image.jpg
🌈 Extracted colors:
[
"#ff6b35",
"#2c5aa0",
"#ffffff",
"#1a1a1a",
"#f5f5f5"
]
✓ Saved palette to: ./path/to/image_palette.json
Keep anvil up to date:
anvil upgrade--version- Show version and exit--verbose,-v- Enable verbose output--no-color- Disable colored output
Anvil supports both built-in and third-party plugins through a simple registration system.
Create a file in anvil/plugins/your_plugin.py:
"""Your custom plugin."""
import typer
from rich.console import Console
console = Console()
def register(main_app: typer.Typer) -> None:
"""Register the plugin with the main CLI app."""
plugin_app = typer.Typer(name="your-plugin", help="Your plugin description")
@plugin_app.command()
def hello(name: str = "World") -> None:
"""Say hello from your plugin."""
console.print(f"[green]👋 Hello {name} from your plugin![/green]")
main_app.add_typer(plugin_app, name="your-plugin")Distribute your plugin as a separate package with entry points in pyproject.toml:
[tool.poetry.plugins."anvil.plugins"]
my_awesome_plugin = "my_package.plugin:register"Your plugin module should export a register function:
# my_package/plugin.py
import typer
def register(main_app: typer.Typer) -> None:
"""Register your plugin commands."""
# Add your commands here
pass- Development Tools: Code formatters, linters, generators
- Design Utilities: Image processors, color tools, font managers
- Project Management: Template generators, deployment tools
- Creative Tools: AI integrations, content generators
- Python 3.10+
- Poetry
# Clone the repository
git clone https://github.com/yourusername/anvil-cli.git
cd anvil-cli
# Install dependencies
poetry install
# Activate virtual environment
poetry shell
# Run tests
pytest
# Run linting
ruff check .
# Run type checking
mypy anvil
# Test the CLI
anvil --helpBefore submitting changes, ensure:
pytestpasses with ≥90% coverageruff check .andruff format .passmypy anvilpasses with strict checking
anvil-cli/
├── anvil/
│ ├── __init__.py # Package metadata
│ ├── cli.py # Main CLI entry point
│ ├── cache.py # SQLite caching layer
│ ├── py.typed # Type hint marker
│ ├── commands/ # Built-in commands
│ │ ├── __init__.py
│ │ ├── sketch.py # Sketch command
│ │ └── palette.py # Palette command
│ └── plugins/ # Plugin system
│ ├── __init__.py
│ └── example.py # Example plugin
├── tests/ # Test suite
├── .github/workflows/ # CI/CD
├── pyproject.toml # Project configuration
└── README.md # Documentation
We welcome contributions! Here's how to get started:
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes and add tests
- Ensure all quality gates pass
- Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Submit a Pull Request
- Follow the existing code style (enforced by ruff)
- Add tests for new functionality
- Update documentation as needed
- Ensure backwards compatibility
- Write clear, descriptive commit messages
Please use the GitHub Issues page to report bugs or request features.
This project is licensed under the MIT License - see the LICENSE file for details.
- Built with Typer for the CLI framework
- Rich for beautiful terminal output
- Pillow for image processing
- ASCII art generated with inspiration from figlet
Anvil provides flexible API key management for v0 integration:
# Set API key globally (works for all projects)
anvil sketch config --set-key YOUR_KEY --global
# Set API key for current project only
anvil sketch config --set-key YOUR_KEY
# Check current API key status
anvil sketch config --show
# See all configuration options
anvil sketch config --helpAnvil looks for your API key in this order:
- Current directory
.envfile - Project-specific - Global
~/.anvil/.envfile - User-wide settings - Environment variable
V0_API_KEY- Session-specific
- For development: Use global configuration (
--global) for convenience - For teams: Use project-specific
.envfiles and add.envto.gitignore - For CI/CD: Use environment variables
- Security: Never commit API keys to version control
V0_API_KEY: Your v0 API key (required for sketch command)
Happy building with Anvil! 🔨✨