Kubiya CLI¶

The Kubiya CLI is a standalone binary tool for discovering and managing sources of tools and workflows that are built with the Kubiya SDK. While the SDK is primarily used to develop the tools and workflows (in Python, YAML, or JSON), the CLI provides a way to discover, deploy, and manage these tools across different environments.

Relationship Between SDK and CLI¶

Kubiya SDK: Used to develop tools and workflows with Python, YAML, or JSON. The SDK defines the structure, behavior, and schema of tools, ensuring they remain predictable.
Kubiya CLI: Used to discover, deploy, and manage tools built with the SDK. The CLI enables runtime configuration and deployment of these tools across different environments.

This separation ensures that once tool schemas are produced with the SDK, they remain consistent, predictable, and can be executed reliably across environments. The tools run inside Docker containers behind the scenes, ensuring that LLM applications can always execute the same logic regardless of the environment.

Installation¶

Install the Kubiya CLI:

Bash

# Direct installation
curl -sSL https://get.kubiya.ai/cli | bash

# Or via pip
pip install kubiya

Basic Usage¶

After installation, you can access the CLI using the kubiya command:

Bash

kubiya --help

This will display all available commands and options.

Source Management¶

In Kubiya, sources are repositories containing tools and workflows built with the SDK. The CLI allows you to manage these sources:

List Sources¶

View all sources in your environment:

Bash

# List all sources
kubiya source list

# Show detailed information about each source
kubiya source list --full

# Output in JSON format
kubiya source list --output json

Scan for Tools¶

Scan a Git repository or local directory to discover tools and workflows built with the SDK:

Bash

# Scan current directory
kubiya source scan .

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

# Stage, commit and push changes
kubiya source scan . --add --push --commit-msg "feat: update tools"

# Stage specific files and push
kubiya source scan . --add "tools/*,README.md" --push

Add Source¶

Add a new source from a Git repository or as inline tools:

Bash

# Add a source from a URL
kubiya source add https://github.com/org/repo

# Add with custom name and config
kubiya source add https://github.com/org/repo --name "My Source" --config config.json

# Add an inline source from a file
kubiya source add --inline tools.yaml --name "My Inline Tools" --runner my-runner

# Add a Python file as an inline source (automatically zipped)
kubiya source add ./my_script.py --name "Python Script" --runner my-runner

# Add a directory as an inline source (automatically zipped)
kubiya source add ./tools_dir --name "Tools Directory" --runner my-runner

Load Source¶

Load a source temporarily without creating it permanently:

Bash

# Load a source from a URL
kubiya source load https://github.com/org/repo

# Load a Python file as a temporary source (automatically zipped)
kubiya source load ./my_script.py --name "Test Python Script"

# Load a directory as a temporary source (automatically zipped)
kubiya source load ./tools_dir --name "Test Directory"

# Load inline tools from a file
kubiya source load --inline tools.yaml

Update Source¶

Modify an existing source:

Bash

# Update an inline source from a file
kubiya source update abc-123 --inline tools.yaml --name "Updated Tools" --runner my-runner

# Update an inline source from stdin
kubiya source update abc-123 --inline-stdin --name "Updated From Stdin"

# Update source name or runner
kubiya source update abc-123 --name "New Name" --runner "new-runner"

Sync Source¶

Synchronize a source to get the latest tools:

Bash

# Sync a source interactively
kubiya source sync abc-123

# Sync with specific branch
kubiya source sync abc-123 --branch main

# Non-interactive sync
kubiya source sync abc-123 --mode non-interactive --force

Delete Source¶

Remove a source:

Bash

# Delete a source
kubiya source delete abc-123

# Force delete without confirmation
kubiya source delete abc-123 --force

Source Types¶

Git Sources¶

Git sources are repositories containing tools and workflows built with the Kubiya SDK:

Bash

# Add a Git source
kubiya source add https://github.com/org/repo --name "GitHub Tools"

