CLI Reference

The Anvil CLI provides commands for project setup, tool management, and system diagnostics.

Installation

The CLI is installed automatically with the package:

pip install anvil-agent
anvil --help

Global Options

anvil --version  # Show version
anvil --help     # Show help

---

anvil init

Initialize a new Anvil project.

anvil init [OPTIONS]

Options

Option	Short	Default	Description
--dir	-d	.	Directory to initialize.
--tools-dir		anvil_tools	Name of the tools directory.
--force	-f		Overwrite existing files.
--skip-keys			Skip interactive API key setup.

What It Does

1. Creates the tools directory structure
2. Sets up .gitignore to protect API keys
3. Prompts for API keys (optional)
4. Creates a .env file
5. Generates an example script

Examples

# Initialize current directory
anvil init

# Initialize a specific directory
anvil init --dir ./my-project

# Custom tools directory
anvil init --tools-dir my_tools

# Non-interactive mode
anvil init --skip-keys

# Overwrite existing files
anvil init --force

---

anvil doctor

Check system requirements and configuration.

anvil doctor

What It Checks

• Python version (requires 3.10+)
• Docker availability
• API key configuration
• .env file existence
• Tools directory status

Example Output

🩺 System Health Check

┌───────┬─────────────────────────────┬───────────╮
│  ✓    │  Python                     │  3.12.0   │
│  ✓    │  Docker                     │  24.0.7   │
│  ✓    │  Rich CLI                   │  enabled  │
╰───────┴─────────────────────────────┴───────────╯

🔑 API Keys

┌───────┬────────────────────────┬──────────────────────╮
│  ✓    │  ANTHROPIC_API_KEY     │  sk-ant-...1234      │
│  ○    │  FIRECRAWL_API_KEY     │  not set (optional)  │
╰───────┴────────────────────────┴──────────────────────╯

╭──────────────────────────────────────────────────────╮
│ All checks passed!                                   │
╰──────────────────────────────────────────────────────╯

---

anvil list

List all cached tools.

anvil list [OPTIONS]

Options

Option	Short	Default	Description
--dir	-d	./anvil_tools	Tools directory.
--json			Output as JSON.

Examples

# List tools
anvil list

# Custom directory
anvil list --dir ./my_tools

# JSON output (for scripting)
anvil list --json

Example Output

📦 Anvil Tools (3 total)

┌────────┬──────────────────┬─────────┬─────────────────────────────────┐
│ Status │ Name             │ Version │ Intent                          │
├────────┼──────────────────┼─────────┼─────────────────────────────────┤
│   ●    │ search_github    │ v1.0    │ Search GitHub repositories      │
│   ●    │ get_weather      │ v1.2    │ Get current weather for a city  │
│   ○    │ custom_tool      │ v1.0    │ Custom implementation           │
╰────────┴──────────────────┴─────────┴─────────────────────────────────╯

Status Icons

Icon	Meaning
● (green)	Active, working tool
● (red)	Failed tool
○ (yellow)	Ejected (user-controlled)

JSON Output

{
  "tools": [
    {
      "name": "search_github",
      "file": "./anvil_tools/search_github.py",
      "version": "1.0",
      "intent": "Search GitHub repositories",
      "status": "active",
      "size_bytes": 1234,
      "modified": "2025-01-18T10:00:00"
    }
  ]
}

---

anvil clean

Clear the tool cache to force regeneration.

anvil clean [OPTIONS]

Options

Option	Short	Default	Description
--dir	-d	./anvil_tools	Tools directory.
--force	-f		Skip confirmation prompt.
--keep-ejected			Keep user-controlled tools.

What It Does

1. Removes all managed tool files
2. Updates the tool registry
3. Clears __pycache__
4. Optionally preserves ejected tools

Examples

# Interactive confirmation
anvil clean

# Skip confirmation
anvil clean --force

# Keep user-edited tools
anvil clean --keep-ejected

# Clean specific directory
anvil clean --dir ./my_tools --force

Example Output

🧹 Anvil Clean

  Managed tools to remove: 5
    - search_github
    - get_weather
    - send_email
    ... and 2 more

  Ejected tools (keeping): 1

Proceed with cleanup? [y/N]: y
✓ Removed 5 tools.
ℹ Tools will be regenerated on next use.

---

anvil verify

Verify a tool’s code in the sandbox.

anvil verify <TOOL_NAME> [OPTIONS]

Arguments

Argument	Description
TOOL_NAME	Name of the tool to verify.

Options

Option	Short	Default	Description
--dir	-d	./anvil_tools	Tools directory.

What It Does

1. Loads the tool’s source code
2. Runs static security analysis
3. Executes in sandbox (if Docker available)
4. Reports violations or success

Examples

# Verify a tool
anvil verify search_github

# Verify tool in custom directory
anvil verify my_tool --dir ./custom_tools

Example Output (Success)

🔍 Verifying: search_github

  Sandbox: docker

✓ Code passed verification!
  Duration: 45.2ms

Example Output (Failure)

🔍 Verifying: dangerous_tool

  Sandbox: docker

✗ Code failed verification!

  Error: Security violation detected

  Security violations:
    - Blocked import: subprocess
    - Dangerous function call: os.system

---

Exit Codes

Code	Meaning
0	Success
1	Error or verification failure

Environment Variables

The CLI respects these environment variables:

Variable	Description
ANTHROPIC_API_KEY	Anthropic API key
OPENAI_API_KEY	OpenAI API key
XAI_API_KEY	Grok API key
FIRECRAWL_API_KEY	FireCrawl API key

See Also

• Installation Guide
• Quick Start
• Configuration Reference