​
Overview

The Kapso CLI provides comprehensive commands for developing, testing, and deploying conversational agents.

​
Complete example

# Initialize a new project
kapso init --template support

# Navigate to project directory
cd my-support-agent

# Login to Kapso Cloud
kapso login

# Compile agent to YAML
kapso compile

# Run agent locally for testing
kapso run

# Deploy to production
kapso deploy --name "Customer Support Bot"

# Run tests
kapso test

# Run a specific test
kapso test tests/support_tests/greeting_flow.yaml

​
Installation

pip install kapso

​
Global options

All commands support these global options:

kapso [command] [options] --verbose    # Enable detailed output

​
Command reference

​
kapso init

Initialize a new Kapso project.

kapso init [options]

Options:

  • --template <name>: Use a specific template
    • basic: Simple agent with SubagentNode (default)
    • support: Customer support template
    • knowledge-base: Knowledge-focused template

What it creates:

.
├── agent.py          # Python agent definition
├── kapso.yaml        # Project configuration
├── .env             # Environment variables
├── .gitignore       # Git ignore file
└── tests/           # Test directory
    └── basic/
        ├── test-suite.yaml
        └── greeting_test.yaml

Example:

# Basic initialization
kapso init

# With template
kapso init --template support

​
kapso login

Authenticate with Kapso Cloud.

kapso login

Process:

  1. Opens browser for authentication
  2. Stores credentials securely
  3. Validates API access

Stored credentials location:

  • macOS/Linux: ~/.kapso/credentials
  • Windows: %USERPROFILE%\.kapso\credentials

​
kapso compile

Convert Python agent definition to YAML format.

kapso compile [options]

Options:

  • --input <file>: Python file to compile (default: agent.py)
  • --output <file>: Output YAML file (default: agent.yaml)

Example:

# Default compilation
kapso compile

# Custom files
kapso compile --input my_agent.py --output custom.yaml

​
kapso run

Test your agent interactively.

kapso run [options]

Options:

  • --cloud: Run in cloud with visual debugger
  • --verbose: Show detailed execution logs
  • --agent <id>: Run specific agent by ID

Modes:

Local mode (default):

kapso run
  • Runs agent locally
  • Text-based interface
  • No persistent memory

Cloud mode:

kapso run --cloud
  • Opens visual debugger in browser
  • Shows conversation flow graph
  • Persistent conversation memory
  • Real-time node highlighting

Example session:

$ kapso run
Starting local agent...
Agent ready! Type 'exit' to quit.

You: Hello
Agent: Hi! How can I help you today?

You: What's the weather?
Agent: I'll check the weather for you...
[Uses weather API tool]
Agent: It's currently 72°F and sunny.

You: exit
Goodbye!

​
kapso test

Run test suites against your agent.

kapso test [target] [options]

Arguments:

  • target: Test suite name or test file path (optional)

Options:

  • --verbose: Show detailed test execution
  • --local: Test against local agent (default: cloud)

Examples:

# Run all tests
kapso test

# Run specific test suite
kapso test "Customer Support Tests"

# Run specific test file
kapso test tests/greeting_test.yaml

# Verbose output
kapso test --verbose

Output:

Running Customer Support Tests...
✓ greeting_test (0.95/1.00)
✓ order_flow_test (0.88/1.00)
✗ error_handling (0.65/1.00)

Summary: 2 passed, 1 failed
Average Score: 0.83/1.00

​
kapso deploy

Deploy your agent to Kapso Cloud.

kapso deploy [options]

Options:

  • --project <id>: Deploy to specific project
  • --name <name>: Override agent name
  • --skip-tests: Deploy without running tests

What it does:

  1. Compiles Python to YAML (if needed)
  2. Validates agent structure
  3. Uploads agent configuration
  4. Uploads test suites
  5. Creates deployment snapshot
  6. Returns deployment URL

Output:

$ kapso deploy
Compiling agent...
Validating structure...
Uploading to Kapso Cloud...
Uploading test suites...

✓ Agent deployed successfully!
Agent ID: agent_abc123
Dashboard: https://app.kapso.ai/agents/agent_abc123
API Endpoint: https://api.kapso.ai/agents/agent_abc123

