Skip to content

cli.md

Latest commit

 

History

History
351 lines (256 loc) · 8.85 KB

cli.md

File metadata and controls

351 lines (256 loc) · 8.85 KB
Raw

CLI Reference

Complete reference for the AgenticGoKit command-line interface

This document provides comprehensive reference for AgenticGoKit's command-line interface (agentcli), covering all commands, options, and usage patterns.

🏗️ Installation and Setup

Installation

# Install from source
go install github.com/kunalkushwaha/agenticgokit/cmd/agentcli@latest

# Or download binary from releases
curl -L https://github.com/kunalkushwaha/agenticgokit/releases/latest/download/agentcli-${OS}-${ARCH}.tar.gz | tar xz

Shell Completion

AgenticGoKit CLI supports intelligent tab completion for all major shells. This provides faster command usage and reduces typing errors.

Bash

# Load completion for current session
source <(agentcli completion bash)

# Install permanently on Linux
sudo agentcli completion bash > /etc/bash_completion.d/agentcli

# Install permanently on macOS (with Homebrew)
agentcli completion bash > $(brew --prefix)/etc/bash_completion.d/agentcli

Zsh

# Enable completion support (if not already enabled)
echo "autoload -U compinit; compinit" >> ~/.zshrc

# Install completion
agentcli completion zsh > "${fpath[1]}/_agentcli"

# Restart your shell or reload configuration
source ~/.zshrc

Fish

# Load completion for current session
agentcli completion fish | source

# Install permanently
agentcli completion fish > ~/.config/fish/completions/agentcli.fish

PowerShell

# Load completion for current session
agentcli completion powershell | Out-String | Invoke-Expression

# Install permanently
agentcli completion powershell > agentcli.ps1
# Add the following line to your PowerShell profile:
# . /path/to/agentcli.ps1

Completion Features:

  • Command completion: Tab completion for all available commands
  • Flag completion: Tab completion for all command flags and options
  • Template completion: Intelligent completion for --template flag with all available templates
  • Provider completion: Tab completion for --provider flag (openai, azure, ollama, mock)
  • Memory provider completion: Tab completion for --memory flag (memory, pgvector, weaviate)
  • File completion: Smart file completion for template validation and other file operations

📋 Command Structure

agentcli [global options] command [command options] [arguments...]

Global Options

Option Short Description Default
--config -c Path to configuration file agentflow.toml
--verbose -v Enable verbose output false
--quiet -q Suppress non-error output false
--help -h Show help information
--version Show version information

🚀 Available Commands

Based on the actual codebase, the following commands are available:

trace

View execution traces with detailed agent flows

# View a basic trace with all details
agentcli trace <session-id>

# View only the agent flow for a session
agentcli trace --flow-only <session-id>

# Filter trace to see only a specific agent's activity
agentcli trace --filter <agent-name> <session-id>

mcp

Manage Model Context Protocol servers and tools

# List connected MCP servers
agentcli mcp servers

# View MCP server status
agentcli mcp status

cache

Monitor and optimize MCP tool result caches

# View cache statistics
agentcli cache stats

# Clear specific caches
agentcli cache clear --server web-service

create

Create new AgenticGoKit projects with multi-agent workflows

# Create a basic project
agentcli create my-project

# Create from template
agentcli create my-project --template research-assistant

# Custom configuration with consolidated flags
agentcli create my-project --memory pgvector --embedding openai --rag 1500 --mcp standard

# Interactive mode for guided setup
agentcli create --interactive

# Show available templates
agentcli create help-templates

Key Features:

  • Template System: Pre-configured project templates for common use cases
  • Consolidated Flags: Simplified flag structure (12 flags instead of 32)
  • Intelligent Defaults: Automatic dependency resolution and sensible defaults
  • External Templates: Support for custom templates via JSON/YAML files
  • Interactive Mode: Guided project setup

