Carp CLI

Command-line tool for the Claude Agent Registry Portal (Carp).

Features

• Search Agents: Find agents in the registry with powerful search functionality
• Pull Agents: Download and extract agents locally for use
• Publish Agents: Package and upload your agents to the registry
• Create Templates: Generate new agent projects with built-in templates

Installation

From Source

git clone https://github.com/refcell/carp
cd carp
just build-cli

The binary will be available at cli/target/release/carp.

From Crates.io (Coming Soon)

cargo install carp-cli

Usage

Search for Agents

# Basic search
carp search "text processing"

# Limit results
carp search "claude" --limit 5

# Exact match only
carp search "my-agent" --exact

Pull an Agent

# Pull latest version
carp pull agent-name

# Pull specific version
carp pull agent-name@1.2.0

# Pull to specific directory
carp pull agent-name --output ./my-agents/

# Force overwrite existing directory
carp pull agent-name --force

Create a New Agent

# Create basic agent template
carp new my-agent

# Create with specific template
carp new my-agent --template python

# Create in specific directory
carp new my-agent --path ./projects/my-agent

# Available templates: basic, advanced, python

Publish an Agent

# Publish from current directory (requires Carp.toml)
carp publish

# Publish with specific manifest
carp publish --manifest ./path/to/Carp.toml

# Dry run (validate without publishing)
carp publish --dry-run

# Skip confirmation prompts
carp publish --yes

Configuration

Configuration is stored in ~/.config/carp/config.toml:

registry_url = "https://api.carp.refcell.org"
api_token = "your-api-token"
timeout = 30
verify_ssl = true
default_output_dir = "/path/to/agents"

Agent Manifest (Carp.toml)

name = "my-agent"
version = "1.0.0"
description = "A Claude AI agent that does amazing things"
author = "Your Name <your.email@example.com>"
license = "MIT"
homepage = "https://github.com/username/my-agent"
repository = "https://github.com/username/my-agent"
tags = ["claude", "ai", "automation"]

files = [
    "README.md",
    "agent.py",
    "config.toml",
    "src/"
]

main = "agent.py"

[dependencies]
# Optional: dependencies on other agents
# other-agent = "1.0.0"

Development

Building

just build-cli

Testing

just test-cli

Linting

just lint-cli

Formatting

just fmt-cli

Security

The Carp CLI includes several security features:

• Secure Config Storage: API tokens stored with restricted file permissions (600)
• Path Traversal Protection: ZIP extraction validates paths to prevent directory traversal
• HTTPS by Default: All network requests use HTTPS
• URL Validation: Registry URLs are validated for format and security
• Input Validation: All user inputs are validated and sanitized

Architecture

The CLI is built with a modular architecture:

src/
├── main.rs              # CLI entry point and argument parsing
├── lib.rs              # Library exports
├── commands/           # Command implementations
│   ├── search.rs       # Agent search functionality
│   ├── pull.rs         # Agent download and extraction
│   ├── publish.rs      # Agent packaging and upload
│   └── new.rs          # Template generation
├── config/             # Configuration management
├── api/                # HTTP client for registry API
├── auth/               # Authentication handling
└── utils/              # Shared utilities and error handling

Error Handling

The CLI provides comprehensive error handling with user-friendly messages:

• Network connectivity issues
• Authentication failures
• File system errors
• Manifest validation errors
• API rate limiting and server errors

Contributing

This CLI tool follows Rust best practices:

• MSRV: 1.82
• No warnings policy (clippy warnings treated as errors)
• Comprehensive error handling
• Security-first design
• Full test coverage (coming soon)

License

MIT License - see LICENSE for details.