Managing Sources with Kubiya CLI¶

This guide explains how to effectively manage sources using the Kubiya CLI. Sources in Kubiya are repositories that contain tools that can be used by your AI teammates.

Prerequisites¶

Before you begin, make sure you have:

Installed the Kubiya CLI
Set up authentication with your Kubiya environment
Appropriate permissions to manage sources

Adding a New Source¶

From a Git Repository¶

To add a source from a Git repository:

Bash

kubiya source add https://github.com/organization/repo-name

You can customize the source with additional options:

Bash

kubiya source add https://github.com/organization/repo-name \
  --name "My Custom Tools" \
  --runner "default" \
  --branch "main"

From a Local Directory¶

You can add a local directory containing tools:

Bash

kubiya source add ./my-tools-directory \
  --name "Local Tools"

The CLI will automatically zip the directory and upload it as an inline source.

From YAML/JSON Definition¶

For inline tool definitions in YAML or JSON format:

Bash

kubiya source add --inline tools-definition.yaml \
  --name "Inline Tools"

Example of a tools-definition.yaml file:

YAML

- name: deploy-application
  description: "Deploys an application to production"
  args:
    - name: version
      description: "Version to deploy"
      required: true
  env:
    - AWS_ACCESS_KEY
    - AWS_SECRET_KEY

Listing Sources¶

To view all sources in your environment:

Bash

kubiya source list

For more detailed information:

Bash

kubiya source list --full

To output in JSON format (useful for scripting):

Bash

kubiya source list --output json

Scanning for Tools¶

You can scan a repository to discover tools:

Bash

# Scan the current directory
kubiya source scan .

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

Automating Source Updates¶

When working with your development workflow, you can automatically commit and push tool changes:

Bash

kubiya source scan . \
  --add \
  --commit-msg "Update tools" \
  --push

Updating Sources¶

To update an existing source:

Bash

# Update source name or runner
kubiya source update source-id \
  --name "New Name" \
  --runner "new-runner"

# Update from inline definition
kubiya source update source-id \
  --inline updated-tools.yaml

Syncing Sources¶

To get the latest tools from a source:

Bash

# Interactive sync
kubiya source sync source-id

# Sync with specific branch
kubiya source sync source-id --branch develop

# Non-interactive sync
kubiya source sync source-id --mode non-interactive

Deleting Sources¶

To remove a source:

Bash

kubiya source delete source-id

To force deletion without confirmation:

Bash

kubiya source delete source-id --force

Temporary Sources with Load¶

For testing purposes, you can temporarily load a source without creating it permanently:

Bash

# Load from Git repository
kubiya source load https://github.com/organization/repo-name

# Load from local file
kubiya source load ./my_tool.py

# Load from inline definition
kubiya source load --inline tools.yaml

Best Practices¶

Use descriptive names: Give your sources clear, descriptive names that indicate their purpose.
Organize tools logically: Group related tools in the same source.
Version control: Keep your tools in a version-controlled repository.
Regular syncing: Regularly sync your sources to ensure you have the latest tools.
CI/CD integration: Integrate source management into your CI/CD pipeline.

Troubleshooting¶

Source Not Found¶

If you encounter a "Source not found" error:

Verify the source ID is correct
Check if the source exists with kubiya source list
Ensure your API key has the necessary permissions

Sync Failures¶

If source syncing fails:

Check if the repository is accessible
Verify your Git credentials
Ensure there are no conflicts in the repository

Debug Information¶

To get detailed debug information about a source:

Bash

kubiya source debug source-id

For full debug details:

Bash

kubiya source debug source-id --full

Next Steps¶

Now that you know how to manage sources, learn how to: