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

# On-Demand Execution

> Execute tasks with intelligent planning, ephemeral workers, and pipeline integration

Execute tasks on-demand with automatic planning, agent selection, and flexible worker deployment strategies.

## Quick Start

```bash theme={null}
# Simple execution (auto-selects agent/team)
kubiya exec "Deploy my app to production"

# Local execution with ephemeral worker
kubiya exec "Run tests for changed files" --local --cwd $(pwd)

# Direct execution (skip planning)
kubiya exec agent AGENT_ID "Deploy to staging"
```

## Execution Lifecycle

Every execution follows this lifecycle:

**Submit Request** → **Planning** → **Execute** → **Complete**

1. **Submit Request**: Prompt analysis, resource discovery
2. **Planning**: Agent selection, cost estimation, plan creation
3. **Execute**: Queue selection, worker assignment, streaming output
4. **Complete**: Status update, response storage, graph updates

### Lifecycle Stages

#### 1. Submit Request

* User provides natural language prompt
* CLI authenticates with API key
* Request routed to control plane

#### 2. Planning (Auto Mode)

* **Resource Discovery**: Fetches available agents, teams, environments
* **Agent Selection**: AI analyzes prompt and selects best agent/team
* **Cost Estimation**: Calculates token usage and estimated cost
* **Plan Generation**: Creates detailed execution plan
* **User Approval**: Shows plan for review (unless `--yes`)

#### 3. Execute

* **Queue Selection**: Chooses worker queue (persistent or ephemeral)
* **Worker Assignment**: Assigns task to available worker in queue
* **Execution**: Worker runs task using agent/team configuration
* **Streaming**: Real-time output streamed to CLI
* **Context Updates**: Updates context graph with results

#### 4. Complete

* **Status Update**: Marks execution as complete/failed
* **Response Storage**: Stores full response in database
* **Graph Updates**: Updates knowledge graph with execution metadata
* **Cleanup**: For ephemeral workers, deletes queue and terminates process

## Worker Deployment Modes

Choose between two deployment strategies based on your needs:

### Persistent Workers

**Best for:** Production environments and high-frequency tasks

Long-running workers that stay active and handle multiple executions:

```bash theme={null}
# Deploy a persistent worker
kubiya worker start --queue-id QUEUE_ID --daemon
```

**Benefits:**

* ⚡ Instant task startup (dependencies already installed)
* 🔄 Handles multiple tasks sequentially
* 📦 Pre-warmed environment ready to execute
* 🎯 Best for production workloads

**When to use:**

* Production agent deployments
* Frequent executions throughout the day
* Shared team resources
* Mission-critical agents

### Ephemeral Workers

**Best for:** CI/CD pipelines and one-off tasks

Short-lived workers created on-demand for single executions:

```bash theme={null}
# Automatically created when you use --local
kubiya exec "task" --local
```

**Benefits:**

* 💰 Pay only when running (no idle costs)
* 🧹 Automatic cleanup after execution
* 🔒 Isolated environment per execution
* 🚀 Perfect for CI/CD pipelines

**When to use:**

* CI/CD pipeline integration
* Development and testing
* Occasional or scheduled tasks
* Local execution from CLI

### Quick Comparison

|               | Persistent Workers        | Ephemeral Workers              |
| ------------- | ------------------------- | ------------------------------ |
| **Startup**   | Instant (pre-warmed)      | 10-120s first run, then cached |
| **Lifecycle** | Always running            | Created → Execute → Cleanup    |
| **Cost**      | Continuous resource usage | Pay per execution              |
| **Best For**  | Production, frequent use  | CI/CD, occasional tasks        |
| **Cleanup**   | Manual management         | Automatic (5 min TTL)          |

## Local Execution Mode

Run tasks with an ephemeral worker directly from your CLI or CI/CD pipeline.

### How It Works

```bash theme={null}
kubiya exec "analyze and fix linting errors" --local --cwd $(pwd)
```

When you run with `--local`, here's what happens:

1. **Queue Setup** - CLI creates a temporary queue with 5-minute auto-cleanup
2. **Worker Launch** - CLI starts a local Python worker process
3. **Task Execution** - Worker runs in your specified directory with full file access
4. **Stream Results** - Real-time output appears in your terminal
5. **Auto Cleanup** - Worker exits and queue is automatically deleted

**Key Benefits:**

* 📁 Full access to local files and git repository
* 🔄 Works from any directory with `--cwd`
* ⚡ Fast for cached runs (dependencies installed once)
* 🧹 Zero cleanup needed (automatic)

