CLI Reference¶

The AgenticAI SDK provides a comprehensive command-line interface through run.py for the complete application lifecycle - from local development to production deployment.

Overview¶

The SDK CLI is a unified interface that handles:

Configuration: Select which environment config to use
Local Development: Start and test applications locally
Packaging: Create deployable KAR archives
Deployment: Deploy to the AgenticAI platform
Management: Create environments, check status, and test deployments

CLI Structure¶

What's `run.py`?¶

run.py is a thin wrapper script that invokes the centralized CLI from agenticai_core.cli.runner. It provides a consistent interface across all workspace operations.

# workspace/run.py structure
from agenticai_core.cli.runner import main

if __name__ == '__main__':
    # Wrapper passes app module to centralized CLI
    app_module = 'src.app'  # Your app module
    main(app_module=app_module)

Command Format¶

# General format
python run.py COMMAND [OPTIONS]

Available Commands¶

Command	Purpose	Key Options	Example
`config`	Select which .env config to use	`-u <name>`	`python run.py config -u prod`
`package`	Package app for deployment	`-o <name>`	`python run.py package -o my-app`
`start`	Start local development server	`-H <host>`, `-P <port>`	`python run.py start -H 0.0.0.0`
`deploy`	Deploy to AgenticAI platform	`-f <kar_file>`, `-e <env>`, `--package-only`	`python run.py deploy -f app.kar`
`publish`	Create app environment	`-a <appId>`, `-n <name>`	`python run.py publish -a <id> -n dev`
`status`	Check environment status	`-a <appId>`, `-n <name>`	`python run.py status -a <id> -n dev`
`undeploy`	Undeploy an app environment	`-f <path>`	`python run.py undeploy -f bin/myapp/`
`test`	Run end-to-end tests	-	`python run.py test`

Command Details¶

Config Command¶

Select which environment configuration file to use as the default.

python run.py config -u <config_name>

Options:

-u, --use - Config name to use (for example, dev, staging, prod)

Example:

python run.py config -u prod

This copies .env/prod to .env/default, which is then loaded by subsequent commands.

Package Command¶

Package your application into a deployable KAR archive file.

python run.py package -o <project_name>

Options:

-o, --output - Name for the output package (creates bin/<project_name>/)

Output:

bin/<project_name>/application.kar - Deployable ZIP archive (<1MB target)
bin/<project_name>/application.config.json - Application configuration

Example:

python run.py package -o banking-app

Package Size

Target package size is <1MB. If larger, check contents with unzip -l bin/<project>/application.kar and ensure .venv isn't included.

Start Command¶

Start the application server locally for development and testing.

python run.py start [OPTIONS]

Options:

-H, --host - Server host address (default: localhost)
-P, --port - Server port (default: 8080)

Uppercase Flags

The flags use uppercase -H and -P because lowercase -h conflicts with argparse's built-in help flag.

Example:

python run.py start -H 0.0.0.0 -P 8080

Deploy Command¶

Deploy your application to the AgenticAI platform.

python run.py deploy -f <kar_file> [OPTIONS]

Required Options:

-f, --kar - Path to KAR archive file

Optional:

-e, --env - Path to .env file to override app variables
--package-only - Re-deploys only the package; skips app import

Environment Requirements: Requires in .env/default (set via config command):

KORE_HOST - Platform endpoint URL
APP_API_KEY - API authentication key

Example:

# Full deployment
python run.py deploy -f bin/banking-app/application.kar

# With environment overrides
python run.py deploy -f bin/banking-app/application.kar -e .env/prod

# Package-only redeployment
python run.py deploy -f bin/banking-app/application.kar --package-only

Save Deployment IDs

Save the appId and streamId from deployment output for environment creation and testing.

Publish Command¶

Create an environment for your deployed application.

python run.py publish -a <appId> -n <envName> [OPTIONS]

Required Options:

-a, --app - Application ID (from deploy output)
-n, --name - Environment name (for example, development, staging, production)

Optional:

-d, --desc - Environment description
-e, --env - Path to .env file to override app variables

Example:

python run.py publish -a app_abc123xyz -n development -d "Dev environment"

Status Command¶

Check the status of a deployed application environment.

python run.py status -a <appId> -n <envName>

Required Options:

-a, --app - Application ID
-n, --name - Environment name

Example:

python run.py status -a app_abc123xyz -n development

Undeploy Command¶

Undeploy an application environment.

python run.py undeploy -f <path>

Required Options:

-f, --path - Path to the deployment directory (for example, bin/myapp/)

Example:

python run.py undeploy -f bin/banking-app/

Test Command¶

Run end-to-end tests on a deployed application.

python run.py test

Example:

python run.py test

Quick Reference¶

Complete reference for all run.py commands:

# ============================================
# CONFIGURATION
# ============================================

# Set which config to use
python run.py config -u <config_name>

# Examples
python run.py config -u dev        # Use .env/dev
python run.py config -u prod       # Use .env/prod


# ============================================
# LOCAL DEVELOPMENT
# ============================================

# Start local server
python run.py start [-H HOST] [-P PORT]

# Examples
python run.py start                          # localhost:8080
python run.py start -H 0.0.0.0 -P 8080


# ============================================
# PACKAGING
# ============================================

# Create deployable package
python run.py package -o <project_name>

