Smart Execution

The kubiya exec command provides intelligent task execution with automatic agent/team selection, detailed planning, and cost optimization. No infrastructure setup required - just execute and go!

Overview

Key Features

Automatic Agent Selection: Analyzes your task and selects the best agent or team
Intelligent Planning: Creates step-by-step execution plans
Cost Estimation: Shows estimated costs before execution
On-Demand Workers: Auto-provisions ephemeral workers (no setup needed)
Plan Storage: Saves all plans for repeatability and audit
Multiple Execution Modes: Auto-planning, direct execution, or from saved plans

Quick Start

Execute with On-Demand Worker (Easiest)

Run AI tasks without needing a queue in advance - perfect for CI/CD pipelines!

# Execute any task - no queue needed!
kubiya exec "Deploy my application to production"

How it works: The Control Plane creates an ephemeral worker queue for your execution, provisions a worker on managed infrastructure, runs your task, and automatically cleans up. The CLI:

Analyzes your task requirements
Selects the best agent or team
Creates a detailed execution plan
Shows cost estimates
Control Plane provisions ephemeral queue + worker
Executes the task
Auto-cleans up queue and worker
Returns results

No queue setup or infrastructure management needed! This makes it perfect for integrations inside CI/CD pipelines.

Execution Modes

Auto-Planning Mode (Recommended)

Let the planner automatically select the best agent/team for your task:

# Basic execution with planning
kubiya exec "Deploy my app to production"

# Auto-approve without confirmation
kubiya exec "Run integration tests" --yes

# Set task priority
kubiya exec "Critical security patch" --priority critical

# JSON output for automation
kubiya exec "Generate report" --output json

What happens:

✓ Task analyzed and categorized
✓ Available agents/teams discovered
✓ Best match selected with reasoning
✓ Execution plan generated
✓ Cost estimate calculated
✓ User approval requested (unless —yes)
✓ Plan saved to ~/.kubiya/plans/<plan-id>.json
✓ Task executed

Direct Execution Mode

Execute with a specific agent or team (skips planning):

With Agent
With Team

# Execute with specific agent
kubiya exec agent <agent-id> "Deploy to staging"

# Stream execution logs
kubiya exec agent <agent-id> "Run tests" --stream

# Execute with team
kubiya exec team <team-id> "Complete production deployment"

# Auto-approve
kubiya exec team <team-id> "Security audit" --yes

Load from Saved Plan

Re-execute a previously saved plan:

# Load and execute saved plan
kubiya exec --plan-file ~/.kubiya/plans/abc123.json

# List your saved plans
ls ~/.kubiya/plans/

# View plan details
cat ~/.kubiya/plans/abc123.json | jq

Local Mode Execution

Execute tasks with an ephemeral local worker - perfect for development, testing, and experimentation.

What is Local Mode?

Local mode runs an ephemeral Python worker on your local machine to execute tasks. The CLI:

Generates a quick execution plan (simplified planning)
Creates a temporary worker queue (5-minute TTL)
Starts a Python worker in the foreground
Executes your task
Automatically cleans up the queue and worker

Key Benefits:

🆓 Free: Uses your local compute resources
🧪 Perfect for testing: Quick iterations without infrastructure setup
🎓 Learning: Experiment with agents and tasks locally
🔒 Private: Everything runs on your machine

Basic Usage

# Execute any task locally
kubiya exec --local "analyze the security of this project"

# With auto-approval
kubiya exec --local "create a hello world script" --yes

# Combine with other flags
kubiya exec --local "deploy to staging" --yes --output json

How It Works

First Run
Subsequent Runs

# First execution takes 40-120 seconds
kubiya exec --local "print hello world" --yes

# What happens:
# 1. Quick planning (simplified prompts)
# 2. Creates ephemeral queue
# 3. Installs Python dependencies (cached for future runs)
# 4. Starts worker
# 5. Executes task
# 6. Cleans up automatically

Expected time: 40-120 seconds (one-time dependency install)

# Cached runs are much faster (5-10 seconds)
kubiya exec --local "another task" --yes

# Dependencies are cached, so it only:
# 1. Quick planning
# 2. Creates ephemeral queue
# 3. Starts worker (fast startup)
# 4. Executes task
# 5. Cleans up