### Working Directory Support

The `--cwd` flag sets the execution working directory:

```bash theme={null}
# Execute in current directory
kubiya exec "analyze git diff" --local --cwd $(pwd)

# Execute in specific directory
kubiya exec "run tests" --local --cwd /path/to/project

# In CI/CD pipeline
kubiya exec "run changed tests" --local --cwd $CIRCLE_WORKING_DIRECTORY
```

**Why This Matters:**

* **Local File Access**: Worker can read/write files in specified directory
* **Git Integration**: Access to .git directory and git commands
* **Project Context**: Reads package.json, requirements.txt, etc.
* **Pipeline Integration**: CI/CD jobs can pass their working directory

### Pipeline Integration

Local mode is perfect for CI/CD pipelines. Here are examples for popular platforms:

#### GitHub Actions

```yaml theme={null}
name: Smart Testing
on: [pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Kubiya CLI
        run: |
          curl -fsSL https://raw.githubusercontent.com/kubiyabot/cli/main/install.sh | bash
          echo "$HOME/.kubiya/bin" >> $GITHUB_PATH

      - name: Run Smart Tests
        env:
          KUBIYA_API_KEY: ${{ secrets.KUBIYA_API_KEY }}
          KUBIYA_NON_INTERACTIVE: "true"
        run: |
          kubiya exec "
            Analyze git diff and run only tests for changed files.
            Skip irrelevant test suites.
          " \
            --local \
            --cwd ${{ github.workspace }} \
            --yes
```

#### GitLab CI

```yaml theme={null}
test-smart:
  stage: test
  image: node:20
  variables:
    KUBIYA_NON_INTERACTIVE: "true"
  script:
    - curl -fsSL https://raw.githubusercontent.com/kubiyabot/cli/main/install.sh | bash
    - export PATH="$HOME/.kubiya/bin:$PATH"
    - |
      kubiya exec "
        Analyze git diff and run only affected tests.
      " \
        --local \
        --cwd $CI_PROJECT_DIR \
        --yes
```

#### CircleCI

```yaml theme={null}
version: 2.1
jobs:
  test:
    docker:
      - image: cimg/node:20.11
    environment:
      KUBIYA_NON_INTERACTIVE: "true"
    steps:
      - checkout
      - run:
          name: Install Kubiya CLI
          command: |
            curl -fsSL https://raw.githubusercontent.com/kubiyabot/cli/main/install.sh | bash
            export PATH="$HOME/.kubiya/bin:$PATH"
      - run:
          name: Smart Test Selection
          command: |
            export PATH="$HOME/.kubiya/bin:$PATH"
            kubiya exec "Analyze git diff and run only affected tests." \
              --local --cwd $(pwd) --yes
```

**Key Points:**

* `--local`: Creates ephemeral worker in the CI environment
* `--cwd`: Sets working directory to pipeline workspace
* `--yes`: Skips approval prompts for automation
* `KUBIYA_NON_INTERACTIVE="true"`: Ensures non-interactive mode

### Real-World Use Case: Smart Test Selection

**Problem:** Traditional CI runs ALL tests on every commit, even when only one module changed.

**Solution:** Kubiya analyzes changes and runs only relevant tests.

**Example from a Node.js project with modular test suites:**

```bash theme={null}
# In CI/CD pipeline
kubiya exec "
  You are an intelligent test executor.

  Steps:
  1. Run 'git diff HEAD~1 --name-only' to see changed files
  2. Analyze which module(s) were affected
  3. Run ONLY relevant test suites
  4. Explain your reasoning

  Rules:
  - If src/tasks/ changed, run: npm run test:tasks
  - If src/projects/ changed, run: npm run test:projects
  - If multiple modules changed, run tests for each
  - If only docs changed, skip all tests
" \
  --local \
  --cwd $(pwd) \
  --yes
```

**Results:**

* Single module change: Run 8/36 tests (78% faster)
* Documentation change: Run 0/36 tests (100% time saved)
* Average savings: 77% time reduction

**How It Works:**

1. **Git Diff Analysis**: `git diff --name-only` shows `src/tasks/tasks.js`
2. **Module Detection**: Recognizes "tasks" module changed
3. **Test Selection**: Runs `npm run test:tasks` (8 tests)
4. **Skip Irrelevant**: Skips projects, comments, tags, search tests (28 tests)

## Execution Modes

### Auto-Planning Mode (Recommended)

