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

# CLI Overview

> Introduction to the Kubiya CLI - your command-line interface for AI-powered automation

The Kubiya CLI is a comprehensive command-line interface that empowers you to build, deploy, and manage AI-powered automation from your terminal. Whether you're managing infrastructure, orchestrating agents, or executing complex tasks, the CLI provides full control over the Kubiya Control Plane.

## What is the Kubiya CLI?

The Kubiya CLI is your command-line interface to Kubiya's AI automation platform. Execute tasks, manage agents, and automate workflows - all from your terminal.

### Primary Use Case: Smart Task Execution

The `kubiya exec` command is your main interface to Kubiya:

```bash theme={null}
# Execute any task with automatic planning
kubiya exec "Deploy my app to production"

# Local development mode
kubiya exec --local "Run tests" --yes

# CI/CD automation
kubiya exec "Deploy version 2.0" --yes --non-interactive
```

**What Makes It Powerful:**

* 🤖 **Automatic Agent Selection**: Analyzes your task and picks the best agent
* 📋 **Intelligent Planning**: Creates detailed execution plans with cost estimates
* ⚡ **Zero Setup**: On-demand workers provision automatically
* 💰 **Cost Transparent**: Shows estimated costs before execution
* 📦 **Plan Storage**: All plans saved for audit and repeatability

### Full Platform Access

Beyond execution, the CLI provides complete control over the Kubiya platform:

* **Resource Management**: Create and configure agents, teams, jobs, skills, policies
* **Worker Deployment**: Run on your infrastructure or use ephemeral workers
* **Agent Interaction**: Chat with AI agents directly from your terminal
* **Context Graph**: Query organizational knowledge stored in Neo4j
* **Policy Enforcement**: Implement OPA-based security and compliance

## Key Capabilities

<CardGroup cols={2}>
  <Card title="Smart Execution" icon="bolt">
    Execute tasks with automatic agent selection, task planning, and on-demand workers - no setup required
  </Card>

  <Card title="Resource Management" icon="cube">
    Full CRUD operations for agents, teams, executions, jobs, skills, models, policies, and environments
  </Card>

  <Card title="Worker Deployment" icon="server">
    Deploy persistent Temporal workers for high-frequency tasks with enterprise-grade reliability
  </Card>

  <Card title="Context Graph" icon="diagram-project">
    Query Neo4j-based organizational knowledge with Cypher queries
  </Card>
</CardGroup>

## Architecture

The Kubiya CLI integrates seamlessly with the Kubiya Control Plane:

```mermaid theme={null}
graph TB
    CLI[💻 Kubiya CLI]
    CP[🎯 Control Plane]
    Temporal[⚡ Temporal Cloud]
    Worker[🔧 Workers]
    Agent[🤖 AI Agents]
    Graph[(📊 Context Graph)]

    CLI -->|API Calls| CP
    CLI -->|Manages| Worker
    CP -->|Orchestrates| Temporal
    Temporal -->|Distributes Tasks| Worker
    Worker -->|Executes| Agent
    Agent -->|Queries| Graph
    CP -->|Updates| Graph

    style CLI fill:#2196F3,color:#fff
    style CP fill:#4CAF50,color:#fff
    style Worker fill:#FF9800,color:#fff
    style Agent fill:#9C27B0,color:#fff
    style Graph fill:#00BCD4,color:#fff
```

### Core Components

1. **Control Plane Integration**
   * Authenticate with API keys via `kubiya login`
   * Manage all platform resources
   * Configure environments and policies

2. **Smart Execution**
   * Auto-planning with agent/team selection
   * On-demand worker provisioning
   * Cost estimation and plan storage

3. **Worker Management**
   * Start local, Docker, or Kubernetes workers
   * Monitor worker health and logs
   * Configure execution environments

4. **Resource Operations**
   * Agents, teams, and projects
   * Jobs and executions
   * Skills, models, and policies
   * Environments and context graph

## Common Use Cases

### 1. Smart Task Execution (Primary)

The `kubiya exec` command is your go-to for executing any task with automatic planning:

<Tabs>
  <Tab title="Production Deployment">
    ```bash theme={null}
    # Full planning with cost estimates and approval
    kubiya exec "Deploy version 2.5.0 to production"

    # What happens:
    # 1. Analyzes task → selects best agent
    # 2. Creates execution plan → shows costs
    # 3. You approve → provisions worker
    # 4. Executes task → shows results
    # 5. Auto-cleanup → done!
    ```
  </Tab>

  <Tab title="Local Development">
    ```bash theme={null}
    # Run locally for dev/test (uses your machine)
    kubiya exec --local "Run integration tests" --yes

    # Fast iterations with cached dependencies
    kubiya exec --local "Analyze code quality"
    ```
  </Tab>

  <Tab title="CI/CD Automation">
    ```bash theme={null}
    # GitHub Actions, GitLab CI, Jenkins
    kubiya exec "Deploy ${BUILD_VERSION}" \
      --yes \
      --non-interactive \
      --output json

    # Perfect for pipelines - zero infrastructure setup
    ```
  </Tab>
</Tabs>

### 2. On-Demand Workers

Run tasks without pre-configuring queues - perfect for CI/CD and automation:

```bash theme={null}
# Zero setup needed - worker auto-provisions
kubiya exec "Rollback to version 2.4.0" --yes

# Ephemeral execution with automatic cleanup
kubiya exec --local "Test new feature"
```

<Info>
  **Ephemeral Workers**: Perfect for CI/CD, automation, and development. Auto-provision, execute, and clean up automatically.
</Info>

### 3. Persistent Workers

