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://compose.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

Quick Start

Core Concepts

Using Kubiya

Workflows

MCP Integration

Administration

Reference

​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