CLI Overview - Kubiya

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

Control Plane Integration
- Authenticate with API keys via kubiya login
- Manage all platform resources
- Configure environments and policies
Smart Execution
- Auto-planning with agent/team selection
- On-demand worker provisioning
- Cost estimation and plan storage
Worker Management
- Start local, Docker, or Kubernetes workers
- Monitor worker health and logs
- Configure execution environments
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:

Production Deployment
Local Development
CI/CD Automation

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

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

# GitHub Actions, GitLab CI, Jenkins
kubiya exec "Deploy ${BUILD_VERSION}" \
  --yes \
  --non-interactive \
  --output json

# Perfect for pipelines - zero infrastructure setup

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

Task Execution (Primary)

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

Worker Management

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

# Check status
kubiya worker status

# View logs
kubiya worker logs --follow

Agent Management

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

Execution Tracking

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

Resource Management

# 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

Context Graph

# 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

​What is the Kubiya CLI?

​Primary Use Case: Smart Task Execution

​Full Platform Access

​Key Capabilities

Smart Execution

Resource Management

Worker Deployment

Context Graph

​Architecture

​Core Components

​Common Use Cases

​1. Smart Task Execution (Primary)

​2. On-Demand Workers

​3. Persistent Workers

​4. Agent & Resource Management

​Job Scheduling

​Context Graph Queries

​CI/CD Integration

​Platform Integration

​Getting Started

Installation

Authentication

Smart Execution

Resource Management

​Quick Reference

​Installation

​Authentication

​Core Commands

​Next Steps

Installation

Smart Execution

Worker Management

Core Resources

Execution Resources

Authentication

What is the Kubiya CLI?

Primary Use Case: Smart Task Execution

Full Platform Access

Key Capabilities

Architecture

Core Components

Common Use Cases

1. Smart Task Execution (Primary)

2. On-Demand Workers

3. Persistent Workers

4. Agent & Resource Management

Job Scheduling

Context Graph Queries

CI/CD Integration

Platform Integration

Getting Started

Quick Reference

Installation

Authentication

Core Commands

Next Steps