Resource Management

The Kubiya CLI provides comprehensive resource management capabilities for all Control Plane resources. This guide covers CRUD operations for agents, teams, tools, sources, secrets, runners, and more.

Resource Overview

Agents

AI-powered agents that execute tasks using tools and integrations.

List Agents

# Basic listing
kubiya agent list

# Detailed view with all metadata
kubiya agent list --all

# Filter active agents only
kubiya agent list --active

# Sort by various fields
kubiya agent list --sort name
kubiya agent list --sort updated

# Search by name or description
kubiya agent list --filter "kubernetes"

# Output formats
kubiya agent list --output json
kubiya agent list --output yaml
kubiya agent list --output table

Create Agent

Interactive
Command Line
From File

# Guided interactive creation
kubiya agent create --interactive

# You'll be prompted for:
# - Agent name
# - Description
# - Sources to attach
# - Environment variables
# - Secrets
# - Webhook configuration

Update Agent

# Update basic information
kubiya agent edit <agent-id> \
  --name "Updated Agent Name" \
  --desc "Updated description"

# Add/remove sources
kubiya agent edit <agent-id> \
  --add-source source-uuid \
  --remove-source old-source-uuid

# Update environment variables
kubiya agent edit <agent-id> \
  --add-env "NEW_VAR=value" \
  --remove-env "OLD_VAR"

# Update secrets
kubiya agent edit <agent-id> \
  --add-secret "NEW_SECRET" \
  --remove-secret "OLD_SECRET"

# Configure webhook
kubiya agent edit <agent-id> \
  --webhook-method slack \
  --webhook-dest "#new-channel" \
  --webhook-prompt "Updated prompt"

# Interactive editing
kubiya agent edit <agent-id> --interactive

Delete Agent

# Delete agent
kubiya agent delete <agent-id>

# Delete with confirmation skip
kubiya agent delete <agent-id> --force

# Delete multiple agents
kubiya agent delete agent-1 agent-2 agent-3

Agent Chat

# Interactive chat session
kubiya chat --interactive

# Chat with specific agent by name
kubiya chat -n "DevOps Agent" -m "Deploy to staging"

# Chat with agent by UUID
kubiya chat -t <agent-uuid> -m "Show deployment logs"

# Chat with context files
kubiya chat -n "Security Agent" \
  -m "Review this configuration" \
  --context k8s/deployment.yaml \
  --context src/**/*.go

# Chat with stdin
cat error.log | kubiya chat -n "Debug Agent" --stdin

# Create temporary inline agent
kubiya chat --inline \
  --tools-file tools.json \
  --ai-instructions "You are a DevOps assistant" \
  --runners "k8s-runner" \
  -m "Deploy the application"

Teams

Groups of agents that collaborate on tasks.

List Teams

# List all teams
kubiya team list

# Detailed view
kubiya team list --all

# Filter by name
kubiya team list --filter "production"

# Sort by creation date
kubiya team list --sort created

Create Team

# Basic team
kubiya team create \
  --name "DevOps Team" \
  --desc "Production DevOps operations"

# Team with agents
kubiya team create \
  --name "Platform Team" \
  --desc "Platform engineering" \
  --agent agent-1 \
  --agent agent-2 \
  --agent agent-3

# Team with Slack integration
kubiya team create \
  --name "Support Team" \
  --desc "Customer support automation" \
  --slack-channel "#support"

Update Team

# Add/remove agents
kubiya team edit <team-id> \
  --add-agent new-agent-id \
  --remove-agent old-agent-id

# Update name and description
kubiya team edit <team-id> \
  --name "Updated Team Name" \
  --desc "Updated description"

Tools

Executable units of work that agents can use.

List Tools

# List all tools
kubiya tool list

# Filter by source
kubiya tool list --source source-uuid

# Filter by type
kubiya tool list --type docker
kubiya tool list --type script

# Detailed view
kubiya tool list --all

# Search by name
kubiya tool list --filter "kubectl"

Execute Tool

Basic Execution
With Integrations
Advanced

# Simple command
kubiya tool exec \
  --name "hello" \
  --content "echo Hello World"

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

# With timeout
kubiya tool exec \
  --name "long-task" \
  --content "sleep 90 && echo done" \
  --timeout 120s

# On specific runner
kubiya tool exec \
  --name "k8s-command" \
  --content "kubectl get nodes" \
  --runner k8s-runner

Sources

Collections of tools from Git repositories or inline definitions.

List Sources

# List all sources
kubiya source list

