Managing Tools with Kubiya CLI

This guide explains how to manage tools with the Kubiya CLI. After your tools have been built using the Kubiya SDK, you can use the CLI to discover, inspect, and test them.

Prerequisites

Before you begin, make sure you have:

1. Installed the Kubiya CLI
2. Set up authentication with your Kubiya environment
3. Added at least one source containing tools (see Managing Sources)

Listing Tools

To view all tools available across all sources:

Bash

kubiya tool list

To list tools from a specific source:

Bash

kubiya tool list --source SOURCE_ID

For more detailed information:

Bash

kubiya tool list --full

To output in JSON format (useful for scripting):

Bash

kubiya tool list --output json

Searching for Tools

To search for tools by keyword:

Bash

kubiya tool search "kubernetes"

To search within a specific source:

Bash

kubiya tool search "deploy" --source SOURCE_ID

Inspecting Tool Details

To get detailed information about a specific tool:

Bash

kubiya tool describe TOOL_ID

To specify the source containing the tool (if multiple sources have tools with the same ID):

Bash

kubiya tool describe TOOL_ID --source SOURCE_ID

To output in JSON format:

Bash

kubiya tool describe TOOL_ID --output json

Testing Tools

One of the key benefits of the Kubiya CLI is the ability to test tools locally before using them in production:

Bash

kubiya tool test TOOL_ID --param key1=value1 --param key2=value2

For interactive testing with prompts for each parameter:

Bash

kubiya tool test TOOL_ID --interactive

To test a tool from a specific source:

Bash

kubiya tool test TOOL_ID --source SOURCE_ID --param key=value

Working with Environment Variables

Many tools require environment variables. To set them for a test session:

Bash

export API_KEY=your-api-key
kubiya tool test tool-requiring-api-key

You can also provide environment variables during scanning:

Bash

kubiya source scan . --with-env API_KEY=your-api-key

Runtime Tool Configuration

The CLI allows you to configure tools at runtime, producing variations of the same tool logic for different environments:

Creating Configuration Files

Create a configuration file in JSON format:

JSON

{
  "tools": {
    "deploy-app": {
      "environment": "development",
      "registry": "dev-registry.example.com",
      "timeout": 300
    },
    "backup-database": {
      "retention_days": 7,
      "storage_path": "/tmp/backups"
    }
  }
}

Applying Configuration

Apply configuration when adding a source:

Bash

kubiya source add https://github.com/org/repo --config config.json

Or update an existing source with new configuration:

Bash

kubiya source update SOURCE_ID --config updated-config.json

Environment-Specific Configurations

You can maintain different configuration files for different environments:

Bash

# Development environment
kubiya source add . --config dev-config.json --name "Dev Tools"

# Production environment
kubiya source add . --config prod-config.json --name "Prod Tools"

Tool Versioning

The CLI provides ways to work with different versions of tools:

Bash

# Add a source with a specific branch/version
kubiya source add https://github.com/org/repo --branch v1.2.3

# Sync a source to a specific version
kubiya source sync SOURCE_ID --branch main

Docker Container Management

While the CLI abstracts away much of the Docker complexity, you can interact with the underlying containers:

Bash

# View running tool containers
kubiya container list

# Get logs from a tool container
kubiya container logs CONTAINER_ID

# Restart a tool container
kubiya container restart CONTAINER_ID

Advanced Tool Commands

Exporting Tool Definitions

Export tool definitions to a file:

Bash

kubiya tool export TOOL_ID --output tool-definition.yaml

Importing Tool Definitions

Import previously exported tool definitions:

Bash

kubiya tool import tool-definition.yaml

Generating Tool Documentation

Generate documentation for a tool:

Bash

kubiya tool docs TOOL_ID --format markdown --output tool-docs.md

Best Practices

1. Test tools locally first: Always test tools with the CLI before deploying them to production.

2. Use version control: Keep tool configurations in version control along with the tools themselves.

3. Environment-specific configs: Maintain separate configuration files for different environments.

4. Consistent naming: Use consistent naming conventions for tools across environments.

5. Regular updates: Regularly sync your sources to ensure you have the latest tool versions.

Troubleshooting

Tool Not Found

If you encounter a "Tool not found" error:

• Verify the tool ID is correct
• Check if the tool exists with kubiya tool list
• Ensure your source is properly synced

Tool Execution Failures

If a tool fails during execution:

• Check the parameters you provided
• Verify that required environment variables are set
• Look for errors in the tool's output
• Use kubiya container logs to view detailed logs

Configuration Issues

If tool configuration isn't being applied correctly:

• Verify your JSON configuration format
• Check that the tool ID in the configuration matches the actual tool ID
• Ensure the configuration file is being properly loaded

Next Steps

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

• Set up end-to-end testing for tools
• Integrate tool management with CI/CD pipelines
• Create your own tools with the Kubiya SDK