Expected time: 5-10 seconds (dependencies cached)

When to Use Local Mode

Development

Quick iterations and testing during development without setting up infrastructure

Learning

Experiment with Kubiya agents and tasks in a safe local environment

Demos

Show Kubiya capabilities without depending on remote infrastructure

Comparison: Local vs On-Demand vs Persistent Workers

Feature	Local Mode	On-Demand Workers	Persistent Workers
Execution Location	Your machine	Kubiya Cloud	Your infrastructure
Setup Time	Medium (first run) Fast (cached)	None	Configuration required
Best For	Dev/Testing	CI/CD/Production	High-frequency tasks
Cleanup	Automatic	Automatic	Manual
Cost	Free (your compute)	Pay per execution	Infrastructure costs
Network Access	Your machine’s network	Kubiya’s network	Your network
Custom Dependencies	Local Python env	Managed by Kubiya	Full control

Technical Details

Ephemeral Queue:

Created automatically with 5-minute TTL
Auto-deleted after execution
Isolated from other queues

Worker Lifecycle:

Runs in foreground (attached to CLI process)
Single execution mode (exits after task completion)
180-second readiness timeout
Graceful cleanup on exit or Ctrl+C

Planning Mode:

Uses “quick mode” for faster planning
Simplified LLM prompts
Optimized for local execution scenarios

Troubleshooting

Slow First Run (40-120 seconds)

This is normal! The first local execution installs Python dependencies which are then cached for subsequent runs.

# Check installation progress
kubiya exec --local "test task" --yes
# You'll see: "⏳ Installing dependencies..."
# Wait for: "✓ Dependencies installed"

Solution: Be patient on first run. Future runs will be much faster (5-10 seconds).

Worker Readiness Timeout

If the worker doesn’t become ready within 180 seconds, you’ll see a timeout error.Common causes:

Slow internet connection (dependency download)
Resource constraints on your machine
Conflicting Python installations

Solutions:

# Check your Python version
python3 --version  # Should be 3.9+

# Ensure you have enough disk space
df -h

# Try again with debug mode
export KUBIYA_DEBUG=true
kubiya exec --local "task" --yes

Port Conflicts

If you see port binding errors, another process may be using the required port.Solution:

# Check for processes on common ports
lsof -i :8080
lsof -i :3000

# Kill conflicting processes or wait for the worker to exit

Python Environment Issues

If you encounter Python-related errors:Solutions:

# Verify Python installation
which python3
python3 --version

