Skip to main content
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: 
# 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

Smart Execution

Execute tasks with automatic agent selection, task planning, and on-demand workers - no setup required

Resource Management

Full CRUD operations for agents, teams, executions, jobs, skills, models, policies, and environments

Worker Deployment

Deploy persistent Temporal workers for high-frequency tasks with enterprise-grade reliability

Context Graph

Query Neo4j-based organizational knowledge with Cypher queries

​
Architecture

The Kubiya CLI integrates seamlessly with the Kubiya Control Plane:

​
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: 
# 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!

​
2. On-Demand Workers

Run tasks without pre-configuring queues - perfect for CI/CD and automation: 
# 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"
Ephemeral Workers: Perfect for CI/CD, automation, and development. Auto-provision, execute, and clean up automatically.

​
3. Persistent Workers

Deploy long-running workers for high-frequency tasks. Run on any compute environment - local, cloud VMs, Kubernetes, Docker: 
# 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
When to Use: High-frequency operations, real-time monitoring, custom infrastructure, low-latency requirements. For occasional tasks, use ephemeral workers instead.

​
4. Agent & Resource Management

# 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

# 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

# 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

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

Installation

Install the CLI on macOS, Linux, Windows, or Docker

Authentication

Configure API keys and connect to the Control Plane

Smart Execution

Execute tasks with automatic planning

Resource Management

Manage agents, teams, and all resources

​
Quick Reference

​
Installation

# 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

# Interactive login (recommended)
kubiya login

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

# Verify installation
kubiya agent list

​
Core Commands

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

# Start persistent worker
kubiya worker start --queue my-queue

# Check status
kubiya worker status

# View logs
kubiya worker logs --follow

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

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

# 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

# Graph statistics
kubiya graph stats

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

# Search nodes
kubiya graph search "kubernetes pods"

​
Next Steps

Installation

Install and verify the CLI

Smart Execution

Execute with automatic planning

Worker Management

Deploy and manage workers

Core Resources

Manage agents, teams, and projects

Execution Resources

Manage executions, jobs, and workers

Authentication

Configure API keys