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 (less than 1 MB target)
bin/<project_name>/application.config.json - Application configuration

Example:

python run.py package -o banking-app

Target package size is less than 1 MB. 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)

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 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

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 (less than 1 MB)
- 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 Resource

SDK concepts and references.

Building Agents

Platform Services

Administration

References

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

Building Agents

Platform Services

Administration

References

​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

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