Skip to content

README.md

Latest commit

 

History

History
368 lines (273 loc) · 8.71 KB

README.md

File metadata and controls

368 lines (273 loc) · 8.71 KB

AI SDK CLI

Command-line tool for interacting with AI Agents.

Installation

Quick Install (Recommended)

Install the AI SDK CLI with a single command:

curl -sSL https://raw.githubusercontent.com/open-metadata/ai-sdk/main/cli/install.sh | sh

This script will:

  • Detect your OS (macOS or Linux) and architecture (x64 or arm64)
  • Download the appropriate binary from GitHub releases
  • Install to ~/.local/bin (or /usr/local/bin as fallback)
  • Verify the installation

Supported platforms:

  • macOS (Intel and Apple Silicon)
  • Linux (x64 and arm64)
  • Windows users: Please use WSL

From Source

cd cli
cargo build --release
# Binary will be at target/release/ai-sdk

Using Cargo

cargo install --path .

Manual Download

Download the appropriate binary for your platform from the releases page:

Platform Architecture Download
macOS Intel (x86_64) ai-sdk-macos-x86_64.tar.gz
macOS Apple Silicon (aarch64) ai-sdk-macos-aarch64.tar.gz
Linux x86_64 ai-sdk-linux-x86_64.tar.gz
Linux aarch64 ai-sdk-linux-aarch64.tar.gz
Windows x86_64 ai-sdk-windows-x86_64.zip
Windows aarch64 ai-sdk-windows-aarch64.zip

Extract and move to a directory in your PATH:

macOS / Linux:

tar -xzf ai-sdk-<os>-<arch>.tar.gz
mv ai-sdk ~/.local/bin/
# Or system-wide: sudo mv ai-sdk /usr/local/bin/

Windows (PowerShell):

Expand-Archive ai-sdk-windows-x86_64.zip -DestinationPath .
# Move ai-sdk.exe to a directory in your PATH

Configuration

The CLI stores configuration in ~/.ai-sdk/:

  • config.toml - Host URL and settings
  • credentials - Authentication token (stored with restricted permissions)

Interactive Setup

ai-sdk configure

Manual Configuration

# Set individual values
ai-sdk configure set host https://your-instance.getcollate.io
ai-sdk configure set token your-jwt-token
ai-sdk configure set timeout 120

# View configuration
ai-sdk configure list
ai-sdk configure get host

Environment Variables

Environment variables take precedence over file configuration:

export AI_SDK_HOST="https://your-instance.getcollate.io"
export AI_SDK_TOKEN="your-jwt-token"

Usage

Interactive Chat (TUI)

The chat command launches a rich terminal interface for conversational interactions:

# Open TUI with agent selection menu
ai-sdk chat

# Open TUI with a specific agent
ai-sdk chat semantic-layer-agent

# Resume an existing conversation
ai-sdk chat semantic-layer-agent -c <conversation-id>

TUI Features:

  • Agent selection: Type /agents or start without an agent to see available agents
  • Markdown rendering: Bold, italic, headers, lists render properly
  • Syntax-highlighted code blocks: SQL, Python, JSON, and more
  • Thinking/reasoning display: Agent's thought process shown in grey
  • Scrollable history: Use arrow keys to scroll through the conversation
  • In-chat commands: /agents, /clear, /quit

Key Bindings:

Key Action
Enter Send message
↑/↓ Scroll history / navigate menu
Ctrl+C Quit
Esc Quit / close menu

Discover Agents

# List all API-enabled agents
ai-sdk agents list

# Get detailed information about an agent
ai-sdk agents info semantic-layer-agent

Create Agents

# Interactive wizard (recommended)
ai-sdk agents create

# Or provide all options via CLI
ai-sdk agents create \
  --name "MyAgent" \
  --description "Agent description" \
  --persona "PersonaName" \
  --api-enabled true

# Create with additional options
ai-sdk agents create \
  --name "AdvancedAgent" \
  --description "An advanced agent" \
  --persona "DataAnalyst" \
  --display-name "Advanced Agent" \
  --bot-name "MyBot" \
  --abilities search,analyze \
  --provider openai \
  --json

Interactive Wizard:

When you run ai-sdk agents create without required arguments, an interactive TUI wizard guides you through:

  1. Basic Details - Enter name and description
  2. Select Persona - Choose from available personas with filter/search
  3. Select Abilities - Multi-select abilities (optional)
  4. Actions - Configure task prompt and bot (optional)

The wizard automatically sets apiEnabled: true for created agents.

Manage Bots

# List all bots
ai-sdk bots list

# List with options
ai-sdk bots list --limit 10 --json

# Get bot information
ai-sdk bots get <bot-name>

# Get bot info as JSON
ai-sdk bots get <bot-name> --json

Manage Personas

# List all personas
ai-sdk personas list

# List with options
ai-sdk personas list --limit 10 --json

# Get persona information
ai-sdk personas get <persona-name>

# Interactive wizard (recommended)
ai-sdk personas create

# Or provide all options via CLI
ai-sdk personas create \
  --name "MyPersona" \
  --description "A helpful data assistant" \
  --prompt "You are a helpful data assistant..."

# Create with additional options
ai-sdk personas create \
  --name "DataExpert" \
  --description "Expert in data analysis" \
  --prompt "You are an expert data analyst..." \
  --display-name "Data Expert" \
  --provider openai \
  --json

Interactive Wizard:

When you run ai-sdk personas create without required arguments, an interactive TUI wizard guides you through:

  1. Basic Details - Enter name and description
  2. System Prompt - Write the persona's system prompt (multiline)
  3. Review & Submit - Review and confirm creation

Manage Abilities

# List all abilities
ai-sdk abilities list

# List with options
ai-sdk abilities list --limit 50 --json

# Get ability information
ai-sdk abilities get <ability-name>

# Get ability info as JSON
ai-sdk abilities get <ability-name> --json

Invoke Agents (One-shot)

For scripting or single queries, use the invoke command:

# Simple invocation
ai-sdk invoke semantic-layer-agent "What tables are available?"

# Stream response in real-time
ai-sdk invoke semantic-layer-agent "Analyze data quality" --stream

# Show agent thinking/reasoning
ai-sdk invoke semantic-layer-agent "Explain this" --stream --thinking

# Get JSON output for scripting
ai-sdk invoke semantic-layer-agent "List all pipelines" --json

# Continue a conversation
ai-sdk invoke semantic-layer-agent "Tell me more" -c <conversation-id>

# Combine options
ai-sdk invoke planner "Create a test plan" --stream --json

Output Formats

Default (Human-readable):

The available tables include:
- customers
- orders
- products

Tools used:
  - searchMetadata

Conversation ID: abc123-def456

JSON (--json):

{
  "conversationId": "abc123-def456",
  "response": "The available tables include...",
  "toolsUsed": ["searchMetadata"],
  "usage": {
    "promptTokens": 150,
    "completionTokens": 200,
    "totalTokens": 350
  }
}

Error Messages

Error Solution
Authentication failed Run ai-sdk configure to set credentials
Agent is not API-enabled Enable API access in the Metadata UI
Agent not found Check agent name with ai-sdk agents list
Rate limit exceeded Wait before retrying
Configuration not found Run ai-sdk configure

Development

Building

cargo build

Running Tests

cargo test

Release Build

cargo build --release

The release build is optimized for size with LTO enabled.

Architecture

src/
├── main.rs          # CLI entry point and argument parsing
├── commands/        # Command implementations
│   ├── configure.rs # Configuration management
│   ├── agents.rs    # Agent discovery and creation
│   ├── abilities.rs # Ability listing and info
│   ├── bots.rs      # Bot management
│   ├── personas.rs  # Persona management
│   ├── invoke.rs    # Agent invocation (one-shot)
│   └── chat.rs      # Interactive TUI chat
├── tui/             # Terminal UI components
│   ├── mod.rs       # Module exports
│   ├── app.rs       # Application state (chat)
│   ├── ui.rs        # Layout, rendering, event loop
│   ├── markdown.rs  # Markdown-to-terminal renderer
│   ├── wizard.rs    # Shared wizard framework
│   ├── create_persona.rs  # Persona creation wizard
│   └── create_agent.rs    # Agent creation wizard
├── client.rs        # HTTP client for AI SDK API
├── config.rs        # Configuration file handling
├── streaming.rs     # SSE parser for streaming responses
└── error.rs         # Error types and handling

License

Apache-2.0