CLI Commands

Complete reference for the aip command-line interface.

📚 Overview

The aip CLI provides a powerful command-line interface for managing AIP resources. It supports multiple output formats, shell completion, and comprehensive resource management.

🚀 Quick Start

# Install CLI
pipx install glaip-sdk

# Configure credentials
aip init

# Check status
aip status

# Create and run an agent
aip agents create --name "hello" --instruction "Be helpful"
aip agents run <AGENT_ID> --input "Hello!"

🔧 Global Options

All commands support these global options:

aip [OPTIONS] COMMAND [ARGS]...

Options:
  --api-url TEXT     AIP API URL [env var: AIP_API_URL]
  --api-key TEXT     AIP API Key [env var: AIP_API_KEY]
  --timeout FLOAT    Request timeout in seconds [default: 30.0]
  --view [rich|plain|json|md]  Output view format [default: rich]
  --no-tty          Disable TTY renderer
  --version         Show version and exit
  --help            Show this message and exit

🤖 Agent Commands

List Agents

aip agents list [OPTIONS]

Options:
  --view [rich|plain|json|md]  Output format [default: rich]
  --help            Show this message and exit

Examples:

# List all agents
aip agents list

# JSON output for scripting
aip agents list --view json

Create Agent

aip agents create [OPTIONS]

Options:
  --name TEXT                     Agent name [required]
  --instruction TEXT              Agent instruction (prompt) [required]
  --tools TEXT                    Tool names or IDs to attach (multiple)
  --agents TEXT                   Sub-agent names to attach (multiple)
  --timeout INTEGER               Execution timeout in seconds [default: 300]
  --view [rich|plain|json|md]    Output format [default: rich]
  --help                          Show this message and exit

Examples:

# Create basic agent
aip agents create --name "math-tutor" --instruction "Help with math"

# Create agent with tools
aip agents create --name "assistant" --instruction "Be helpful" --tools tool1 --tools tool2

# Create agent with sub-agents
aip agents create --name "coordinator" --instruction "Coordinate tasks" --agents agent1 --agents agent2

Get Agent

aip agents get [OPTIONS] AGENT_REF

Options:
  --select INTEGER                Choose among ambiguous matches (1-based)
  --view [rich|plain|json|md]    Output format [default: rich]
  --help                         Show this message and exit

Examples:

# Get agent by ID
aip agents get agent-123

# Get agent by name (with ambiguity handling)
aip agents get "math-tutor"

# Get agent by name with selection
aip agents get "assistant" --select 1

# JSON output
aip agents get agent-123 --view json

Run Agent

aip agents run [OPTIONS] AGENT_ID --input TEXT

Options:
  --input TEXT                    Input message for the agent [required]
  --file PATH                     Attach file(s) (multiple)
  --chat-history TEXT             JSON string of chat history
  --timeout INTEGER               Request timeout in seconds [default: 600]
  --view [rich|plain|json|md]    Output view format [default: rich]
  --compact/--verbose             Collapse tool steps [default: compact]
  --save PATH                     Save transcript to file (md or json)
  --theme [dark|light]           Color theme [default: dark]
  --help                          Show this message and exit

Examples:

# Run agent with text input
aip agents run agent-123 --input "What is 2 + 2?"

# Run with file upload
aip agents run agent-123 --input "Analyze this file" --file document.pdf

# Run with multiple files
aip agents run agent-123 --input "Process these files" --file file1.txt --file file2.txt

# JSON output for scripting
aip agents run agent-123 --input "Hello" --view json

# Save transcript
aip agents run agent-123 --input "Long analysis" --save transcript.md

Update Agent

aip agents update [OPTIONS] AGENT_ID

Options:
  --name TEXT                     New agent name
  --instruction TEXT              New instruction
  --tools TEXT                    New tool names or IDs (multiple)
  --agents TEXT                   New sub-agent names (multiple)
  --timeout INTEGER               New timeout value
  --view [rich|plain|json|md]    Output format [default: rich]
  --help                          Show this message and exit

Examples:

# Update instruction
aip agents update agent-123 --instruction "Updated instructions"

# Update multiple fields
aip agents update agent-123 --name "new-name" --timeout 600

# Update tools
aip agents update agent-123 --tools tool1 --tools tool2

Delete Agent

aip agents delete [OPTIONS] AGENT_ID

Options:
  -y, --yes                       Skip confirmation
  --view [rich|plain|json|md]    Output format [default: rich]
  --help                          Show this message and exit

Examples:

# Delete agent with confirmation
aip agents delete agent-123

# Delete agent without confirmation
aip agents delete agent-123 --yes

# Confirm deletion
aip agents delete agent-123 --view plain

🛠️ Tool Commands

List Tools

aip tools list [OPTIONS]

Options:
  --view [rich|plain|json|md]    Output format [default: rich]
  --help                          Show this message and exit