# Example
python run.py package -o banking-app
ls -lh bin/banking-app/application.kar       # Verify size < 1MB


# ============================================
# DEPLOYMENT
# ============================================

# Deploy to platform
python run.py deploy -f <kar_file>

# Examples
python run.py deploy -f bin/banking-app/application.kar
python run.py deploy -f bin/banking-app/application.kar -e .env/prod
python run.py deploy -f bin/banking-app/application.kar --package-only

# Save the appId and streamId from output!


# ============================================
# ENVIRONMENT MANAGEMENT
# ============================================

# Create environment
python run.py publish -a <appId> -n <envName> [-d "Description"]

# Examples
python run.py publish -a app_abc123xyz -n development
python run.py publish -a app_abc123xyz -n production -d "Production env"

# Check environment status
python run.py status -a <appId> -n <envName>

# Example
python run.py status -a app_abc123xyz -n development

# Undeploy environment
python run.py undeploy -f <path>

# Example
python run.py undeploy -f bin/banking-app/


# ============================================
# TESTING
# ============================================

# Test deployed application
python run.py test

Environment Configuration¶

Create .env/<env> files with required variables:

# .env/dev
KORE_HOST=https://agent-platform.kore.ai
APP_API_KEY=your_dev_api_key_here
TRACING_ENABLED=True

# .env/staging
KORE_HOST=https://agent-platform.kore.ai
APP_API_KEY=your_staging_api_key_here
TRACING_ENABLED=True

# .env/prod
KORE_HOST=https://agent-platform.kore.ai
APP_API_KEY=your_prod_api_key_here
TRACING_ENABLED=False

Set configuration before running commands:

python run.py config -u dev  # Sets .env/dev as .env/default
python run.py deploy -f ...  # Uses .env/default

Application Lifecycle Workflow¶

Complete workflow from development to production:

# ============================================
# 1. DEVELOPMENT PHASE
# ============================================
# Define application structure with Design-Time models
# Implement custom tools and orchestrators
python run.py start -H localhost -P 8080
# Test with MCP client...

# ============================================
# 2. PACKAGING PHASE
# ============================================
python run.py package -o my-banking-app
# Verify: ls -lh bin/my-banking-app/application.kar

# ============================================
# 3. DEPLOYMENT PHASE
# ============================================
python run.py config -u dev
python run.py deploy -f bin/my-banking-app/application.kar
# Output: App ID: app_abc123xyz, Stream ID: stream_def456uvw (SAVE THESE!)

# Create environment
python run.py publish -a app_abc123xyz -n development

# ============================================
# 4. TESTING PHASE
# ============================================
python run.py test

# ============================================
# 5. MONITORING PHASE
# ============================================
python run.py status -a app_abc123xyz -n development

# ============================================
# 6. PRODUCTION DEPLOYMENT (when ready)
# ============================================
python run.py config -u prod
python run.py deploy -f bin/my-banking-app/application.kar
python run.py publish -a <new_appId> -n production
python run.py test

Best Practices¶

Development
- Test locally with python run.py start before deploying
- Use meaningful project names for packages
- Keep package size minimal (<1MB)
- Always test with MCP client during development
Deployment
- Use .venv for virtual environments (excluded from packages)
- Test in staging/dev before production
- Save appId and streamId from deployment output immediately
- Use separate .env files for different environments
- Verify package contents with unzip -l if size is large
Environment Management
- Create separate environments for dev/staging/prod
- Use descriptive environment names and descriptions
- Document appId and environment names in your project README
- Periodically check status with status command
Monitoring
- Enable distributed tracing in dev/staging environments
- Monitor logs and performance metrics
- Use status command to check environment health
- Test deployments end-to-end before going live
Configuration
- Keep sensitive keys in .env files (never commit these!)
- Use different API keys for different environments
- Document required environment variables
- Validate configuration before deployment

Troubleshooting¶

Package Size Issues¶

# Check package contents
unzip -l bin/myProject/application.kar

# Look for unwanted files
unzip -l bin/myProject/application.kar | grep -E "(venv|.venv|__pycache__|.git)"

# Solution: Ensure virtual env is named .venv

Deployment Failures¶

# Verify environment variables
python -c "import os; print(f'KORE_HOST: {os.getenv(\"KORE_HOST\")}'); print(f'APP_API_KEY: {os.getenv(\"APP_API_KEY\")}')"

# Check .env file exists
ls -la .env/

# Set config and deploy
python run.py config -u dev
python run.py deploy -f bin/myProject/application.kar

Module Import Errors¶

# Ensure virtual environment is activated
source .venv/bin/activate

# Verify app module exists
python -c "import src.app; print('Module OK')"

# Check run.py points to correct module
cat run.py | grep "app_module"

Related resources

Getting Started - Complete tutorial with CLI usage
Runtime APIs - Runtime context and services
Building Applications - Application development guide

Send Feedback

CLI Reference¶

Overview¶

CLI Structure¶

What's run.py?¶

Command Format¶

Available Commands¶

Command Details¶

Config Command¶

Package Command¶

Start Command¶

Deploy Command¶

Publish Command¶

Status Command¶

Undeploy Command¶

Test Command¶

Quick Reference¶

Environment Configuration¶

Application Lifecycle Workflow¶

Best Practices¶

Troubleshooting¶

Package Size Issues¶

Deployment Failures¶

Module Import Errors¶

What's `run.py`?¶