Carp CLI

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

Features

• Search Agents: Find agents in the registry with powerful search functionality
• List Agents: Browse all available agents in the registry
• Pull Agents: Download and extract agents locally for use
• Upload Agents: Upload your agents to the registry
• Health Checks: Verify API connectivity and status
• Authentication: Manage API keys for registry access

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

cargo install carp-cli

Usage

Health Check

# Check API connectivity and status
carp healthcheck

Authentication

# Login with API key
carp auth login

# Check authentication status
carp auth status

# Logout (clear stored API key)
carp auth logout

You can also provide API keys via:

• Command line: --api-key YOUR_KEY
• Environment variable: CARP_API_KEY=YOUR_KEY
• Global flags work with all commands for authentication

List All Agents

# List all available agents
carp list

Search for Agents

# Basic search
carp search "text processing"

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

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

# Search with verbose output
carp search "claude" --verbose

Pull an Agent

# Interactive selection (shows available agents)
carp pull

# Pull specific agent (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

# Pull with verbose output
carp pull agent-name --verbose

Upload an Agent

# Upload from current directory (requires Carp.toml)
carp upload

# Upload from specific directory
carp upload --directory ./path/to/agent

# Upload with API key (if not configured)
carp upload --api-key YOUR_API_KEY

# Upload with verbose output
carp upload --verbose

Configuration

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

api_key = "your-api-key"

Authentication Methods

1. Config file (persistent): ~/.config/carp/config.toml
2. Environment variable: export CARP_API_KEY="your-api-key"
3. Command line flag: --api-key YOUR_API_KEY (works with any command)

Global Options

All commands support these global options:

• --verbose: Enable detailed output
• --quiet: Suppress all output except errors
• --api-key: Provide API key for authentication

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"
tags = ["claude", "ai", "automation"]
files = ["README.md", "agent.py"]
main = "agent.py"

Development

Building

# Build CLI only
just build-cli

# Or from CLI directory
cd cli && cargo build --release

Testing

# Test CLI only  
just test-cli

# Or run specific tests
cargo nextest run --package carp-cli

Linting & Formatting

# Lint (treats warnings as errors)
just lint-cli

# Format code
just fmt-cli

# Format with nightly rustfmt
cargo +nightly fmt

All Checks

# Run full test suite
just tests

# Or workspace-wide checks
just build && just lint && just test

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
│   ├── healthcheck.rs  # API health check
│   ├── list.rs         # List all agents
│   ├── search.rs       # Agent search functionality
│   ├── pull.rs         # Agent download and extraction
│   └── upload.rs       # Agent upload functionality
├── 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
• Agent manifest validation errors
• API rate limiting and server errors
• ZIP extraction and path traversal protection

Contributing

This CLI tool follows Rust best practices:

• MSRV: 1.82
• No warnings policy (clippy warnings treated as errors)
• Comprehensive error handling with anyhow
• Security-first design with input validation
• Type-safe APIs and strong typing
• Performance-conscious implementation

License

MIT License - see LICENSE for details.