Examples:

# List all tools
aip tools list

# JSON output
aip tools list --view json

Create Tool

aip tools create [OPTIONS]

Options:
  --file PATH                     Tool file to upload (optional for metadata-only tools)
  --name TEXT                     Tool name (required for metadata-only tools, extracted from script if file provided)
  --description TEXT              Tool description (optional - extracted from script if file provided)
  --tags TEXT                     Comma-separated tags for the tool
  --view [rich|plain|json|md]    Output format [default: rich]
  --help                          Show this message and exit

Examples:

# Create from Python file
aip tools create --file calculator_tool.py

# Create with custom name and description
aip tools create --file my_tool.py --name "custom-tool" --description "My custom tool"

# Create metadata-only tool
aip tools create --name "native-tool" --description "Native tool description"

# Create with tags
aip tools create --file my_tool.py --tags "math,calculator,utility"

Get Tool

aip tools get [OPTIONS] TOOL_REF

Options:
  --select INTEGER                Choose among ambiguous matches (1-based)
  --view [rich|plain|json|md]    Output format [default: rich]
  --help                          Show this message and exit

Examples:

# Get tool by ID
aip tools get tool-123

# Get tool by name (with ambiguity handling)
aip tools get "calculator"

# Get tool by name with selection
aip tools get "assistant" --select 1

# JSON output
aip tools get tool-123 --view json

Update Tool

aip tools update [OPTIONS] TOOL_ID

Options:
  --name TEXT                     New tool name
  --description TEXT              New tool description
  --view [rich|plain|json|md]    Output format [default: rich]
  --help                          Show this message and exit

Examples:

# Update description
aip tools update tool-123 --description "Updated description"

# Update multiple fields
aip tools update tool-123 --name "new-name" --description "New description"

Delete Tool

aip tools delete [OPTIONS] TOOL_REF

Options:
  --select INTEGER                Choose among ambiguous matches (1-based)
  --view [rich|plain|json|md]    Output format [default: rich]
  --help                          Show this message and exit

Examples:

# Delete tool by ID
aip tools delete tool-123

# Delete tool by name
aip tools delete "calculator"

🔌 MCP Commands

List MCPs

aip mcps list [OPTIONS]

Options:
  --view [rich|plain|json|md]    Output format [default: rich]
  --help                          Show this message and exit

Examples:

# List all MCPs
aip mcps list

# JSON output
aip mcps list --view json

Create MCP

aip mcps create [OPTIONS]

Options:
  --name TEXT                     MCP name [required]
  --transport TEXT                MCP transport protocol [required]
  --description TEXT              MCP description
  --config TEXT                   JSON configuration string
  --view [rich|plain|json|md]    Output format [default: rich]
  --help                          Show this message and exit

Examples:

# Create from config file
aip mcps create --name "weather" --transport "http" --config "$(cat weather-config.json)"

# Create with inline config
aip mcps create --name "database" --transport "http" --config '{"url": "http://localhost:8080"}'

# Create with description
aip mcps create --name "api-service" --transport "http" --description "External API integration"

Get MCP

aip mcps get [OPTIONS] MCP_REF

Options:
  --select INTEGER                Choose among ambiguous matches (1-based)
  --view [rich|plain|json|md]    Output format [default: rich]
  --help                          Show this message and exit

Examples:

# Get MCP by ID
aip mcps get mcp-123

# Get MCP by name
aip mcps get "weather"

Test MCP Connection

aip mcps test-connection [OPTIONS] --from-file PATH

Options:
  --from-file PATH              Path to MCP configuration file [required]
  --view [rich|plain|json|md]  Output format [default: rich]
  --help                        Show this message and exit

Examples:

# Test MCP connection
aip mcps test-connection --from-file "weather-config.json"

Update MCP

aip mcps update [OPTIONS] MCP_ID

Options:
  --name TEXT                     New MCP name
  --description TEXT              New description
  --config TEXT                   New MCP configuration JSON
  --view [rich|plain|json|md]    Output format [default: rich]
  --help                          Show this message and exit

Examples:

# Update MCP configuration
aip mcps update mcp-123 --config '{"url": "https://new-api.example.com"}'

# Update description
aip mcps update mcp-123 --description "Updated description"

Delete MCP

aip mcps delete [OPTIONS] MCP_REF

Options:
  --select INTEGER                Choose among ambiguous matches (1-based)
  --view [rich|plain|json|md]    Output format [default: rich]
  --help                          Show this message and exit

Examples:

# Delete MCP by ID
aip mcps delete mcp-123

# Delete MCP by name
aip mcps delete "weather"

🌐 Model Commands

List Models

aip models list [OPTIONS]

Options:
  --view [rich|plain|json|md]    Output format [default: rich]
  --help                          Show this message and exit

Examples:

# List available models
aip models list

# JSON output
aip models list --view json

⚙️ Configuration Commands

Show Configuration

aip config show [OPTIONS]

Options:
  --view [rich|plain|json|md]    Output format [default: rich]
  --help                          Show this message and exit

Examples:

# Show current configuration
aip config show

# JSON output
aip config show --view json

Set Configuration

aip config set [OPTIONS] KEY VALUE

Options:
  --view [rich|plain|json|md]    Output format [default: rich]
  --help                          Show this message and exit

Examples:

# Set API URL
aip config set api_url "https://api.example.com"

# Set API key
aip config set api_key "sk-..."

Initialize Configuration

aip init [OPTIONS]

Options:
  --api-url TEXT                  AIP API URL
  --api-key TEXT                  AIP API Key
  --view [rich|plain|json|md]    Output format [default: rich]
  --help                          Show this message and exit

Examples:

# Interactive configuration
aip init

# Non-interactive configuration
aip init --api-url "https://api.example.com" --api-key "sk-..."

🏥 System Commands

Status

aip status [OPTIONS]

Options:
  --view [rich|plain|json|md]    Output format [default: rich]
  --help                          Show this message and exit

Examples:

# Check connection status
aip status

# Plain output
aip status --view plain

Update

aip update [OPTIONS]

Options:
  --view [rich|plain|json|md]    Output format [default: rich]
  --help                          Show this message and exit

Examples:

# Update AIP SDK to latest version
aip update

📊 Output Formats

Rich (Default)

Beautiful, interactive output with colors, tables, and formatting.

aip agents list  # Default rich output

Plain

Simple text output suitable for scripts and CI/CD.

aip agents list --view plain

JSON

Machine-readable output for automation and scripting.

aip agents list --view json

Markdown

Formatted output suitable for documentation.

aip agents list --view md

🔧 Shell Completion

Enable tab completion for faster CLI usage:

# Bash
# Note: Shell completion is not currently implemented
# aip --show-completion >> ~/.bashrc

# Zsh
# aip --show-completion >> ~/.zshrc

# Fish
# aip --show-completion >> ~/.config/fish/completions/aip.fish

# Reload shell
source ~/.bashrc  # or ~/.zshrc

📝 Examples

Complete Workflow

#!/bin/bash
# Create and run an agent workflow

# Create agent
aip agents create \
  --name "hello-world" \
  --instruction "Be friendly and helpful" \
  --view json

# Get agent ID from the output above
aip agents run <AGENT_ID> --input "Hello! How are you today?"

# Clean up
aip agents delete <AGENT_ID>
echo "Workflow completed"

Batch Processing

#!/bin/bash
# Process multiple files with an agent

# Get agent ID from your agents list
aip agents list

# Process each file manually
aip agents run <AGENT_ID> \
  --input "Analyze this file" \
  --file file1.txt \
  --view json > analysis_file1.txt.json

aip agents run <AGENT_ID> \
  --input "Analyze this file" \
  --file file2.txt \
  --view json > analysis_file2.txt.json

echo "Batch processing complete"

Configuration Management

#!/bin/bash
# Set up configuration for different environments

# Development
aip config set api_url "https://dev-api.example.com"
aip config set api_key "dev-key"

# Production
aip config set api_url "https://api.example.com"
aip config set api_key "prod-key"

# Show current config
aip config show

🚨 Error Handling

Common Error Scenarios

# Authentication error
aip status
# Error: 401 Unauthorized
# Solution: aip config set api_key "your-key"

# Connection error
aip status
# Error: Connection refused
# Solution: Check API URL with aip config show

# Resource not found
aip agents get invalid-id
# Error: 404 Not Found
# Solution: Use aip agents list to see available resources

Debug Mode

# Enable debug output
export AIP_LOG_LEVEL=DEBUG

# Run command with debug info
aip agents list

← Back to Reference

CLI documentation is generated from the actual Click command tree and kept up-to-date automatically.

PreviousPython SDK API NextREST API

📚 Overview

🚀 Quick Start

🔧 Global Options

🤖 Agent Commands

List Agents

Create Agent

Get Agent

Run Agent

Update Agent

Delete Agent

🛠️ Tool Commands

List Tools

Create Tool

Get Tool

Update Tool

Delete Tool

🔌 MCP Commands

List MCPs

Create MCP

Get MCP

Test MCP Connection

Update MCP

Delete MCP

🌐 Model Commands

List Models

⚙️ Configuration Commands

Show Configuration

Set Configuration

Initialize Configuration

🏥 System Commands

Status

Update

📊 Output Formats

Rich (Default)

Plain

JSON

Markdown

🔧 Shell Completion

📝 Examples

Complete Workflow

Batch Processing

Configuration Management

🚨 Error Handling

Common Error Scenarios

Debug Mode

🔗 Navigation