Deployment saved to .deployed.yaml

​
kapso pull

Download an agent from Kapso Cloud.

kapso pull [options]

Options:

  • --agent <id>: Agent ID to pull
  • --output <dir>: Output directory (default: current)
  • --format <type>: Output format (yaml or python)

Example:

# Pull latest deployed agent
kapso pull

# Pull specific agent
kapso pull --agent agent_abc123

# Pull as Python
kapso pull --format python

​
kapso logout

Remove stored authentication credentials.

kapso logout

Confirmation:

$ kapso logout
Are you sure you want to logout? (y/N): y
✓ Successfully logged out

​
kapso version

Display version information.

kapso version

Output:

Kapso SDK version: 1.2.3
CLI version: 1.2.3
Python: 3.9.7
Platform: darwin-arm64

​
Project configuration

​
kapso.yaml

Project configuration file:

# kapso.yaml
name: my_agent_project
description: Customer support agent
version: 1.0.0
project_id: proj_123456  # From Kapso Cloud

​
.env

Environment variables:

# .env
# LLM Configuration
LLM_PROVIDER_NAME=Anthropic
LLM_PROVIDER_MODEL_NAME=claude-3-sonnet-20240229
LLM_API_KEY=your-key
LLM_TEMPERATURE=0.0
LLM_MAX_TOKENS=8096

# API Keys
WEATHER_API_KEY=abc123
DATABASE_URL=postgres://...

# Custom Variables
COMPANY_NAME=ACME Corp
SUPPORT_EMAIL=support@acme.com

​
.deployed.yaml

Deployment state (auto-generated):

# .deployed.yaml
agent_id: agent_abc123
agent_snapshot_id: snapshot_456
deployed_at: 2024-01-15T10:30:00Z
project_id: proj_789
test_suites:
  - id: suite_001
    name: Customer Support Tests

​
Common workflows

​
1. Create and deploy new agent

# Initialize project
kapso init

# Edit agent.py
# ... make changes ...

# Test locally
kapso run

# Run tests
kapso test

# Deploy
kapso deploy

​
2. Update existing agent

# Pull latest version
kapso pull

# Make changes
# ... edit agent.py ...

# Test changes
kapso run --cloud

# Deploy update
kapso deploy

​
3. Debug failed tests

# Run with verbose output
kapso test --verbose

# Test specific case
kapso test tests/failing_test.yaml --verbose

# Test locally
kapso run
# Manually walk through test scenario

​
4. Collaborate on agent

# Team member 1: Deploy agent
kapso deploy

# Team member 2: Pull agent
kapso pull --agent agent_abc123

# Make changes and test
kapso run --cloud

# Deploy updates
kapso deploy

​
Command exit codes

  • 0: Success
  • 1: General error
  • 2: Authentication error
  • 3: Validation error
  • 4: Network error
  • 5: Configuration error

​
Tips and tricks

​
1. Verbose mode

Always use --verbose when debugging:

kapso deploy --verbose
kapso test --verbose

​
2. Cloud testing

Use cloud mode for visual debugging:

kapso run --cloud

​
3. Quick iteration

Keep a terminal open with:

# Terminal 1: Edit files
# Terminal 2: 
watch -n 2 'kapso compile && kapso test'

​
4. Environment management

Use .env.example for team sharing:

# .env.example
WEATHER_API_KEY=your_key_here
DATABASE_URL=your_db_url_here

​
5. Test single features

Create focused test files:

kapso test tests/specific_feature_test.yaml

​
Troubleshooting

​
Authentication issues

# Re-authenticate
kapso logout
kapso login

​
Compilation errors

# Validate Python syntax
python -m py_compile agent.py

# Check for detailed errors
kapso compile --verbose

​
Deployment failures

# Check project configuration
cat kapso.yaml

# Verify credentials
kapso version  # Should show auth status

# Try with verbose
kapso deploy --verbose

​
Test failures

# Run single test with verbose
kapso test "Test Name" --verbose

# Test locally to debug
kapso run