Kubiya CLI Reference

The Kubiya CLI is a comprehensive command-line interface for managing the full Kubiya platform, including Serverless Agents, Serverless Tools, Local Runners, Policy Management, and MCP Server functionality.

🚀 Installation

# Install Kubiya CLI (zero dependencies)
curl -fsSL https://raw.githubusercontent.com/kubiyabot/cli/main/install.sh | bash

# Verify installation
kubiya --version

# Set your API key
export KUBIYA_API_KEY="kb-your-api-key-here"

🎯 Global Options

These options work with all commands:

Option	Description
`--help, -h`	Show help message
`--version`	Show version information
`--config`	Custom config file path
`--api-key`	Override API key
`--api-url`	Override API endpoint

🤖 Agent Management

Manage serverless AI agents with conversational capabilities.

kubiya agent list

List all available agents in your organization.

kubiya agent list [OPTIONS]

Options:

--output, -o: Output format (text, json, yaml)
--limit: Maximum number of results (default: 50)

Example:

# List all agents
kubiya agent list

# JSON output
kubiya agent list --output json

kubiya agent describe

Get detailed information about a specific agent.

kubiya agent describe [AGENT_NAME] [OPTIONS]

Example:

kubiya agent describe devops-assistant --output yaml

🛠️ Tool Management

Execute and manage serverless container-based tools.

kubiya tool list

List available tools from all sources.

kubiya tool list [OPTIONS]

Options:

--source: Filter by source UUID
--output, -o: Output format (text, json, yaml)

Example:

# List all tools
kubiya tool list

# List tools from specific source
kubiya tool list --source abc-123-def

kubiya tool exec

Execute a tool with live streaming output.

kubiya tool exec [OPTIONS]

Options:

--name: Tool name (required)
--runner: Runner to use (auto, default, or specific runner)
--content: Tool content/script
--type: Tool type (docker, python, bash, etc.)
--image: Docker image
--args: Tool arguments in KEY=VALUE format
--env: Environment variables in KEY=VALUE format
--integration: Integration templates to apply
--with-file: File mappings in source:destination format
--with-volume: Volume mappings
--timeout: Execution timeout in seconds
--skip-policy-check: Skip policy validation
--json: Tool definition as JSON
--json-file: Tool definition from JSON file

Examples:

# Execute a simple bash tool
kubiya tool exec --name "hello" --content "echo Hello World"

# Execute with Docker image
kubiya tool exec --name "python-script" --type docker --image python:3.11 \
  --content "print('Hello from Python')"

# Execute with integrations
kubiya tool exec --name "k8s-pods" --content "kubectl get pods -A" \
  --integration k8s/incluster

# Execute with AWS credentials
kubiya tool exec --name "aws-s3" --content "aws s3 ls" \
  --integration aws/creds

# Execute from JSON file
kubiya tool exec --json-file ./my-tool.json

# Skip policy validation
kubiya tool exec --name "test" --content "date" --skip-policy-check

kubiya tool search

Search for tools across all sources.

kubiya tool search [QUERY] [OPTIONS]

Example:

kubiya tool search "kubernetes deployment"

kubiya tool describe

Get detailed information about a specific tool.

kubiya tool describe [TOOL_NAME] [OPTIONS]

🏃 Runner Management

Manage execution infrastructure and monitor health.

kubiya runner list

List all available runners.

kubiya runner list [OPTIONS]

Options:

--output, -o: Output format
--health: Filter by health status

Example:

# List all runners with health status
kubiya runner list --output json

kubiya runner describe

Get detailed runner information including health metrics.

kubiya runner describe [RUNNER_NAME]

kubiya runner create

Create a new runner deployment.

kubiya runner create [OPTIONS]

Options:

--name: Runner name (required)
--type: Runner type
--description: Runner description

🔄 Workflow Management

Execute workflows from YAML or JSON files with comprehensive control.

kubiya workflow execute

Execute a workflow from a file (supports both YAML and JSON with auto-detection).

kubiya workflow execute [WORKFLOW_FILE] [OPTIONS]

Options:

--runner: Runner to use for execution
--var: Workflow variables in KEY=VALUE format
--watch, -w: Watch execution output (default: true)
--skip-policy-check: Skip policy validation