# Clear Python cache
rm -rf ~/.kubiya/workers/*/venv

# Try again
kubiya exec --local "task" --yes

Command Syntax

# Auto-planning mode
kubiya exec "<prompt>" [OPTIONS]

# Direct execution
kubiya exec agent <agent-id> "<prompt>" [OPTIONS]
kubiya exec team <team-id> "<prompt>" [OPTIONS]

# Load from plan
kubiya exec --plan-file <path> [OPTIONS]

Options

Flag	Short	Description	Default
`--yes`	`-y`	Auto-approve without confirmation	false
`--output`	`-o`	Output format: text, json, yaml	text
`--plan-file`		Execute from saved plan file
`--save-plan`		Custom path to save plan	`~/.kubiya/plans/<id>.json`
`--non-interactive`		Skip all prompts (for CI/CD)	false
`--priority`		Task priority: low, medium, high, critical	medium
`--stream`		Stream real-time execution logs	false
`--local`		Run with ephemeral local worker	false
`--queue`		Worker queue ID(s) - repeatable for parallel execution
`--queue-name`		Worker queue name(s) - alternative to IDs
`--environment`		Environment ID for execution
`--parent-execution`		Parent execution ID for conversation continuation

Environment Variables

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

# API key
export KUBIYA_API_KEY="your-api-key"

# Debug mode
export KUBIYA_DEBUG=true

Examples

DevOps & Deployment

Production Deployment

# Auto-planning deployment
kubiya exec "Deploy version 2.5.0 to production with health checks"

# Expected output:
# ✓ Analyzing task...
# ✓ Selected agent: deployment-agent
# ✓ Plan created with 5 steps
# ✓ Estimated cost: $0.15
# ✓ Approve? (y/N): y
# ✓ Provisioning on-demand worker...
# ✓ Executing deployment...
# ✓ Deployment successful!

Rollback

# Emergency rollback
kubiya exec "Rollback production to previous version" --priority critical --yes

Staging Environment

# Deploy to staging with specific agent
kubiya exec agent staging-deployer "Deploy branch feature/auth to staging"

Infrastructure Management

Kubernetes Operations

# Scale deployment
kubiya exec "Scale the api-service deployment to 5 replicas in production"

# Check pod status
kubiya exec "Show me all failing pods in the cluster with their logs"

# Update configuration
kubiya exec "Update the database connection string in production ConfigMap"

Cloud Resources

# AWS operations
kubiya exec "List all EC2 instances in us-east-1 that are running"

# GCP operations
kubiya exec "Create a new GKE cluster in us-central1 with 3 nodes"

# Multi-cloud
kubiya exec "Compare costs across AWS and GCP for our current usage"

Security & Compliance

Security Audit

# Comprehensive security scan
kubiya exec team security-team "Run full security audit on production environment"

# Vulnerability check
kubiya exec "Scan all container images for critical vulnerabilities"

# Compliance check
kubiya exec "Verify SOC2 compliance for all resources" --output json

Access Management

# Review permissions
kubiya exec "Show all users with admin access to production"

# Rotate credentials
kubiya exec "Rotate all database credentials and update secrets"

Monitoring & Troubleshooting

Incident Response

# Quick investigation
kubiya exec "The API is returning 500 errors - investigate and fix" --priority high

# Performance analysis
kubiya exec "Why is the database slow? Analyze query performance"

# Stream logs during investigation
kubiya exec "Debug the payment service failures" --stream

Health Checks

# System health
kubiya exec "Check health of all production services and alert if issues found"

# Resource usage
kubiya exec "Show resource usage trends for the last 24 hours"

Development & Testing

Test Execution

# Run test suite
kubiya exec "Run all integration tests for the payment service"

# Automated testing
kubiya exec "Run smoke tests on staging" --yes --non-interactive

Code Quality

# Code review
kubiya exec "Analyze the latest commit for security issues and best practices"

# Performance testing
kubiya exec "Run load tests with 1000 concurrent users"

Data & Analytics

Database Operations

# Backup
kubiya exec "Run full database backup and verify integrity"

# Data migration
kubiya exec "Migrate user data from MySQL to PostgreSQL"

# Query optimization
kubiya exec "Analyze slow queries and suggest optimizations"

Reporting

# Generate report
kubiya exec "Generate monthly usage report for all teams" --output json

# Analytics
kubiya exec "Analyze user behavior trends from the last quarter"

CI/CD Integration

GitHub Actions

# .github/workflows/deploy.yml
name: Deploy with Kubiya

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Install Kubiya CLI
        run: |
          curl -fsSL https://raw.githubusercontent.com/kubiyabot/cli/main/install.sh | bash

      - name: Deploy to Production
        env:
          KUBIYA_API_KEY: ${{ secrets.KUBIYA_API_KEY }}
          KUBIYA_NON_INTERACTIVE: true
        run: |
          kubiya exec "Deploy ${{ github.sha }} to production" --yes --output json

GitLab CI

# .gitlab-ci.yml
deploy:
  stage: deploy
  script:
    - curl -fsSL https://raw.githubusercontent.com/kubiyabot/cli/main/install.sh | bash
    - export KUBIYA_NON_INTERACTIVE=true
    - kubiya exec "Deploy ${CI_COMMIT_SHA} to production" --yes
  only:
    - main

Jenkins Pipeline

// Jenkinsfile
pipeline {
    agent any
    environment {
        KUBIYA_API_KEY = credentials('kubiya-api-key')
        KUBIYA_NON_INTERACTIVE = 'true'
    }
    stages {
        stage('Deploy') {
            steps {
                sh '''
                    curl -fsSL https://raw.githubusercontent.com/kubiyabot/cli/main/install.sh | bash
                    kubiya exec "Deploy build ${BUILD_NUMBER} to production" --yes
                '''
            }
        }
    }
}

Task Planning

Understanding the Planning Process

When you use auto-planning mode, the system:

Analyzes Your Task
- Extracts intent and requirements
- Identifies needed skills and tools
- Determines complexity and risk level
Discovers Resources
- Fetches available agents and teams
- Checks agent capabilities and skills
- Evaluates team composition
Selects Best Match
- Matches task requirements to agent capabilities
- Considers agent availability and workload
- Provides reasoning for selection
Generates Plan
- Creates step-by-step execution plan
- Identifies dependencies between steps
- Adds error handling and rollback steps
Estimates Costs
- Calculates LLM token costs
- Estimates tool execution costs
- Shows total estimated cost
Requests Approval
- Displays plan summary
- Shows cost breakdown
- Waits for user confirmation (unless —yes)

Planning Modes

The planner adapts its behavior based on your execution mode:

Normal Mode
Quick Mode

Full Planning with Comprehensive AnalysisUsed by default and for on-demand worker execution:

kubiya exec "Deploy my app to production"

Characteristics:

Comprehensive LLM prompts with full context
Detailed resource discovery and matching
Complete risk analysis and prerequisites
Thorough task breakdown with dependencies
Full cost estimation with breakdown

Best For:

Production deployments
Complex multi-step workflows
Team-based executions
When you need detailed planning insights

Simplified Planning for Local ExecutionAutomatically activated with --local flag:

kubiya exec --local "Run tests" --yes

Characteristics:

Streamlined LLM prompts for faster response
Quick agent/team selection
Essential task breakdown only
Simplified cost estimation
Optimized for development workflows

Benefits:

Faster plan generation (seconds vs minutes)
Lower cost (fewer tokens)
Ideal for iterative testing
Still maintains execution quality

Best For:

Local development and testing
Quick experiments
Frequent iterations
Learning and exploration

Real-Time Progress Streaming

When running in interactive mode, the CLI streams real-time progress updates via Server-Sent Events (SSE):

🤖  Intelligent Task Planning

⏳  0% - Initializing...
⏳ 10% - 🚀 Initializing AI Task Planner...
⏳ 20% - 🔍 Discovering available resources...
⏳ 50% - ✨ Generating plan...
⏳ 30% - 🔍 Analyzing requirements and resources...
⏳ 50% - ✨ Generating comprehensive task plan...
✓  Plan generation complete

Progress Stages:

Initializing: Setting up planner context
Discovering: Fetching agents, teams, environments, queues (parallel)
Analyzing: Matching task requirements to capabilities
Generating: Creating detailed execution plan
Finalizing: Cost estimation and success criteria
Complete: Plan ready for review

Progress Events:

thinking: Planner is processing information
tool_call: Planner is calling internal tools
resources_summary: Resource discovery results
complete: Planning finished successfully
error: Planning encountered an issue

Non-Interactive Mode: Use --non-interactive or set KUBIYA_NON_INTERACTIVE=true to disable progress streaming and get direct output.

Resource Discovery

The planner performs parallel resource discovery to make intelligent recommendations: Discovery Process:

Agents Discovery: Fetches all available agents with their skills and capabilities
Teams Discovery: Retrieves team configurations and member agents
Environments Discovery: Gets environment configurations and access policies
Queue Discovery: Lists available worker queues and their status

Matching Criteria:

Task keywords → Agent/Team skills
Required tools → Agent capabilities
Complexity level → Agent experience/configuration
Availability → Agent/Queue status (running/idle)
Performance history → Previous success rates

Interactive Plan Display

When reviewing plans interactively, you can drill down into details: Display Options:

Summary View (default): High-level overview with key information
Task Breakdown: Detailed step-by-step task list with responsibilities
Cost Analysis: Detailed cost breakdown by model and tool
Risk Assessment: Full risk analysis with mitigation strategies
Dependencies: Task dependencies and execution order

Navigation:

📋  Task Execution Plan

Summary: Deploy application to production
Complexity: 5 story points (high confidence)

Recommended: DevOps Agent (deployment-expert)
Cost: $0.25 estimated

Options:
  [1] View detailed task breakdown
  [2] See cost analysis
  [3] Review risks and prerequisites
  [4] Approve and execute
  [5] Cancel

Choose an option (1-5):

Auto-Skip Interactive Menu:

Use --yes flag to skip interactive display and approve automatically
Use --non-interactive for fully automated execution
Use --output json for machine-readable output without prompts

Best Practice: Review plans interactively during development, then use --yes in production/CI/CD for automation.

Plan Storage

All plans are automatically saved for audit and repeatability:

# Plans saved to
~/.kubiya/plans/<plan-id>.json

# List your plans
ls -lh ~/.kubiya/plans/

# View plan details
cat ~/.kubiya/plans/abc123.json | jq '.'

# Re-execute a plan
kubiya exec --plan-file ~/.kubiya/plans/abc123.json

Plan Contents:

Task prompt and metadata
Selected agent/team with reasoning
Step-by-step execution plan
Cost estimates and actuals
Execution results and logs
Timestamp and duration

Plan File Format

Plans are saved as JSON files with comprehensive metadata for programmatic access and automation.

File Structure

Each plan file contains a SavedPlan object with the following structure:

{
  "plan": {
    "plan_id": "3e7ff469-7d83-4e95-9a23-39ad8dd6fbd5",
    "title": "Simple Hello World Output Task",
    "summary": "Execute a basic 'hello world' command...",
    "complexity": {
      "story_points": 1,
      "confidence": "high",
      "reasoning": "This is a simple task requiring minimal resources..."
    },
    "team_breakdown": [
      {
        "team_name": "Individual Agent",
        "agent_id": "eba459ba-dbf3-4959-9c58-2da3be6f29b5",
        "agent_name": "System Engineer",
        "responsibilities": ["Execute command", "Verify output"],
        "tasks": [
          {
            "title": "Execute Hello World Command",
            "description": "Run a simple command to output 'Hello World'",
            "status": "pending",
            "priority": "high"
          }
        ],
        "estimated_time_hours": 0.1
      }
    ],
    "recommended_execution": {
      "entity_type": "agent",
      "entity_id": "eba459ba-dbf3-4959-9c58-2da3be6f29b5",
      "entity_name": "System Engineer",
      "recommended_environment_id": "04b2ceb0-2b12-4b6a-acb2-155ce29cf975",
      "recommended_environment_name": "default",
      "recommended_worker_queue_id": "88158201-8140-42ce-abac-17fb3e81bdbf",
      "recommended_worker_queue_name": "Default Queue",
      "reasoning": "The System Engineer agent is perfect for this task..."
    },
    "cost_estimate": {
      "estimated_cost_usd": 0.013,
      "llm_costs": [
        {
          "model_id": "claude-sonnet-4",
          "estimated_input_tokens": 500,
          "estimated_output_tokens": 100,
          "cost_per_1k_input_tokens": 0.003,
          "cost_per_1k_output_tokens": 0.015,
          "total_cost": 0.003
        }
      ],
      "tool_costs": []
    },
    "realized_savings": {
      "time_saved_hours": 0.1,
      "money_saved": 9.987,
      "manual_effort_avoided": "Manual command execution"
    },
    "risks": [
      "Minimal risk - basic system operation"
    ],
    "prerequisites": [
      "Access to running worker in selected queue"
    ],
    "success_criteria": [
      "Command executes without errors",
      "Output displayed correctly"
    ],
    "created_at": "2025-12-12T07:18:26Z"
  },
  "saved_at": "2025-12-12T07:18:26.604329-08:00",
  "prompt": "print hello world",
  "approved": true,
  "approved_at": "2025-12-12T07:18:30-08:00",
  "executed_at": "2025-12-12T07:18:35-08:00",
  "execution_id": "exec-abc123-def456",
  "file_path": "/Users/you/.kubiya/plans/3e7ff469-7d83-4e95-9a23-39ad8dd6fbd5.json"
}

Field Reference

Top-Level Fields:

plan (object): The complete plan response from the planner
saved_at (timestamp): When the plan was saved locally
prompt (string): Original user prompt that generated the plan
approved (boolean): Whether user approved the plan
approved_at (timestamp, optional): When plan was approved
executed_at (timestamp, optional): When plan was executed
execution_id (string, optional): Associated execution identifier
file_path (string): Full path to the plan file

Plan Object Fields:

plan_id (string): Unique identifier for the plan
title (string): Human-readable plan title
summary (string): Detailed plan description
complexity (object): Effort estimation
- story_points (number): Estimated complexity (1-13)
- confidence (string): Confidence level (low/medium/high)
- reasoning (string): Explanation of complexity assessment
team_breakdown (array): Execution phases and task assignments
recommended_execution (object): Planner’s execution recommendation
- entity_type (string): “agent” or “team”
- entity_id (string): ID of recommended agent/team
- entity_name (string): Name of recommended entity
- recommended_environment_id (string): Environment to use
- recommended_worker_queue_id (string): Queue to use
- reasoning (string): Why this entity was selected
cost_estimate (object): Financial cost breakdown
- estimated_cost_usd (number): Total estimated cost in USD
- llm_costs (array): Per-model cost breakdown
- tool_costs (array): Per-tool cost breakdown
realized_savings (object): Value generated
- time_saved_hours (number): Estimated time saved
- money_saved (number): Estimated cost saved vs manual work
risks (array): Identified risks and concerns
prerequisites (array): Requirements before execution
success_criteria (array): Conditions for successful completion

Programmatic Usage

Extract Fields
List Plans
Automation
Analysis

# Get recommended agent/team
jq '.plan.recommended_execution.entity_name' plan.json

# Get cost estimate
jq '.plan.cost_estimate.estimated_cost_usd' plan.json

# Get complexity
jq '.plan.complexity.story_points' plan.json

# Check if approved
jq '.approved' plan.json

# Get execution ID if executed
jq '.execution_id' plan.json

# List all plans with status
for file in ~/.kubiya/plans/*.json; do
  name=$(basename "$file")
  approved=$(jq -r '.approved' "$file")
  executed=$(jq -r '.executed_at != null' "$file")
  echo "$name - Approved: $approved, Executed: $executed"
done

# Find unapproved plans
jq -r 'select(.approved == false) | .file_path' ~/.kubiya/plans/*.json

# Find plans by agent
jq -r 'select(.plan.recommended_execution.entity_name == "System Engineer") | .file_path' ~/.kubiya/plans/*.json

# Auto-execute all approved but unexecuted plans
for file in ~/.kubiya/plans/*.json; do
  approved=$(jq -r '.approved' "$file")
  executed=$(jq -r '.executed_at' "$file")

  if [ "$approved" = "true" ] && [ "$executed" = "null" ]; then
    echo "Executing plan: $file"
    kubiya exec --plan-file "$file" --yes
  fi
done

# Generate report of all executions
jq -s 'map({
  plan_id: .plan.plan_id,
  title: .plan.title,
  cost: .plan.cost_estimate.estimated_cost_usd,
  executed: .executed_at,
  execution_id: .execution_id
})' ~/.kubiya/plans/*.json

# Calculate total estimated costs
jq -s 'map(.plan.cost_estimate.estimated_cost_usd) | add' ~/.kubiya/plans/*.json

# Find most complex plans
jq -s 'sort_by(.plan.complexity.story_points) | reverse | .[0:5] |
  map({title: .plan.title, points: .plan.complexity.story_points})' ~/.kubiya/plans/*.json

# Analyze savings
jq -s 'map(.plan.realized_savings.money_saved) | add' ~/.kubiya/plans/*.json

CI/CD Integration: Use plan files to version control your automation workflows and execute them consistently across environments.

On-Demand Workers

What are On-Demand Workers?

On-demand workers let you run AI tasks without needing a queue in advance - perfect for CI/CD pipelines! When you use kubiya exec, the Control Plane creates an ephemeral worker queue specifically for your execution, provisions a worker on managed infrastructure, runs your task, and automatically cleans everything up. Benefits:

✓ No queue setup needed - run tasks instantly without pre-configuring queues
✓ Perfect for CI/CD - integrate into pipelines without infrastructure management
✓ Auto-cleanup - queue and worker automatically removed after execution
✓ Cost-effective - pay only for execution time
✓ Secure - isolated ephemeral environments
✓ Fully managed - handled by Kubiya Control Plane

How It Works

When to Use On-Demand vs Persistent Workers

On-Demand Workers

Best for:

Occasional tasks
One-off operations
CI/CD pipelines
Development/testing
Cost optimization

Advantages:

Zero setup
Auto-scaling
Cost-effective
Latest versions

Persistent Workers

Best for:

High-frequency tasks
Real-time monitoring
Custom compute environments
Specific network access
Low-latency needs

Advantages:

Faster execution
Run on any infrastructure
Custom configuration
Persistent state

Can run on:

Your local machine (Mac, Linux, Windows)
Kubernetes clusters
Docker containers
VMs (EC2, GCE, Azure)
Bare metal servers

Worker Flexibility: Persistent workers can run on nearly any compute environment, making them incredibly powerful and easy to deploy wherever your infrastructure lives!

Output Formats

Text Output (Default)

Human-readable output with formatting:

kubiya exec "List production pods"

✓ Analyzing task...
✓ Selected agent: kubernetes-agent
✓ Plan created with 3 steps
✓ Estimated cost: $0.08

Execution Results:
==================

NAME                          READY   STATUS    RESTARTS   AGE
api-service-7d9f8b-5xk2p     1/1     Running   0          5d
database-8c4f9d-2vn7q        1/1     Running   0          10d
frontend-6b3c8a-9km4t        1/1     Running   0          3d

JSON Output

Machine-readable output for automation:

kubiya exec "List production pods" --output json

{
  "execution_id": "exec-abc123",
  "status": "completed",
  "agent": {
    "id": "kubernetes-agent",
    "name": "Kubernetes Agent"
  },
  "plan": {
    "steps": 3,
    "estimated_cost": 0.08,
    "actual_cost": 0.07
  },
  "results": {
    "pods": [
      {
        "name": "api-service-7d9f8b-5xk2p",
        "ready": "1/1",
        "status": "Running",
        "restarts": 0,
        "age": "5d"
      }
    ]
  },
  "duration_seconds": 4.2
}

YAML Output

Kubernetes-friendly output:

kubiya exec "Get pod details" --output yaml

execution_id: exec-abc123
status: completed
agent:
  id: kubernetes-agent
  name: Kubernetes Agent
results:
  pods:
    - name: api-service-7d9f8b-5xk2p
      ready: 1/1
      status: Running
      restarts: 0
      age: 5d

Best Practices

Task Prompts

Be specific: “Deploy version 2.5.0 to production with health checks” vs “deploy”

Include context: “Scale api-service to 5 replicas in production” vs “scale service”

Specify environment: “Run tests on staging” vs “run tests”

Add constraints: “Deploy during maintenance window (2-4am UTC)” vs “deploy now”

Error Handling

Check plan before approving: Review steps and cost estimates
Use —stream for long tasks: Monitor progress in real-time
Save important plans: Use —save-plan for repeatability
Set appropriate priority: Use —priority for critical tasks

Cost Optimization

Use on-demand workers: No infrastructure costs
Auto-approve simple tasks: Skip confirmation with —yes
Batch similar operations: Combine related tasks in one prompt
Monitor costs: Review estimated vs actual costs in plans

Security

Review plan steps: Ensure no unintended actions
Use policies: Enforce compliance with OPA policies
Rotate credentials: Don’t hardcode secrets in prompts
Audit executions: Review saved plans and execution logs

Troubleshooting

”No suitable agent found”

Problem: Planner couldn’t find an agent with required skills Solution:

# Check available agents
kubiya agent list

# Check agent skills
kubiya agent get <agent-id>

# Execute with specific agent
kubiya exec agent <agent-id> "your task"

“Plan approval timeout”

Problem: User didn’t approve plan within timeout Solution:

# Use auto-approve for trusted tasks
kubiya exec "task" --yes

# Or set non-interactive mode
export KUBIYA_NON_INTERACTIVE=true
kubiya exec "task"

“Worker provisioning failed”

Problem: Failed to provision on-demand worker Solution:

# Check Control Plane status
kubiya worker status

# Try with persistent worker
kubiya worker start --queue my-queue
kubiya exec agent <agent-id> "task" --queue my-queue

“Execution timeout”

Problem: Task took longer than expected Solution:

# Check execution status
kubiya execution status <execution-id>

# View logs
kubiya execution logs <execution-id> --follow

# Cancel if needed
kubiya execution cancel <execution-id>

Command Reference

# Auto-planning mode
kubiya exec "<prompt>"
kubiya exec "<prompt>" --yes
kubiya exec "<prompt>" --output json
kubiya exec "<prompt>" --priority high

# Direct execution
kubiya exec agent <agent-id> "<prompt>"
kubiya exec team <team-id> "<prompt>"
kubiya exec agent <agent-id> "<prompt>" --stream

# Load from plan
kubiya exec --plan-file <path>
kubiya exec --plan-file ~/.kubiya/plans/abc123.json --yes

# Options
--yes, -y                  Auto-approve without confirmation
--output, -o FORMAT        Output format: text, json, yaml
--plan-file PATH           Execute from saved plan file
--save-plan PATH           Custom path to save plan
--non-interactive          Skip all prompts (for CI/CD)
--priority LEVEL           Task priority: low, medium, high, critical
--stream                   Stream real-time execution logs

Next Steps

Core Resources

Manage agents, teams, and projects

Execution Resources

Monitor executions and schedule jobs

Workers

Set up persistent workers

Workflows

Execute automated workflows

Getting Started

Core Commands

Resource Management

Advanced

​Overview

​Key Features

​Quick Start

​Execute with On-Demand Worker (Easiest)

​Execution Modes

​Auto-Planning Mode (Recommended)

​Direct Execution Mode

​Load from Saved Plan

​Local Mode Execution

​What is Local Mode?

​Basic Usage

​How It Works

​When to Use Local Mode

Development

Learning

Demos

​Comparison: Local vs On-Demand vs Persistent Workers

​Technical Details

​Troubleshooting

​Command Syntax

​Options

​Environment Variables

​Examples

​DevOps & Deployment

​Infrastructure Management

​Security & Compliance

​Monitoring & Troubleshooting

​Development & Testing

​Data & Analytics

​CI/CD Integration

​Task Planning

​Understanding the Planning Process

​Planning Modes

​Real-Time Progress Streaming

​Resource Discovery

​Interactive Plan Display

​Plan Storage

​Plan File Format

​File Structure

​Field Reference

​Programmatic Usage

​On-Demand Workers

​What are On-Demand Workers?

​How It Works

​When to Use On-Demand vs Persistent Workers

On-Demand Workers

Persistent Workers

​Output Formats

​Text Output (Default)

​JSON Output

​YAML Output

​Best Practices

​Task Prompts

​Error Handling

​Cost Optimization

​Security

​Troubleshooting

​”No suitable agent found”

​“Plan approval timeout”

​“Worker provisioning failed”

​“Execution timeout”

​Command Reference

​Next Steps

Core Resources

Execution Resources

Workers

Workflows

Overview

Key Features

Quick Start

Execute with On-Demand Worker (Easiest)

Execution Modes

Auto-Planning Mode (Recommended)

Direct Execution Mode

Load from Saved Plan

Local Mode Execution

What is Local Mode?

Basic Usage

How It Works

When to Use Local Mode

Comparison: Local vs On-Demand vs Persistent Workers

Technical Details

Troubleshooting

Command Syntax

Options

Environment Variables

Examples

DevOps & Deployment

Infrastructure Management

Security & Compliance

Monitoring & Troubleshooting

Development & Testing

Data & Analytics

CI/CD Integration

Task Planning

Understanding the Planning Process

Planning Modes

Real-Time Progress Streaming

Resource Discovery

Interactive Plan Display

Plan Storage

Plan File Format

File Structure

Field Reference

Programmatic Usage

On-Demand Workers

What are On-Demand Workers?

How It Works

When to Use On-Demand vs Persistent Workers

Output Formats

Text Output (Default)

JSON Output

YAML Output

Best Practices

Task Prompts

Error Handling

Cost Optimization

Security

Troubleshooting

”No suitable agent found”

“Plan approval timeout”

“Worker provisioning failed”

“Execution timeout”

Command Reference

Next Steps