CLI Commands

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

Authenticate with Kapso Cloud.

kapso login

Process:

Opens browser for authentication
Stores credentials securely
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:

Compiles Python to YAML (if needed)
Validates agent structure
Uploads agent configuration
Uploads test suites
Creates deployment snapshot
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 [AGENT_ID] [options]

Arguments:

AGENT_ID: Agent identifier (optional, interactive selection if not provided)

Options:

--project-id <id>, -p: Project ID (required when using KAPSO_API_KEY)
--yes, -y: Skip confirmation prompts
--output <dir>: Output directory (default: current)
--format <type>: Output format (yaml or python)

Example:

# Interactive agent selection
kapso pull

# Pull specific agent
kapso pull agent_abc123

# Pull with project ID (for KAPSO_API_KEY)
kapso pull agent_abc123 --project-id proj_123456

# Skip confirmation prompts
kapso pull agent_abc123 -p proj_123456 -y

# Pull as Python
kapso pull agent_abc123 --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

Getting Started

Node Types

Testing & Deployment

Overview

Complete example

Installation

Global options

Command reference

kapso init

kapso compile

kapso run

kapso test

kapso deploy

kapso pull

kapso logout

kapso version

Project configuration

kapso.yaml

.env

.deployed.yaml

Common workflows

1. Create and deploy new agent

2. Update existing agent

3. Debug failed tests

4. Collaborate on agent

Command exit codes

Tips and tricks

1. Verbose mode

2. Cloud testing

3. Quick iteration

4. Environment management

5. Test single features

Troubleshooting

Authentication issues

Compilation errors

Deployment failures

Test failures

Getting Started

Node Types

Testing & Deployment

​Overview

​Complete example

​Installation

​Global options

​Command reference

​kapso init

​kapso login

​kapso compile

​kapso run

​kapso test

​kapso deploy

​kapso pull

​kapso logout

​kapso version

​Project configuration

​kapso.yaml

​.env

​.deployed.yaml

​Common workflows

​1. Create and deploy new agent

​2. Update existing agent

​3. Debug failed tests

​4. Collaborate on agent

​Command exit codes

​Tips and tricks

​1. Verbose mode

​2. Cloud testing

​3. Quick iteration

​4. Environment management

​5. Test single features

​Troubleshooting

​Authentication issues

​Compilation errors

​Deployment failures

​Test failures

Overview

Complete example

Installation

Global options

Command reference

kapso init

kapso login

kapso compile

kapso run

kapso test

kapso deploy

kapso pull

kapso logout

kapso version

Project configuration

kapso.yaml

.env

.deployed.yaml

Common workflows

1. Create and deploy new agent

2. Update existing agent

3. Debug failed tests

4. Collaborate on agent

Command exit codes

Tips and tricks

1. Verbose mode

2. Cloud testing

3. Quick iteration

4. Environment management

5. Test single features

Troubleshooting

Authentication issues

Compilation errors

Deployment failures

Test failures