Available Templates:

  • basic - Simple 2-agent sequential system
  • research-assistant - Multi-agent research with web search and analysis
  • rag-system - Document Q&A with vector search and RAG
  • data-pipeline - Sequential data processing workflow
  • chat-system - Conversational agents with memory

Consolidated Flags:

  • --template, -t - Project template name
  • --agents, -a - Number of agents to create
  • --provider, -p - LLM provider (openai, azure, ollama)
  • --memory - Memory system provider (memory, pgvector, weaviate)
  • --embedding - Embedding provider and model (openai, ollama:model, dummy)
  • --enable-mcp - Enable MCP with minimal configuration
  • --mcp - MCP integration level (minimal, standard, advanced)
  • --rag - Enable RAG with optional chunk size
  • --orchestration - Orchestration mode (sequential, collaborative, loop, route)
  • --visualize - Generate Mermaid workflow diagrams
  • --interactive, -i - Interactive mode for guided setup

template

Manage project templates

# List all available templates (built-in + custom)
agentcli template list

# Create a new custom template
agentcli template create my-template

# Validate a template file
agentcli template validate my-template.yaml

# Show template search paths
agentcli template paths

Template Locations: Templates are searched in the following locations (in priority order):

  1. Current directory: .agenticgokit/templates/
  2. User home: ~/.agenticgokit/templates/
  3. System-wide: /etc/agenticgokit/templates/ (Unix) or %PROGRAMDATA%/AgenticGoKit/templates/ (Windows)

Template Formats:

  • JSON format: my-template.json
  • YAML format: my-template.yaml or my-template.yml

list

List various resources

# List available resources
agentcli list

memory

Memory operations and management

# Memory operations
agentcli memory

completion

Generate shell completion scripts

# Generate completion for different shells
agentcli completion bash
agentcli completion zsh
agentcli completion fish
agentcli completion powershell

# Install completion (examples)
agentcli completion bash > /etc/bash_completion.d/agentcli
agentcli completion zsh > "${fpath[1]}/_agentcli"
agentcli completion fish > ~/.config/fish/completions/agentcli.fish

Supported Shells:

  • Bash (Linux, macOS, Windows with Git Bash)
  • Zsh (macOS default, Linux)
  • Fish (cross-platform)
  • PowerShell (Windows, cross-platform PowerShell Core)

version

Show version information

# Show basic version
agentcli version

# Show detailed version information
agentcli version --output detailed

# Show version in JSON format
agentcli version --output json

# Show short version only
agentcli version --short

📚 Usage Examples

Project Creation

# Quick project creation with templates
agentcli create research-bot --template research-assistant
agentcli create knowledge-base --template rag-system
agentcli create data-flow --template data-pipeline

# Custom configuration with consolidated flags
agentcli create custom-bot --memory pgvector --embedding openai --rag 1500 --mcp standard

# Interactive mode for guided setup
agentcli create --interactive

# Override template defaults
agentcli create my-research --template research-assistant --agents 5 --mcp advanced

Template Management

# List all available templates
agentcli template list

# Create a custom template
agentcli template create my-company-standard

# Validate template syntax
agentcli template validate my-template.yaml

# Show template search paths
agentcli template paths

Tracing and Debugging

# View execution traces
agentcli trace session-123

# Filter traces by agent
agentcli trace --filter chat-agent session-123

# View agent flow only
agentcli trace --flow-only session-123

MCP Management

# List MCP servers
agentcli mcp servers

# Check MCP status
agentcli mcp status

Cache Management

# View cache statistics
agentcli cache stats

# Clear cache for specific server
agentcli cache clear --server search-service

🔧 Configuration

The CLI uses the same agentflow.toml configuration file as the main framework. See the Configuration API for complete configuration options.

📝 Exit Codes

Code Description
0 Success
1 General error
2 Configuration error
3 Network/connectivity error

For complete CLI documentation and all available options, run:

agentcli --help
agentcli <command> --help