cmd

README

Command Package (cmd/)

CLI command implementations using the Cobra framework.

Structure

File	Purpose
root.go	Root command, banner display, global flags
setup.go	Interactive configuration wizard
config.go	Configure individual providers
list.go	List all configured providers
status.go	Test connectivity for all providers
test.go	Test specific provider connectivity
switch.go	Switch provider and execute CLI (Claude or Qwen)
harness.go	Manage CLI harness (claude or qwen)
default.go	Get or set default provider
reset.go	Remove provider configurations
rotate.go	Rotate encryption key
version.go	Display version information
update.go	Check for and install updates
completion.go	Shell completion support
audit.go	View and export audit logs

Command Architecture

flowchart TB
    subgraph Root
        Main[main.go] --> RootCmd[root.go]
        RootCmd --> Flags[Global Flags]
    end

    subgraph Configuration
        RootCmd --> Setup[setup]
        RootCmd --> Config[config]
        RootCmd --> DefaultCmd[default]
        RootCmd --> Reset[reset]
    end

    subgraph Execution
        RootCmd --> Switch[switch]
        RootCmd --> Test[test]
    end

    subgraph Information
        RootCmd --> List[list]
        RootCmd --> Status[status]
        RootCmd --> Version[version]
        RootCmd --> Audit[audit]
    end

    subgraph Maintenance
        RootCmd --> Rotate[rotate]
        RootCmd --> Update[update]
        RootCmd --> Completion[completion]
    end

Command Reference

Setup Commands

Command	Description
kairo setup	Interactive setup wizard for initial configuration
kairo config <provider>	Configure a specific provider

Provider Management

Command	Description
kairo list	List all configured providers
kairo status	Test connectivity for all providers
kairo test <provider>	Test specific provider
kairo default <provider>	Get or set default provider
kairo reset <provider|all>	Remove provider configuration

Execution

Command	Description
kairo switch <provider>	Switch and execute CLI (claude or qwen)
kairo switch <provider> --harness qwen	Switch using Qwen CLI
kairo switch <provider> --harness qwen	Switch using Qwen CLI
kairo harness get	Get current default harness
kairo harness set <harness>	Set default harness (claude or qwen)
kairo <provider> [args]	Shorthand for switch (e.g., kairo zai)
kairo -- "query"	Query mode using default provider

Maintenance

Command	Description
kairo rotate	Rotate encryption key
kairo update	Check for and install updates
kairo version	Display version info
kairo completion <shell>	Generate shell completion
kairo audit <list|export>	View/export audit logs

Adding a New Command

1. Create Command File

Create cmd/newcommand.go:

package cmd

import (
    "fmt"
    "github.com/spf13/cobra"
)

var newCommand = &cobra.Command{
    Use:   "newcommand",
    Short: "Brief description",
    Long:  `Longer description with examples`,
    Run: func(cmd *cobra.Command, args []string) {
        // Implementation
    },
}

func init() {
    rootCmd.AddCommand(newCommand)
}

2. Add to Root Command

Import and add in cmd/root.go:

import _ "github.com/dkmnx/kairo/cmd"  // Blank import for init()

3. Testing

go test ./cmd/... -run TestNewCommand

Testing

# All cmd package tests
go test ./cmd/...

# With race detection
go test -race ./cmd/...

# Specific test file
go test -v ./cmd/... -run TestSetup

# Integration tests
go test -v ./cmd/... -run Integration

Dependencies

• github.com/spf13/cobra - CLI framework
• github.com/spf13/viper - Configuration management
• Internal packages: config, crypto, providers, validate, ui, audit

Global Flags

Flag	Purpose
-v, --verbose	Enable verbose output
-h, --help	Show help for command
--config	Config directory (default is platform-specific)

Switch Command Flags

Flag	Purpose
--harness	CLI harness to use (claude or qwen)

Banner Display

The root command displays version and provider information:

kairo v1.2.0 - Provider: zai

This is rendered from internal/version/version.go and providers package.

CLI Harnesses

Kairo supports multiple CLI harnesses:

Harness	CLI Binary	Description
claude	claude	Claude Code (default)
qwen	qwen	Qwen Code

Using Harnesses

# Use Qwen harness for a specific provider
kairo switch zai --harness qwen

# Set default harness globally
kairo harness set qwen

# Get current harness
kairo harness get

The model is automatically passed from the provider's configuration.

Provider Shorthand

Users can use provider name directly instead of switch:

# These are equivalent:
kairo switch zai "Help me"
kairo zai "Help me"

This is handled in root.go by checking if the first argument is a valid provider name.

Audit Integration

All configuration commands log changes to ~/.config/kairo/audit.log:

• config - Logs api_key, base_url, model changes
• default - Logs default provider changes
• reset - Logs provider resets
• rotate - Logs key rotations
• setup - Logs provider setup
• switch - Logs provider switches

See: docs/guides/audit-guide.md

Documentation

Overview

Package cmd implements the Kairo CLI application using the Cobra framework.

Architecture:

• Commands are defined in individual files (root.go, setup.go, switch.go, etc.)
• Global state (configDir, verbose) is managed via getter/setter functions
• Command execution is orchestrated by rootCmd.Execute()

Testing:

• Most commands have corresponding *_test.go files
• Integration tests verify end-to-end workflows
• External process execution can be mocked via execCommand variable

Design principles:

• Minimal business logic in command handlers
• Delegation to internal packages for core functionality
• Consistent error handling with user-friendly messages

Security:

• All user input is read securely using ui package
• No secrets are logged to stdout/stderr
• API keys are managed via encrypted secrets file

Index

• func Execute() error
• func LoadAndDecryptSecrets(dir string) (map[string]string, string, string, error)

Functions

func Execute

func Execute() error

Execute runs the kairo CLI application. It processes command-line arguments, handles provider name shortcuts, and executes the appropriate Cobra command. Returns an error if command execution fails.

func LoadAndDecryptSecrets

func LoadAndDecryptSecrets(dir string) (map[string]string, string, string, error)

LoadSecrets loads and decrypts secrets from the specified directory. Returns the secrets map, secrets file path, key file path, and any error. Returns nil map with error if secrets file cannot be decrypted. Returns empty map with nil error if secrets file doesn't exist (first-time setup). LoadAndDecryptSecrets loads and decrypts secrets from the specified directory. Returns secrets map, secrets path, and key path. If secrets file doesn't exist or decryption fails, returns empty secrets map with appropriate error handling.