Examples:

# Execute YAML workflow
kubiya workflow execute deploy.yaml

# Execute JSON workflow
kubiya workflow execute backup.json

# Execute with variables
kubiya workflow execute deploy.yaml --var env=production --var version=2.1.0

# Execute with specific runner
kubiya workflow execute migrate.json --runner prod-runner

# Skip policy validation
kubiya workflow execute deploy.yaml --skip-policy-check

kubiya workflow test

Test a workflow by executing it with validation.

kubiya workflow test [WORKFLOW_FILE] [OPTIONS]

Options:

--runner: Runner for testing
--var: Test variables

Examples:

# Test YAML workflow
kubiya workflow test my-workflow.yaml

# Test JSON workflow
kubiya workflow test my-workflow.json

# Test with variables
kubiya workflow test backup.yaml --var env=staging

kubiya workflow generate

Generate workflows from natural language descriptions.

kubiya workflow generate [DESCRIPTION] [OPTIONS]

kubiya workflow compose

Compose and execute workflows from natural language.

kubiya workflow compose [DESCRIPTION] [OPTIONS]

🛡️ Policy Management (OPA)

Comprehensive Open Policy Agent (OPA) integration for access control.

kubiya policy list

List all OPA policies.

kubiya policy list [OPTIONS]

Options:

--output, -o: Output format (text, json)

kubiya policy create

Create a new OPA policy.

kubiya policy create [OPTIONS]

Options:

--name, -n: Policy name (required)
--env, -e: Target environments (comma-separated)
--file, -f: Policy file path
--policy, -p: Policy content directly
--validate: Validate policy before creating (default: true)

Example:

# Create from file
kubiya policy create --name "prod-access" --env "production" --file policy.rego

# Create with inline policy
kubiya policy create --name "dev-access" --policy "package tools; allow = true"

kubiya policy get

Get details of a specific policy.

kubiya policy get [POLICY_NAME] [OPTIONS]

kubiya policy update

Update an existing policy.

kubiya policy update [POLICY_NAME] [OPTIONS]

kubiya policy delete

Delete a policy.

kubiya policy delete [POLICY_NAME] [OPTIONS]

Options:

--confirm: Confirm deletion

kubiya policy validate

Validate a policy without creating it.

kubiya policy validate [OPTIONS]

kubiya policy test-tool

Test tool execution permissions.

kubiya policy test-tool [OPTIONS]

Options:

--tool, -t: Tool name (required)
--args: Tool arguments as JSON
--args-file: Tool arguments from file
--runner, -r: Runner name

Example:

kubiya policy test-tool --tool kubectl --args '{"command": "get pods"}' --runner prod

kubiya policy test-workflow

Test workflow execution permissions.

kubiya policy test-workflow [OPTIONS]

Options:

--file, -f: Workflow definition file (required)
--params: Workflow parameters as JSON
--runner, -r: Runner name

🔧 MCP Server

Model Context Protocol server for AI integration.

kubiya mcp serve

Start the MCP server for AI assistant integration.

kubiya mcp serve [OPTIONS]

Options:

--allow-platform-apis: Enable platform management tools
--config: Configuration file path
--port: Server port (for HTTP mode)
--host: Server host (for HTTP mode)

Examples:

# Basic MCP server (stdio)
kubiya mcp serve

# With platform APIs enabled
kubiya mcp serve --allow-platform-apis

# With policy enforcement
KUBIYA_OPA_ENFORCE=true kubiya mcp serve

# Custom configuration
kubiya mcp serve --config ~/.kubiya/mcp-config.json

kubiya mcp setup

Setup MCP integration for various AI assistants.

kubiya mcp setup [ASSISTANT] [OPTIONS]

Supported assistants:

claude: Claude Desktop
cursor: Cursor IDE
vscode: VS Code (Continue extension)
custom: Custom integration

📚 Knowledge Management

Manage and query the organizational knowledge base.

kubiya knowledge query

Query the knowledge base with intelligent search.

kubiya knowledge query [QUERY] [OPTIONS]

Options:

--limit: Maximum results
--output, -o: Output format

