Skip to content

Python Wrapper (pip)

Install CapiscIO CLI via pip

The capiscio Python package provides a pip-installable wrapper for the CapiscIO CLI.

Installation

pip install capiscio

Or with a specific version:

pip install capiscio==0.3.0

How It Works

When you run pip install capiscio:

  1. Detects your OS (Linux, macOS, Windows) and architecture (x64, ARM64)
  2. Downloads the correct capiscio-core binary from GitHub releases
  3. Installs the binary to your Python environment's bin directory
  4. Creates a capiscio command that proxies to the binary

Usage

After installation, use capiscio directly from your terminal:

# Validate an agent card
capiscio validate agent-card.json

# Validate with JSON output
capiscio validate agent-card.json --json

# Test live endpoint
capiscio validate https://agent.example.com --test-live

All CLI flags are identical to the core binary. See CLI Reference for the complete command reference.

Wrapper-Specific Options

The Python wrapper adds two utility flags:

Flag Description
--wrapper-version Show the pip package version (not the core binary version)
--wrapper-clean Remove downloaded binary and re-download on next run 
# Check wrapper package version
capiscio --wrapper-version

# Force re-download of binary
capiscio --wrapper-clean

Virtual Environments

The wrapper works correctly in virtual environments:

# Create and activate venv
python -m venv .venv
source .venv/bin/activate

# Install in venv
pip install capiscio

# Binary is installed to .venv/bin/capiscio
which capiscio
# → /path/to/project/.venv/bin/capiscio

CI/CD Usage

GitHub Actions

- name: Set up Python
  uses: actions/setup-python@v5
  with:
    python-version: '3.11'

- name: Install CapiscIO
  run: pip install capiscio

- name: Validate Agent
  run: capiscio validate agent-card.json --strict

GitLab CI

validate:
  image: python:3.11
  script:
    - pip install capiscio
    - capiscio validate agent-card.json --strict

Troubleshooting

Binary Download Fails

If the binary download fails, check your network connection and try:

# Clean and reinstall
pip uninstall capiscio
pip install capiscio

Permission Errors

On Unix systems, ensure the binary is executable:

chmod +x $(python -c "import capiscio; print(capiscio.BINARY_PATH)")

Platform Not Supported

The wrapper supports: - Linux: x64, ARM64 - macOS: x64 (Intel), ARM64 (Apple Silicon) - Windows: x64

If your platform isn't supported, build from source.

See Also