Deploy long-running workers for high-frequency tasks. Run on **any compute environment** - local, cloud VMs, Kubernetes, Docker:

```bash theme={null}
# Start persistent worker on your infrastructure
kubiya worker start --queue prod-queue

# Or install + start in one command (daemon mode)
curl -fsSL https://raw.githubusercontent.com/kubiyabot/cli/main/install.sh | bash -s -- \
  --worker --queue-id=prod-queue --mode=daemon --start
```

<Tip>
  **When to Use**: High-frequency operations, real-time monitoring, custom infrastructure, low-latency requirements. For occasional tasks, use ephemeral workers instead.
</Tip>

### 4. Agent & Resource Management

```bash theme={null}
# List agents
kubiya agent list

# Create an agent
kubiya agent create --file agent.yaml

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

# Chat with an agent
kubiya agent chat <agent-id>
```

### Job Scheduling

```bash theme={null}
# Create scheduled job
kubiya job create --file job.yaml

# Trigger job manually
kubiya job trigger <job-id>

# List jobs
kubiya job list
```

### Context Graph Queries

```bash theme={null}
# View graph statistics
kubiya graph stats

# Query with Cypher
kubiya graph query --query "MATCH (a:Agent)-[:HAS_SKILL]->(s:Skill) RETURN a.name, s.name"

# List integrations
kubiya graph integrations list
```

### CI/CD Integration

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

## Platform Integration

The CLI provides complete access to Kubiya Control Plane features:

* **Control Plane**: Full API access to all resources
* **Task Queues**: Manage distributed task execution
* **Context Graph**: Query and utilize Neo4j-based organizational knowledge
* **Policies**: Enforce OPA-based governance
* **On-Demand Workers**: Zero-setup execution with auto-provisioned workers
* **Temporal**: Enterprise-grade workflow orchestration

## Getting Started

Ready to start using the Kubiya CLI? Follow these guides:

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/cli/installation">
    Install the CLI on macOS, Linux, Windows, or Docker
  </Card>

  <Card title="Authentication" icon="key" href="/cli/authentication">
    Configure API keys and connect to the Control Plane
  </Card>

  <Card title="Smart Execution" icon="bolt" href="/cli/exec">
    Execute tasks with automatic planning
  </Card>

  <Card title="Resource Management" icon="cube" href="/cli/core-resources">
    Manage agents, teams, and all resources
  </Card>
</CardGroup>

## Quick Reference

### Installation

```bash theme={null}
# macOS/Linux (one-liner)
curl -fsSL https://raw.githubusercontent.com/kubiyabot/cli/main/install.sh | bash

# macOS (Homebrew)
brew install kubiyabot/kubiya/kubiya

# With worker setup
curl -fsSL https://raw.githubusercontent.com/kubiyabot/cli/main/install.sh | bash -s -- \
  --worker --queue-id=my-queue --start
```

### Authentication

```bash theme={null}
# Interactive login (recommended)
kubiya login

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

# Verify installation
kubiya agent list
```

### Core Commands

<AccordionGroup>
  <Accordion title="Task Execution (Primary)" icon="bolt">
    ```bash theme={null}
    # Auto-planning with on-demand workers
    kubiya exec "Deploy to production"
    kubiya exec "task" --yes --output json

    # Local ephemeral execution
    kubiya exec --local "Run tests" --yes

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

    # Direct execution with specific agent/team
    kubiya exec agent <agent-id> "Run tests"
    kubiya exec team <team-id> "Complex task"
    ```
  </Accordion>

  <Accordion title="Worker Management" icon="server">
    ```bash theme={null}
    # Start persistent worker
    kubiya worker start --queue my-queue

    # Check status
    kubiya worker status

    # View logs
    kubiya worker logs --follow
    ```
  </Accordion>

  <Accordion title="Agent Management" icon="robot">
    ```bash theme={null}
    # List agents
    kubiya agent list

    # Get agent details
    kubiya agent get <agent-id>

    # Create agent
    kubiya agent create --file agent.yaml

    # Chat with agent
    kubiya agent chat <agent-id>
    ```
  </Accordion>

  <Accordion title="Execution Tracking" icon="list-check">
    ```bash theme={null}
    # List executions
    kubiya execution list --status running

    # Get execution details
    kubiya execution get <execution-id>

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

    # Cancel execution
    kubiya execution cancel <execution-id>
    ```
  </Accordion>

  <Accordion title="Resource Management" icon="database">
    ```bash theme={null}
    # Teams
    kubiya team list
    kubiya team create --file team.yaml

    # Jobs (scheduled)
    kubiya job list
    kubiya job create --file job.yaml

    # Skills
    kubiya skill list
    kubiya skill create --file skill.yaml

    # Policies
    kubiya policy list
    kubiya policy create --file policy.yaml
    ```
  </Accordion>

  <Accordion title="Context Graph" icon="diagram-project">
    ```bash theme={null}
    # Graph statistics
    kubiya graph stats

    # Cypher query
    kubiya graph query --query "MATCH (n) RETURN n LIMIT 10"

    # Search nodes
    kubiya graph search "kubernetes pods"
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={3}>
  <Card title="Installation" icon="download" href="/cli/installation">
    Install and verify the CLI
  </Card>

  <Card title="Smart Execution" icon="bolt" href="/cli/exec">
    Execute with automatic planning
  </Card>

  <Card title="Worker Management" icon="server" href="/cli/workers">
    Deploy and manage workers
  </Card>

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

  <Card title="Execution Resources" icon="play" href="/cli/execution-resources">
    Manage executions, jobs, and workers
  </Card>

  <Card title="Authentication" icon="key" href="/cli/authentication">
    Configure API keys
  </Card>
</CardGroup>