Source Command

This guide documents the source command in the Kubiya CLI, which allows you to manage sources of tools in your Kubiya environment. Sources are repositories that contain tools that can be used by your teammates.

Want to know more about Sources in Kubiya? Learn more about Sources

Overview

The source command (aliased as sources) provides comprehensive management of tool sources. Sources are typically Git repositories or inline definitions that contain the tools your AI teammates can use to perform tasks.

Source Listing and Discovery

List Sources

View all sources in your environment:

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

# 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

Describe Source

Get detailed information about a specific source:

# Show source details
kubiya source describe abc-123

# Get details in JSON format
kubiya source describe abc-123 --output json

Source Management

Add Source

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

# 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 an inline source from stdin
kubiya source add --inline-stdin --name "From Stdin" --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

For more details on adding sources via the web UI, see Add a Source

Load Source

Load a source temporarily without creating it permanently. This is useful for testing tools before adding them as a permanent source:

# 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

The load command creates a temporary source that won't be saved permanently. This is useful for testing tools or running one-off operations.

Update Source

Modify an existing source:

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

# 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

For more details on syncing sources via the web UI, see Sync a Source

Delete Source

Remove a source:

# Delete a source
kubiya source delete abc-123

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

For more details on deleting sources via the web UI, see Delete a Source

Troubleshooting

Debug Source

Debug source-related issues:

# Basic debug info
kubiya source debug abc-123

# Full debug details
kubiya source debug abc-123 --full

# JSON output
kubiya source debug abc-123 --output json

# Show raw API response
kubiya source debug abc-123 --raw

Command Options

Global Options

These options are available for all source commands:

Option	Description
--runner, -r	Runner name to use for operations

List Command Options

Option	Description
--output, -o	Output format (text|json)
--full	Show detailed information for each source
--debug	Enable debug logging

Add Command Options

Option	Description
--name, -n	Source name
--config, -c	Path to dynamic configuration file (JSON)
--yes	Skip confirmation prompts
--inline	File containing inline tool definitions (YAML or JSON)
--inline-stdin	Read inline tool definitions from stdin
--runner	Runner name for the source

Update Command Options

Option	Description
--name, -n	New source name
--config, -c	Path to dynamic configuration file (JSON)
--yes	Skip confirmation prompts
--inline	File containing inline tool definitions (YAML or JSON)
--inline-stdin	Read inline tool definitions from stdin
--runner	Runner name for the source

Sync Command Options

Option	Description
--mode, -m	Sync mode (interactive|non-interactive|ci)
--branch, -b	Branch to sync
--force, -f	Force sync
--auto-commit	Automatically commit changes

Scan Command Options

Option	Description
--interactive	Enable interactive mode
--output	Output format (text|json)
--config	Path to dynamic configuration file (JSON)
--local	Scan local directory instead of remote URL
--repo	Repository URL to scan
--branch	Branch to scan
--path	Relative path within repository
--remote	Git remote name (default: origin)
--force	Force scan even with uncommitted changes
--add	Stage changes after scan (can specify patterns)
--push	Push changes after scan
--commit-msg	Commit message for changes
--runner	Runner name for source

Source Types

Git Sources

Git sources are repositories that contain tool definitions in specific formats. The Kubiya CLI can scan these repositories to discover tools and make them available to your teammates.

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

Inline Sources

Inline sources contain tool definitions that are provided directly rather than from a Git repository. Inline sources can be provided in two ways:

1. JSON/YAML Tool Definitions

You can provide tool definitions directly through JSON or YAML files:

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

Example tools.yaml format:

- 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

You can also upload Python files or entire directories as inline sources. The CLI will automatically zip the content and upload it:

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

When adding a directory, the CLI will:

• Automatically detect if it's a Python project

• Include only relevant Python files and project files if it's a Python project

• Exclude hidden files and directories

• Create a zip file and upload it to the Kubiya API

When uploading Python code, your Python files must declare at least one tool using the Kubiya SDK. See Build a Tool using Kubiya SDK for details on how to create tools with the SDK.

This is particularly useful for tools that require multiple files or dependencies.

Python Project Support

The CLI includes special handling for Python projects. When you add a Python file or directory as an inline source, the system will:

1. Detect Python Projects: The CLI automatically identifies directories as Python projects if they contain:

   • Python-specific files like setup.py, requirements.txt, pyproject.toml

   • At least 3 Python (.py) files

   • Module structure with __init__.py files

2. Smart Filtering: For identified Python projects, the system only includes:

   • Python source files (.py, .pyi, .pyx, .pxd)

   • Python project files (requirements.txt, setup.py, etc.)

   • Configuration files (.yaml, .yml, .json)

   • Documentation files (README.md, LICENSE, etc.)

3. Exclusions: The system automatically excludes:

   • Hidden files and directories (starting with .)

   • Compiled Python files (.pyc, __pycache__)

   • Non-essential directories and files

This intelligent handling ensures that only relevant files are included in your tools, keeping them lightweight and focused.

1. Kubiya SDK Integration: Your Python code must define at least one tool using the Kubiya SDK. Here's a simple example:

# Simple tool using the Kubiya SDK
from kubiya import Tool, tool

@tool
def hello_world(name: str = "World"):
    """
    A simple greeting tool
    
    Args:
        name: Person to greet
    """
    return f"Hello, {name}!"

For more complex tools and to use the full capabilities of the SDK, initialize your project with:

# Install Kubiya SDK
pip install kubiya-sdk

# Initialize a new project structure
kubiya init

# Test your tools by running the bundle command
kubiya bundle

The kubiya init command creates template tools and the necessary directory structure, while kubiya bundle runs the discovery process locally to validate your tools before uploading.

For full documentation on using the Kubiya SDK, see Build a Tool using Kubiya SDK.

Working with Tools from Sources

After adding sources, you can list, search, and describe the tools they contain:

# 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

Integration with CI/CD

Sources can be managed through CI/CD pipelines:

# 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 using the Kubiya provider:

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

For more details on managing sources with Terraform, see Sources in Terraform

Troubleshooting

Common Issues and Solutions

1. 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

2. Sync Failures

   • Ensure the repository is accessible

   • Check if there are conflicts in the repository

   • Verify you have the correct permissions

3. 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

Related Commands

• kubiya tool list - List tools from sources

• kubiya tool search - Search for tools across sources

• kubiya tool describe - Show detailed information about a tool

• kubiya generate-tool - Generate a new tool

See Also

• Sources Overview - Learn more about sources in Kubiya
• Add a Source - How to add a source via the web UI
• Connect a Source to a Teammate - How to give teammates access to tools in a source
• Terraform Provider - Managing sources with Terraform

Conclusion

The source command in Kubiya CLI is essential for managing the tools available to your AI teammates. By properly managing sources, you can provide your teammates with the capabilities they need to perform tasks effectively.