🔗 Source Management

Manage tool sources and repositories.

kubiya source list

List all tool sources.

kubiya source list [OPTIONS]

kubiya source add

Add a new tool source.

kubiya source add [URL] [OPTIONS]

kubiya source discover

Discover tools in a source without adding it.

kubiya source discover [URL] [OPTIONS]

🔑 Secrets Management

Manage secrets and credentials securely.

kubiya secret list

List available secrets.

kubiya secret list [OPTIONS]

🎮 Interactive Mode

kubiya browse

Interactive browser for sources and tools.

kubiya browse

kubiya chat

Interactive chat mode with AI agents.

kubiya chat [OPTIONS]

Options:

--agent: Specific agent to chat with
--interactive: Enable interactive mode

🔧 Configuration

Environment Variables

Variable	Description	Default
`KUBIYA_API_KEY`	Required - Your Kubiya API key	None
`KUBIYA_API_URL`	Kubiya API endpoint	`https://api.kubiya.ai`
`KUBIYA_DEFAULT_RUNNER`	Default runner for tool execution	`auto`
`KUBIYA_OPA_ENFORCE`	Enable policy enforcement	`false`
`KUBIYA_TOOL_TIMEOUT`	Default tool timeout in seconds	`300`
`KUBIYA_TOOL_OUTPUT_FORMAT`	Default output format	`text`
`KUBIYA_SKIP_HEALTH_CHECK`	Skip runner health checks	`false`

Configuration File

The CLI stores configuration in ~/.kubiya/config.yaml:

api_key: kb-your-api-key
api_url: https://api.kubiya.ai  
default_runner: auto
log_level: info
output_format: text

MCP Server Configuration

MCP server configuration in ~/.kubiya/mcp-server.json:

{
  "allow_platform_apis": true,
  "enable_opa_policies": true,
  "enable_runners": true,
  "whitelisted_tools": [
    {
      "name": "Safe kubectl",
      "tool_name": "kubectl",
      "description": "Read-only Kubernetes access", 
      "integrations": ["k8s/readonly"]
    }
  ]
}

🚀 Common Workflows

1. Setting up MCP for Claude Desktop

# 1. Install Kubiya CLI
curl -fsSL https://raw.githubusercontent.com/kubiyabot/cli/main/install.sh | bash

# 2. Set API key
export KUBIYA_API_KEY="kb-your-key"

# 3. Setup Claude integration
kubiya mcp setup claude

# 4. Start using in Claude Desktop!

2. Tool Development and Testing

# 1. Create tool definition
cat > my-tool.json << EOF
{
  "name": "disk-usage",
  "type": "docker",
  "image": "alpine",
  "content": "df -h"
}
EOF

# 2. Test locally
kubiya tool exec --json-file my-tool.json

# 3. Test with policy validation
kubiya policy test-tool --tool disk-usage --runner prod

3. Workflow Deployment Pipeline

# 1. Create workflow
cat > deploy.yaml << EOF
name: "deploy-app"
description: "Deploy application"
steps:
  - name: "build"
    command: "docker build -t app:{{version}} ."
  - name: "deploy"
    command: "kubectl apply -f k8s/"
EOF

# 2. Test workflow
kubiya workflow test deploy.yaml --var version=1.0.0

# 3. Execute with policy checks
kubiya workflow execute deploy.yaml --var version=1.0.0 --runner prod

4. Policy-Based Access Control

# 1. Create policy
cat > prod-policy.rego << EOF
package tools

allow {
    input.action == "tool_execution"
    input.runner == "production"
    input.user.role == "devops"
}
EOF

# 2. Deploy policy
kubiya policy create --name "prod-access" --env "production" --file prod-policy.rego

# 3. Enable enforcement
export KUBIYA_OPA_ENFORCE=true

# 4. Test access
kubiya policy test-tool --tool kubectl --runner production

🔍 Troubleshooting

Common Issues

API Key Not Set

# Check environment
echo $KUBIYA_API_KEY

# Get from app
open https://app.kubiya.ai/settings

Runner Health Issues

# Check runner status
kubiya runner list --health

# Get detailed health info
kubiya runner describe kubiya-hosted