# Detailed view
kubiya source list --all

# Filter by name
kubiya source list --filter "devops"

# Sort by creation date
kubiya source list --sort created

Scan Sources

# Scan GitHub repository
kubiya source scan https://github.com/org/devops-tools

# Scan local directory
kubiya source scan .

# Scan with specific runner
kubiya source scan . --runner python-runner

# Scan specific branch and path
kubiya source scan https://github.com/org/tools \
  --branch develop \
  --path /scripts

# Force scan with uncommitted changes
kubiya source scan . --force

Add Source

From Git
Inline Source

# Add from GitHub
kubiya source add https://github.com/org/devops-tools \
  --name "DevOps Automation"

# With configuration
kubiya source add https://github.com/org/k8s-tools \
  --name "K8s Tools" \
  --config k8s-config.json \
  --runner k8s-runner

# With auto-commit
kubiya source add . \
  --name "Local Tools" \
  --add \
  --push \
  --commit-msg "feat: add monitoring tools"

Sync Source

# Sync source with latest changes
kubiya source sync <source-id>

# Force sync (ignore conflicts)
kubiya source sync <source-id> --force

# Sync all sources
kubiya source sync --all

Secrets

Securely store and manage sensitive credentials.

List Secrets

# List all secrets
kubiya secret list

# Detailed view (values are hidden)
kubiya secret list --all

# Filter by name
kubiya secret list --filter "AWS"

Create Secret

# Basic secret
kubiya secret create DB_PASSWORD "secure-password-123" \
  --description "Production database password"

# With expiration
kubiya secret create API_TOKEN "token-xyz" \
  --expires-in 30d \
  --description "Temporary API token"

# For specific environment
kubiya secret create STAGING_KEY "staging-secret" \
  --environment staging \
  --description "Staging environment key"

# From file
kubiya secret create SSH_KEY --file ~/.ssh/id_rsa \
  --description "SSH private key"

Update Secret

# Update secret value
kubiya secret update DB_PASSWORD "new-password-456"

# Update with expiration
kubiya secret update API_TOKEN "new-token" --expires-in 60d

# Rotate secret (generates new value)
kubiya secret rotate API_TOKEN

Delete Secret

# Delete secret
kubiya secret delete TEMP_TOKEN

# Force delete (skip confirmation)
kubiya secret delete OLD_SECRET --force

Runners

Execution environments for tools and workflows.

List Runners

# List all runners
kubiya runner list

# Show detailed information
kubiya runner list --all

# Filter healthy runners
kubiya runner list --healthy

# Sort by health status
kubiya runner list --sort health

Get Runner Details

# Describe specific runner
kubiya runner describe <runner-name>

# Get runner manifest for Kubernetes
kubiya runner manifest <runner-name> > runner.yaml

# Get Helm chart
kubiya runner helm-chart <runner-name> > chart.yaml

Create Runner

# Create Kubernetes runner
kubiya runner create my-k8s-runner \
  --type kubernetes \
  --namespace kubiya

# Create Docker runner
kubiya runner create my-docker-runner \
  --type docker

Environments

Logical groupings for resources and configurations.

List Environments

# List all environments
kubiya environment list

# Detailed view
kubiya environment list --all

# Filter by name
kubiya environment list --filter "production"

Create Environment

# Basic environment
kubiya environment create production \
  --desc "Production environment"

# With default runner
kubiya environment create staging \
  --desc "Staging environment" \
  --default-runner staging-runner

Switch Environment

# Switch to different environment
kubiya environment use production

# View current environment
kubiya environment current

Projects

Organizational units for grouping resources.

List Projects

# List all projects
kubiya project list

# Detailed view
kubiya project list --all

# Filter by name
kubiya project list --filter "platform"

Create Project

# Basic project
kubiya project create "Platform Engineering" \
  --desc "Platform team's automation project"

# With team assignment
kubiya project create "Security Operations" \
  --desc "Security automation" \
  --team security-team-id

Integrations

Connect external services and tools.

List Integrations

# List all integrations
kubiya integration list

# Filter by type
kubiya integration list --type github
kubiya integration list --type slack

# Show configuration
kubiya integration describe <integration-id>

Create Integration

GitHub
Slack
AWS
Kubernetes

kubiya integration create github \
  --name "GitHub Integration" \
  --token "ghp_your_token_here" \
  --org "your-org"

Batch Operations

Export Resources

# Export all agents
kubiya agent list --output yaml > agents.yaml