Automatically selects agent/team and creates plan:

```bash theme={null}
# Basic usage
kubiya exec "Deploy app to production"

# With options
kubiya exec "Analyze security issues" \
  --yes \
  --priority high \
  --output json
```

**Features:**

* Analyzes task requirements
* Selects best agent or team
* Estimates cost and time
* Shows detailed plan
* Asks for approval

### Local Mode

Execute with ephemeral local worker:

```bash theme={null}
# Basic local execution
kubiya exec "task" --local

# With working directory
kubiya exec "run tests" --local --cwd $(pwd)

# With custom package source
kubiya exec "task" \
  --local \
  --package-source 0.5.0

# With local development wheel
kubiya exec "task" \
  --local \
  --local-wheel /path/to/worker.whl
```

**Options:**

* `--local`: Use ephemeral worker
* `--cwd PATH`: Set working directory
* `--environment ID`: Specify environment
* `--package-source SOURCE`: Custom worker package
* `--local-wheel PATH`: Local wheel file (development)

### Direct Mode

Skip planning and execute directly:

```bash theme={null}
# Execute with specific agent
kubiya exec agent AGENT_ID "Deploy to staging"

# Execute with specific team
kubiya exec team TEAM_ID "Run integration tests"
```

**Use Cases:**

* Testing specific agents
* Bypassing plan approval
* Scripting and automation

### Plan File Mode

Execute from saved plan:

```bash theme={null}
# Execute saved plan
kubiya exec --plan-file ~/.kubiya/plans/abc123.json

# Execute from URL
kubiya exec --plan-file https://example.com/plan.json

# Execute from GitHub
kubiya exec --plan-file user/repo/path/to/plan.json
```

## Command Reference

```bash theme={null}
# Auto-planning mode
kubiya exec "PROMPT" [flags]

# Local mode
kubiya exec "PROMPT" --local [--cwd PATH] [--environment ID]

# Direct mode
kubiya exec agent AGENT_ID "PROMPT"
kubiya exec team TEAM_ID "PROMPT"

# Plan file mode
kubiya exec --plan-file PATH_OR_URL
```

### Global Flags

* `--yes, -y`: Auto-approve plan (skip confirmation)
* `--output, -o`: Output format (`text`, `json`, `yaml`)
* `--non-interactive`: Skip all prompts
* `--priority`: Task priority (`low`, `medium`, `high`, `critical`)
* `--save-plan PATH`: Custom plan save location

### Local Mode Flags

* `--local`: Enable local execution mode
* `--cwd PATH`: Working directory for execution
* `--environment ID`: Environment ID
* `--package-source SOURCE`: Worker package source (PyPI version, git URL, GitHub ref)
* `--local-wheel PATH`: Path to local wheel file (development)

### Queue Flags

* `--queue ID`: Specific worker queue ID(s)
* `--queue-name NAME`: Queue selection by name

### Advanced Flags

* `--parent-execution ID`: Parent execution for conversation continuation

## Environment Variables

```bash theme={null}
# API authentication
export KUBIYA_API_KEY=your-api-key

# Non-interactive mode (for CI/CD)
export KUBIYA_NON_INTERACTIVE=true

# Debug output
export KUBIYA_DEBUG=true
```

## Best Practices

### Local Execution

* Use `--local` for CI/CD pipelines
* Always specify `--cwd` for file access
* Set `KUBIYA_NON_INTERACTIVE=true` in pipelines
* Use `--yes` to skip approval prompts
* Capture `--output json` for result parsing

### Persistent Workers

* Use for production environments
* Pre-deploy workers to reduce latency
* Monitor worker health and capacity
* Scale workers based on load

### Planning

* Review plans before approval in production
* Save important plans for reproducibility
* Use `--priority` for urgent tasks
* Check cost estimates for large operations

### Error Handling

* Parse `--output json` for status codes
* Implement retries for transient failures
* Monitor execution logs
* Set up alerts for failed executions

## Next Steps

<CardGroup cols={2}>
  <Card title="Workers" icon="server" href="/cli/workers">
    Deploy and manage worker infrastructure
  </Card>

  <Card title="Workflows" icon="diagram-next" href="/cli/workflows">
    Compose multi-step execution workflows
  </Card>

  <Card title="Core Resources" icon="cube" href="/cli/core-resources">
    Manage agents, teams, and projects
  </Card>

  <Card title="Execution Resources" icon="list-check" href="/cli/execution-resources">
    View and manage execution history
  </Card>
</CardGroup>