Inline Sources¶

Inline sources contain tool definitions provided directly rather than from a Git repository.

1. JSON/YAML Tool Definitions¶

Bash

# Create an inline source from a YAML file
kubiya source add --inline tools.yaml --name "Custom Tools"

Example tools.yaml format:

YAML

- name: deploy-app
  description: "Deploys an application to a Kubernetes cluster"
  args:
    - name: namespace
      description: "Kubernetes namespace to deploy to"
      required: true
    - name: version
      description: "Application version to deploy"
      required: false
  env:
    - KUBERNETES_CONFIG

2. Python Files or Directories¶

Bash

# Add a Python file as a source
kubiya source add my_tool.py --name "Python Tool"

# Add a directory as a source
kubiya source add ./tools_directory --name "Tools Directory"

Environment Configuration¶

A key benefit of the CLI is its ability to discover and configure tools at runtime. This enables you to produce variations of the same tools across different environments with different configurations while maintaining consistent logic. For example:

Bash

# Discover tools and configure them for development
kubiya source scan . --config dev-config.json

# Discover tools and configure them for production
kubiya source scan . --config prod-config.json

The underlying Docker containers ensure that the tool logic remains predictable and consistent, while the configuration allows for environment-specific settings.

Working with Tools from Sources¶

After adding sources, you can manage the tools they contain:

Bash

# List all tools from a specific source
kubiya tool list --source SOURCE_UUID

# Search for tools
kubiya tool search kubernetes

# Get detailed information about a tool
kubiya tool describe deploy-app

Testing Tools¶

You can test individual tools directly with the CLI:

Bash

# Test a specific tool with parameters
kubiya tool test deploy-app --param namespace=staging --param version=1.2.3

# Interactive testing with prompts for each parameter
kubiya tool test deploy-app --interactive

# Test with environment variables
export API_KEY=your-api-key
kubiya tool test auth-tool

# View detailed output with verbose mode
kubiya tool test deploy-app --verbose

# Test a tool from a specific source
kubiya tool test deploy-app --source SOURCE_ID

For debugging purposes, you can also validate tool definitions and check logs:

Bash

# Validate tool definitions in the current directory
kubiya source validate .

# Check logs for a tool
kubiya tool logs TOOL_ID

# Inspect Docker containers running tools
kubiya container list
kubiya container logs CONTAINER_ID

Integration with CI/CD¶

Sources can be managed through CI/CD pipelines:

Bash

# GitHub Actions example
- name: Add Kubiya Source
  run: |
    kubiya source add https://github.com/org/repo \
      --name "CI Tools" \
      --yes \
      --runner ci-runner

Terraform Integration¶

You can also manage sources through Terraform:

Terraform

terraform {
  required_providers {
    kubiya = {
      source = "kubiya-terraform/kubiya"
    }
  }
}

provider "kubiya" {
  # Your Kubiya API Key will be taken from the 
  # environment variable KUBIYA_API_KEY
}

resource "kubiya_source" "example" {
  url = "https://github.com/org/repo"
}

Troubleshooting¶

Common Issues and Solutions¶

Source Not Found¶

Verify the UUID is correct
Check if the source exists with kubiya source list
Verify your API key has access to the source

Sync Failures¶

Ensure the repository is accessible
Check if there are conflicts in the repository
Verify you have the correct permissions

Tool Discovery Issues¶

Ensure tools are defined in the correct format
Verify the source contains valid tool definitions
Use kubiya source debug to get more information

Conclusion¶

The Kubiya CLI is an essential companion to the Kubiya SDK. While the SDK allows you to develop predictable tools and workflows, the CLI enables you to discover, deploy, and manage these tools across different environments. This separation ensures consistent logic execution through Docker containers while allowing for environment-specific configurations. By properly managing sources with the CLI, you can provide your AI teammates with the capabilities they need to perform tasks effectively on your infrastructure.