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

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

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

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

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

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