CLI Reference

The AgenticAI SDK provides a command-line interface through run.py for the complete application lifecycle — from local development to production deployment. run.py is a thin wrapper that invokes the centralized CLI from agenticai_core.cli.runner:

from agenticai_core.cli.runner import main

if __name__ == '__main__':
    app_module = 'src.app'
    main(app_module=app_module)

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>

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

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

python run.py config -u prod

Package Command

Package your application into a deployable KAR archive file.

python run.py package -o <project_name>

Option	Description
`-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

python run.py package -o banking-app

!!! tip “Package Size” 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]

Option	Default	Description
`-H, --host`	`localhost`	Server host address
`-P, --port`	`8080`	Server port

!!! note “Uppercase Flags” The flags use uppercase -H and -P because lowercase -h conflicts with argparse’s built-in help flag.

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]

Option	Required	Description
`-f, --kar`	Yes	Path to KAR archive file
`-e, --env`	No	Path to .env file to override app variables
`--package-only`	No	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

# 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

!!! warning “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]

Option	Required	Description
`-a, --app`	Yes	Application ID (from deploy output)
`-n, --name`	Yes	Environment name (for example, `development`, `staging`, `production`)
`-d, --desc`	No	Environment description
`-e, --env`	No	Path to .env file to override app variables

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>

Option	Required	Description
`-a, --app`	Yes	Application ID
`-n, --name`	Yes	Environment name

python run.py status -a app_abc123xyz -n development

Undeploy Command

Undeploy an application environment.

python run.py undeploy -f <path>

Option	Required	Description
`-f, --path`	Yes	Path to the deployment directory (for example, `bin/myapp/`)

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

Test Command

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

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
# 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
python run.py package -o my-banking-app
# Verify: ls -lh bin/my-banking-app/application.kar

# 3. DEPLOYMENT
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!)

# 4. ENVIRONMENT CREATION
python run.py publish -a app_abc123xyz -n development

# 5. TESTING
python run.py test

# 6. MONITORING
python run.py status -a app_abc123xyz -n development

# 7. 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 (< 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

Available Commands

Command Details

Config Command

Package Command

Start Command

Deploy Command

Publish Command

Status Command

Undeploy Command

Test Command

Environment Configuration

Application Lifecycle Workflow

Best Practices

Troubleshooting

Package Size Issues

Deployment Failures

Module Import Errors

Building Agents

Platform Services

Administration

References

​Available Commands

​Command Details

​Config Command

​Package Command

​Start Command

​Deploy Command

​Publish Command

​Status Command

​Undeploy Command

​Test Command

​Environment Configuration

​Application Lifecycle Workflow

​Best Practices

​Troubleshooting

​Package Size Issues

​Deployment Failures

​Module Import Errors

Available Commands

Command Details

Config Command

Package Command

Start Command

Deploy Command

Publish Command

Status Command

Undeploy Command

Test Command

Environment Configuration

Application Lifecycle Workflow

Best Practices

Troubleshooting

Package Size Issues

Deployment Failures

Module Import Errors