# Export specific resources
kubiya agent describe <agent-id> --output yaml > agent.yaml
kubiya source describe <source-id> --output yaml > source.yaml

# Export entire project
kubiya project export <project-id> --output ./project-backup/

Import Resources

# Import agents
kubiya agent create --file agents.yaml

# Import project
kubiya project import ./project-backup/

Bulk Updates

# Update multiple agents
for agent in $(kubiya agent list --filter "prod" --output json | jq -r '.[].id'); do
  kubiya agent edit $agent --add-env "ENVIRONMENT=production"
done

# Add source to all agents in project
PROJECT_AGENTS=$(kubiya agent list --project <project-id> --output json | jq -r '.[].id')
for agent in $PROJECT_AGENTS; do
  kubiya agent edit $agent --add-source <source-id>
done

Best Practices

Resource Naming

Use descriptive, consistent naming: prod-devops-agent, staging-k8s-runner

Include environment in name for clarity: prod-*, staging-*, dev-*

Use hyphens, not underscores: my-agent not my_agent

Organization

Group by project: Assign related resources to projects
Use teams effectively: Group agents by function
Tag resources: Use labels for filtering and organization
Document resources: Add clear descriptions

Security

✅ Rotate secrets regularly: At least quarterly
✅ Use least privilege: Grant minimum required permissions
✅ Audit access: Review resource access logs
✅ Separate environments: Don’t mix prod/staging secrets

Maintenance

# Regular cleanup
kubiya agent list --inactive | xargs kubiya agent delete
kubiya source sync --all
kubiya secret list --expired | xargs kubiya secret delete

# Health checks
kubiya runner list --unhealthy
kubiya agent list --filter "last_run > 30d"

Command Reference

# Agents
kubiya agent list [--all] [--active] [--filter <query>]
kubiya agent create --name <name> --desc <description>
kubiya agent edit <id> [options]
kubiya agent delete <id>

# Teams
kubiya team list [--all] [--filter <query>]
kubiya team create --name <name>
kubiya team edit <id> [options]

# Tools
kubiya tool list [--source <id>] [--type <type>]
kubiya tool exec --name <name> --content <command>

# Sources
kubiya source list [--all] [--filter <query>]
kubiya source scan <path|url>
kubiya source add <url> --name <name>
kubiya source sync <id>

# Secrets
kubiya secret list
kubiya secret create <name> <value>
kubiya secret update <name> <new-value>
kubiya secret delete <name>

# Runners
kubiya runner list [--healthy]
kubiya runner describe <name>
kubiya runner manifest <name>

# Environments
kubiya environment list
kubiya environment create <name>
kubiya environment use <name>

# Projects
kubiya project list
kubiya project create <name>

Next Steps

Workflow Execution

Execute automated workflows

Webhooks

Set up automated triggers

Advanced Features

MCP integration, policies, and more

API Reference

Programmatic access to resources

Getting Started

Core Operations

Advanced

​Resource Overview

​Agents

​List Agents

​Create Agent

​Update Agent

​Delete Agent

​Agent Chat

​Teams

​List Teams

​Create Team

​Update Team

​Tools

​List Tools

​Execute Tool

​Sources

​List Sources

​Scan Sources

​Add Source

​Sync Source

​Secrets

​List Secrets

​Create Secret

​Update Secret

​Delete Secret

​Runners

​List Runners

​Get Runner Details

​Create Runner

​Environments

​List Environments

​Create Environment

​Switch Environment

​Projects

​List Projects

​Create Project

​Integrations

​List Integrations

​Create Integration

​Batch Operations

​Export Resources

​Import Resources

​Bulk Updates

​Best Practices

​Resource Naming

​Organization

​Security

​Maintenance

​Command Reference

​Next Steps

Workflow Execution

Webhooks

Advanced Features

API Reference

Resource Overview

Agents

List Agents

Create Agent

Update Agent

Delete Agent

Agent Chat

Teams

List Teams

Create Team

Update Team

Tools

List Tools

Execute Tool

Sources

List Sources

Scan Sources

Add Source

Sync Source

Secrets

List Secrets

Create Secret

Update Secret

Delete Secret

Runners

List Runners

Get Runner Details

Create Runner

Environments

List Environments

Create Environment

Switch Environment

Projects

List Projects

Create Project

Integrations

List Integrations

Create Integration

Batch Operations

Export Resources

Import Resources

Bulk Updates

Best Practices

Resource Naming

Organization

Security

Maintenance

Command Reference

Next Steps