Policy Errors

# Validate policy syntax
kubiya policy validate --file policy.rego

# Test specific permissions
kubiya policy test-tool --tool kubectl --args '{"command": "get pods"}'

MCP Connection Issues

# Test MCP server
kubiya mcp serve --debug

# Check configuration
cat ~/.kubiya/mcp-server.json

Debug Mode

Enable detailed logging for troubleshooting:

# Global debug flag
kubiya --debug tool exec --name test --content "echo debug"

# Environment variable
export LOG_LEVEL=DEBUG
kubiya tool exec --name test --content "echo debug"

🆘 Getting Help

# General help
kubiya --help

# Command-specific help
kubiya tool --help
kubiya tool exec --help

# Subcommand help
kubiya policy create --help
kubiya workflow execute --help

📚 Additional Resources

Documentation: https://docs.kubiya.ai
GitHub: https://github.com/kubiyabot/cli
API Keys: Get your API key
Examples: GitHub Examples

The Kubiya CLI provides enterprise-grade automation capabilities with comprehensive policy enforcement, making it perfect for production AI applications that need reliable, secure, and auditable execution.

Introduction

Core Concepts

Workflows

MCP Integration

Full-Stack Agents

Streaming UI

Tutorials

Resources

​Kubiya CLI Reference

​🚀 Installation

​🎯 Global Options

​🤖 Agent Management

​kubiya agent list

​kubiya agent describe

​🛠️ Tool Management

​kubiya tool list

​kubiya tool exec

​kubiya tool search

​kubiya tool describe

​🏃 Runner Management

​kubiya runner list

​kubiya runner describe

​kubiya runner create

​🔄 Workflow Management

​kubiya workflow execute

​kubiya workflow test

​kubiya workflow generate

​kubiya workflow compose

​🛡️ Policy Management (OPA)

​kubiya policy list

​kubiya policy create

​kubiya policy get

​kubiya policy update

​kubiya policy delete

​kubiya policy validate

​kubiya policy test-tool

​kubiya policy test-workflow

​🔧 MCP Server

​kubiya mcp serve

​kubiya mcp setup

​📚 Knowledge Management

​kubiya knowledge query

​🔗 Source Management

​kubiya source list

​kubiya source add

​kubiya source discover

​🔑 Secrets Management

​kubiya secret list

​🎮 Interactive Mode

​kubiya browse

​kubiya chat

​🔧 Configuration

​Environment Variables

​Configuration File

​MCP Server Configuration

​🚀 Common Workflows

​1. Setting up MCP for Claude Desktop

​2. Tool Development and Testing

​3. Workflow Deployment Pipeline

​4. Policy-Based Access Control

​🔍 Troubleshooting

​Common Issues

​Debug Mode

​🆘 Getting Help

​📚 Additional Resources

Kubiya CLI Reference

🚀 Installation

🎯 Global Options

🤖 Agent Management

kubiya agent list

kubiya agent describe

🛠️ Tool Management

kubiya tool list

kubiya tool exec

kubiya tool search

kubiya tool describe

🏃 Runner Management

kubiya runner list

kubiya runner describe

kubiya runner create

🔄 Workflow Management

kubiya workflow execute

kubiya workflow test

kubiya workflow generate

kubiya workflow compose

🛡️ Policy Management (OPA)

kubiya policy list

kubiya policy create

kubiya policy get

kubiya policy update

kubiya policy delete

kubiya policy validate

kubiya policy test-tool

kubiya policy test-workflow

🔧 MCP Server

kubiya mcp serve

kubiya mcp setup

📚 Knowledge Management

kubiya knowledge query

🔗 Source Management

kubiya source list

kubiya source add

kubiya source discover

🔑 Secrets Management

kubiya secret list

🎮 Interactive Mode

kubiya browse

kubiya chat

🔧 Configuration

Environment Variables

Configuration File

MCP Server Configuration

🚀 Common Workflows

1. Setting up MCP for Claude Desktop

2. Tool Development and Testing

3. Workflow Deployment Pipeline

4. Policy-Based Access Control

🔍 Troubleshooting

Common Issues

Debug Mode

🆘 Getting Help

📚 Additional Resources