> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.app/llms.txt
> Use this file to discover all available pages before exploring further.

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

```python theme={null}
# 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

```bash theme={null}
# 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.

```bash theme={null}
python run.py config -u <config_name>
```

**Options:**

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

**Example:**

```bash theme={null}
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.

```bash theme={null}
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:**

```bash theme={null}
python run.py package -o banking-app
```

<Note>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.</Note>

### Start Command

Start the application server locally for development and testing.

```bash theme={null}
python run.py start [OPTIONS]
```

**Options:**

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

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

**Example:**

```bash theme={null}
python run.py start -H 0.0.0.0 -P 8080
```

### Deploy Command

Deploy your application to the AgenticAI platform.

```bash theme={null}
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:**

```bash theme={null}
# 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
```

<Note>Save the `appId` and `streamId` from deployment output for environment creation and testing.</Note>

### Publish Command

Create an environment for your deployed application.

```bash theme={null}
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:**

```bash theme={null}
python run.py publish -a app_abc123xyz -n development -d "Dev environment"
```

### Status Command

Check the status of a deployed application environment.

```bash theme={null}
python run.py status -a <appId> -n <envName>
```

**Required Options:**

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

**Example:**

```bash theme={null}
python run.py status -a app_abc123xyz -n development
```

### Undeploy Command

Undeploy an application environment.

```bash theme={null}
python run.py undeploy -f <path>
```

**Required Options:**

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

**Example:**

```bash theme={null}
python run.py undeploy -f bin/banking-app/
```

### Test Command

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

```bash theme={null}
python run.py test
```

**Example:**

```bash theme={null}
python run.py test
```

## Quick Reference

Complete reference for all `run.py` commands:

```bash expandable=true theme={null}
# ============================================
# 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:

<CodeGroup>
  ```bash dev theme={null}
  # .env/dev
  KORE_HOST=https://agent-platform.kore.ai
  APP_API_KEY=your_dev_api_key_here
  TRACING_ENABLED=True
  ```

  ```bash staging theme={null}
  # .env/staging
  KORE_HOST=https://agent-platform.kore.ai
  APP_API_KEY=your_staging_api_key_here
  TRACING_ENABLED=True
  ```

  ```bash prod theme={null}
  # .env/prod
  KORE_HOST=https://agent-platform.kore.ai
  APP_API_KEY=your_prod_api_key_here
  TRACING_ENABLED=False
  ```
</CodeGroup>

Set configuration before running commands:

```bash theme={null}
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:

```bash theme={null}
# ============================================
# 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

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

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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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](/agent-platform/sdk-overview#7-advanced-concepts-and-next-steps).