CapiscIO CLI

Catch bad agents before your users do.

CapiscIO CLI validates A2A agent cards, tests live endpoints, and blocks broken deployments — one command in your pipeline.

CLI secures your pipeline. Agent Guard secures your runtime.

Installation

pip install capiscio

Also available via npm: npm install -g capiscio

Quick Start

# Validate an agent card (local file or URL)
capiscio validate ./agent-card.json

# Validate a live agent endpoint
capiscio validate https://my-agent.example.com

# JSON output for CI pipelines
capiscio validate https://my-agent.example.com --json

# Strict mode — fail on warnings too
capiscio validate ./agent-card.json --strict

What It Checks

Use Cases

• Pre-commit hooks — Validate agent cards before you push
• CI/CD gates — Block deployments with misconfigured agents (GitHub Action)
• Vendor due diligence — Validate third-party agents before integration
• Cron monitoring — Continuous health checks on agent endpoints

Dev & Testing Commands

The CLI also exposes badge and key management commands for local development and testing:

# Issue a self-signed badge (dev/testing only)
capiscio badge issue --self-sign

# Verify a badge
capiscio badge verify "$TOKEN"

# Generate a key pair
capiscio key gen

# Start the gateway sidecar
capiscio gateway start --port 8080 --target http://localhost:3000

For full CLI reference, see the capiscio-core documentation.

Wrapper Utilities

How It Works

This package is a lightweight Python wrapper around capiscio-core (written in Go). On first run it downloads the correct binary for your platform — zero overhead after that.

1. Detects your OS (Linux, macOS, Windows) and architecture (AMD64, ARM64)
2. Downloads the binary to your user cache (with SHA-256 checksum verification)
3. Replaces the Python process with the Go binary — native speed, no shim

Supported Platforms

• macOS: AMD64 (Intel), ARM64 (Apple Silicon)
• Linux: AMD64, ARM64
• Windows: AMD64

Binary Integrity Verification

On first run, the wrapper downloads the capiscio-core binary and verifies its SHA-256 checksum against the published checksums.txt from the GitHub release.

Two failure modes exist:

1. Checksum mismatch ("Binary integrity check failed"): The downloaded file does not match the published checksum. This indicates tampering or corruption and cannot be bypassed. Delete the cached binary and retry.

2. Checksums unavailable ("checksums.txt could not be fetched" or "no entry for …"): The checksums file could not be downloaded or does not contain an entry for the platform binary. This can happen with pre-release versions or network issues. To bypass:

# Bypass only when checksums.txt is unavailable (not for mismatches)
export CAPISCIO_SKIP_CHECKSUM=true

Troubleshooting

"Permission denied" errors: Ensure your user has write access to the cache directory. You can reset the cache by running:

capiscio --wrapper-clean

"Binary not found" or download errors: If you are behind a corporate firewall, ensure you can access github.com.

"Binary integrity check failed": The downloaded binary does not match the published checksum — this may indicate a corrupted or tampered download. Delete the cached binary (capiscio --wrapper-clean) and retry. This error cannot be bypassed with CAPISCIO_SKIP_CHECKSUM.

"Checksum verification failed: checksums.txt could not be fetched": The checksums file is unavailable (network issue or pre-release version). You can set CAPISCIO_SKIP_CHECKSUM=true to proceed without verification, but only do this in development environments.

License

Apache-2.0

Related Packages

Documentation · Website · Platform