Aitana CLI Tool Documentation

The Aitana CLI is a powerful command-line tool for bulk processing files and requests using Aitana AI assistants. It provides efficient batch operations with Google Cloud Storage integration, intelligent permission management, and direct assistant interaction capabilities.

Table of Contents

• Installation
• Core Features
• Authentication
• Command Reference
  • Assistant Commands
  • Batch Processing Commands
  • Server Management
  • Direct API Access
• Environment Configuration
• Smart Defaults
• Examples
• API Integration
• Troubleshooting
• Development

Installation

# Install the CLI tool using UV
cd /Users/mark/dev/aitana-labs/frontend
uv tool install ./aitana --force

# Verify installation
aitana --version

# The CLI is now available globally at:
# /Users/mark/.local/bin/aitana

Core Features

• Bulk File Processing: Process multiple files from GCS buckets concurrently
• Batch API Requests: Execute batch requests from JSONL files
• Assistant Inspection: View assistant capabilities and tool configurations
• Direct Assistant Calls: Interact with assistants from the command line
• MCP Tool Integration: Access and call MCP (Model Context Protocol) tools
• Server Management: Start, stop, and monitor backend/frontend servers
• Smart Defaults: Automatically uses assistant’s default bucket and tools
• Authentication Management: Integrates with Google Cloud auth and supports email persistence
• Permission-Aware: Respects tool permissions based on user email
• Direct API Access: Call models and tools directly without assistants

Authentication

The CLI uses Google Application Default Credentials and supports email persistence:

Check Authentication Status

aitana auth

Save Email Preference

# Save email for all future commands
aitana --user-email mark@aitanalabs.com auth --save

# Now all commands will use this email automatically
aitana assistant inspect ASSISTANT_ID

Clear Saved Email

aitana auth --clear

Override Email for Single Command

# Global options must come before the command
aitana --user-email other@example.com assistant inspect ASSISTANT_ID

Command Reference

Command Structure

The Aitana CLI has been organized for better logical grouping:

aitana
├── assistant
│   ├── list      # List all available assistants
│   ├── inspect   # View assistant details
│   └── call      # Call assistant with prompt
├── batch-extract
│   ├── run       # Main extraction command
│   ├── create-sample # Create sample JSONL
│   └── process   # Process files/batch
│       ├── files # Process GCS bucket files
│       └── batch # Process JSONL batch requests
├── auth          # Authentication management
├── server        # Server management
├── model         # Direct model calls
├── tool          # Direct tool calls
│   ├── list      # List available tools (native & MCP)
│   ├── mcp       # Call MCP tools directly
│   ├── ai-search # Vertex AI search
│   ├── search    # Google search
│   └── url       # URL processing
└── api           # Direct API access
    └── call-mcp  # Call MCP tools via API

Assistant Commands

List All Assistants

# List all assistant instances (default)
aitana assistant list

# Include template assistants
aitana assistant list --templates

# Limit results
aitana assistant list -n 10

# Get JSON output for scripting
aitana assistant list --json-output

# Use with specific environment
aitana --env dev assistant list

The list command shows:

• Assistant ID
• Name
• Type (Instance/Template)
• Description (truncated)
• Available tools

Inspect Assistant

View assistant configuration, available tools, and permissions:

# Basic inspection
aitana assistant inspect e66d675c-12f0-4c7f-9ae6-272c7ea44a49

# With specific user email
aitana --user-email mark@aitanalabs.com assistant inspect ASSISTANT_ID

# Verbose output
aitana -v assistant inspect ASSISTANT_ID

Output shows:

• Assistant name and description
• Available tools with configurations
• Bucket access permissions
• Default tool configurations
• User permissions

Call Assistant

Directly interact with an assistant from the command line:

# Simple question to an assistant
aitana assistant call ASSISTANT_ID -p "What can you help me with?"

# Use specific tools
aitana assistant call ASSISTANT_ID -p "Search for Python documentation" -t google-search

# Save response to file
aitana assistant call ASSISTANT_ID -p "Explain your capabilities" -o capabilities.txt

# Save as JSON with metadata
aitana assistant call ASSISTANT_ID -p "Calculate 5+5" --json-output -o response.json

# Override tool configuration
aitana assistant call ASSISTANT_ID -p "List files in my bucket" \
  --config-override file-browser.bucketUrl=gs://my-custom-bucket/data/

# Using different environments
aitana --env dev assistant call ASSISTANT_ID -p "Hello"

# Verbose mode for debugging
aitana -v assistant call ASSISTANT_ID -p "Test prompt"

Call Command Options:

Option	Description	Example
-p, --prompt	Required. The question or prompt to send	-p "What is 2+2?"
-t, --tools	Comma-separated list of tools to use	-t google-search,file-browser
-o, --output	Save the response to a file	-o response.txt
--json-output	Output the raw JSON response	--json-output
--config-override	Override tool configurations	--config-override file-browser.bucketUrl=gs://my-bucket/
--chat-history	Load chat history from JSON file	--chat-history history.json
--save-history	Save conversation to Firestore	--save-history

Batch Processing Commands

Process Files

Bulk process files from Google Cloud Storage buckets:

# Use assistant's default bucket and tools
aitana batch-extract process files ASSISTANT_ID --prompt "Extract key information"

# Specify custom bucket and tools
aitana batch-extract process files ASSISTANT_ID \
  --bucket gs://my-bucket/data/ \
  --prompt "Analyze document" \
  --tools file-browser,preview

# Filter specific file types
aitana batch-extract process files ASSISTANT_ID \
  --prompt "Extract data" \
  --filter-pattern "*.pdf"

# Dry run to preview files
aitana batch-extract process files ASSISTANT_ID \
  --prompt "Test" \
  --dry-run

# Save results to file
aitana batch-extract process files ASSISTANT_ID \
  --prompt "Process" \
  --output results.json

# Control concurrency and limits
aitana batch-extract process files ASSISTANT_ID \
  --prompt "Analyze" \
  --concurrency 10 \
  --max-files 50

Process Files Options:

Option	Description	Default
--bucket	GCS bucket path (gs://bucket/path/)	Assistant’s default bucket
--prompt	Prompt to send with each file	Required
--tools	Comma-separated list of tools	file-browser (if available)
--config-override	Tool config overrides (tool.key=value)	None
--concurrency	Number of concurrent requests	5
--filter-pattern	File pattern filter (e.g., *.pdf)	None
--output	Output file for results	None
--max-files	Maximum files to process	1000
--dry-run	List files without processing	False

Process Batch

Process batch requests from JSONL files:

# Basic batch processing
aitana batch-extract process batch ASSISTANT_ID \
  --input-file requests.jsonl

# With specific tools and output
aitana batch-extract process batch ASSISTANT_ID \
  --input-file requests.jsonl \
  --output results.jsonl \
  --tools preview,highlights

# Override tool configurations
aitana batch-extract process batch ASSISTANT_ID \
  --input-file requests.jsonl \
  --config-override file-browser.bucketUrl=gs://other-bucket

JSONL Input Format:

Each line in the input file should be a JSON object:

{"question": "What is the main topic?", "documents": [{"uri": "gs://bucket/file.pdf"}]}
{"question": "Summarize this document", "documents": [{"uri": "gs://bucket/doc.txt"}]}

Server Management

The aitana server commands provide comprehensive server management:

# Start servers with automatic logging
aitana server start              # Start with cloud Firebase (default)
aitana server start --mode local # Start with Firebase emulators
aitana server start --no-frontend # Start only backend
aitana server start --no-backend  # Start only frontend
aitana server start --https      # Start backend with HTTPS (for MCP/Claude Desktop)

# Server control commands
aitana server status    # Check server status and PIDs
aitana server stop      # Stop all servers
aitana server restart   # Restart all servers

# Log management
aitana server logs              # View recent logs (last 50 lines)
aitana server logs -n 100       # View last 100 lines
aitana server logs -f           # Follow logs (tail -f)
aitana server logs -s frontend  # View specific service logs
aitana server analyze           # Analyze logs for errors/warnings
aitana server clean-logs        # Clean all log files

Direct API Access

Model Commands

Call AI models directly without using assistants:

# Call Gemini model
aitana model gemini "Explain quantum computing"

# Call Claude model
aitana model claude "Write a Python function to sort a list"

# Specify model version
aitana model gemini "What is AI?" --model-name gemini-2.5-flash

# Control temperature and max tokens
aitana model gemini "Creative story" --temperature 0.9 --max-tokens 2048

# Save output to file
aitana model claude "Analysis" -o result.txt

# JSON output
aitana model gemini "Test" --json-output

Tool Commands

Call tools directly:

# AI Search
aitana tool ai-search -d aitana3 "BESS Germany" --full-output
aitana tool ai-search -d aitana3 "query" --max-length 5000

# Google Search
aitana tool search "battery energy storage systems"

# URL Processing
aitana tool url "What is BESS?" -u https://example.com

# Control output
aitana tool ai-search -d aitana3 "query" --full-output  # No truncation
aitana tool search "query" --max-length 3000  # Custom limit

Output Control Options:

• --full-output: Show complete output without any truncation
• --max-length <number>: Set custom character limit
• Default: 2000 characters

MCP Tool Commands

Access and call MCP (Model Context Protocol) tools:

List Available Tools

# List native tools only (default)
aitana tool list

# Include MCP server tools
aitana tool list --include-mcp

# Show only MCP tools
aitana tool list --mcp-only

# Get JSON output for scripting
aitana tool list --include-mcp --json-output

Call MCP Tools

Two methods to call MCP tools:

Method 1: Using tool mcp command (recommended)

# Call with server specified
aitana tool mcp demo_greeting -s demo -a '{"name": "Alice", "language": "es"}'

# Auto-detect server from tool name prefix
aitana tool mcp demo_random_fact    # Detects 'demo' server
aitana tool mcp mcp_demo_calculator -a '{"operation": "add", "a": 5, "b": 3}'

# Get JSON output
aitana tool mcp demo_system_info -s demo --json-output

# Examples with demo server tools
aitana tool mcp demo_text_processor -s demo -a '{"text": "Hello World", "operation": "reverse"}'
aitana tool mcp demo_data_analyzer -s demo -a '{"data": [1, 2, 3, 4, 5]}'

Method 2: Using api call-mcp command

# Direct API call to MCP tool
aitana api call-mcp demo demo_greeting -a '{"name": "Bob", "language": "fr"}'

# Without arguments
aitana api call-mcp demo demo_random_fact

# JSON output
aitana api call-mcp demo demo_calculator -a '{"operation": "multiply", "a": 7, "b": 8}' --json-output

Available MCP Servers

Currently registered MCP servers:

Server ID	Description	Example Tools
demo	Demo MCP server with example tools	demo_greeting, demo_calculator, demo_text_processor, demo_random_fact, demo_data_analyzer, demo_system_info
aitana	Main Aitana MCP tools	assistant_list, assistant_inspect, assistant_call, user_history, ai_search, google_search

MCP Tool Name Patterns

The CLI supports auto-detection of MCP servers from tool names:

• demo_* → Automatically uses demo server
• mcp_demo_* → Extracts server ID (demo) from prefix
• aitana_* → Automatically uses aitana server
• Other patterns → Defaults to demo server

MCP Implementation Notes

• API-Based: All MCP operations use API calls (no direct backend imports)
• Auto-Detection: Tool names can include server prefixes for convenience
• JSON Arguments: Tool arguments must be valid JSON
• Error Handling: Clear error messages for invalid servers or tools
• See aitana/CLAUDE.md for CLI development guidelines

Environment Configuration

Select different deployment environments:

# Local development (default)
aitana --env local assistant inspect ASSISTANT_ID

# Development environment
aitana --env dev assistant inspect ASSISTANT_ID

# Test environment
aitana --env test assistant inspect ASSISTANT_ID

# Production environment
aitana --env prod assistant inspect ASSISTANT_ID

# Custom API base URL
aitana --api-base http://localhost:1956 assistant inspect ASSISTANT_ID

Environment URLs:

Environment	Base URL
local	http://localhost:1956
dev	https://backend-dev-aitana-yfdacnqgxq-ew.a.run.app
test	https://backend-test-aitana-yfdacnqgxq-ew.a.run.app
prod	https://backend-prod-aitana-yfdacnqgxq-ew.a.run.app

Smart Defaults

The CLI intelligently uses assistant configurations:

1. Bucket Selection Priority:
   • Explicitly specified --bucket option
   • Assistant’s configured bucketUrl from tool configs
   • Assistant’s bucket access configurations
   • Error if no bucket found
2. Tool Selection Priority:
   • Explicitly specified --tools option
   • file-browser if available in assistant’s tools
   • First 3 available tools as fallback
   • All available tools if needed
3. Tool Configuration Merging:
   • Starts with assistant’s default tool configurations
   • Applies user overrides via --config-override
   • Maintains assistant-specific settings

Examples

Example 1: Document Classification

# Save email preference once
aitana --user-email mark@aitanalabs.com auth --save

# Inspect assistant capabilities
aitana assistant inspect e66d675c-12f0-4c7f-9ae6-272c7ea44a49

# Dry run to see files
aitana batch-extract process files e66d675c-12f0-4c7f-9ae6-272c7ea44a49 \
  --prompt "Classify document type" \
  --dry-run

# Process all PDFs
aitana batch-extract process files e66d675c-12f0-4c7f-9ae6-272c7ea44a49 \
  --prompt "Classify document as: contract, invoice, or report" \
  --filter-pattern "*.pdf" \
  --output classifications.json

Example 2: Bulk Data Extraction

# Process with custom bucket and high concurrency
aitana batch-extract process files ASSISTANT_ID \
  --bucket gs://data-bucket/contracts/ \
  --prompt "Extract parties, dates, and amounts" \
  --tools structured_extraction \
  --concurrency 20 \
  --max-files 100 \
  --output extractions.json

Example 3: Batch API Processing

# Create batch input file
cat > requests.jsonl << EOF
{"question": "Summarize main points", "documents": [{"uri": "gs://bucket/doc1.pdf"}]}
{"question": "Extract key terms", "documents": [{"uri": "gs://bucket/doc2.pdf"}]}
EOF

# Process batch
aitana batch-extract process batch ASSISTANT_ID \
  --input-file requests.jsonl \
  --output results.jsonl \
  --tools preview,highlights \
  --concurrency 10

Example 4: Direct Assistant Interaction

# Quick question
aitana assistant call ASSISTANT_ID -p "What is machine learning?"

# Complex analysis with file output
aitana assistant call ASSISTANT_ID \
  -p "Analyze the pros and cons of renewable energy" \
  -t google-search \
  -o analysis.txt

# Scripting example
#!/bin/bash
RESPONSE=$(aitana assistant call ASSISTANT_ID -p "Calculate 10*10" --json-output)
ANSWER=$(echo "$RESPONSE" | jq -r '.response')
echo "The answer is: $ANSWER"

Example 5: MCP Tool Usage

# List all available tools including MCP
aitana tool list --include-mcp

# Call demo MCP tools
aitana tool mcp demo_greeting -s demo -a '{"name": "Alice", "language": "es"}'
# Output: ¡Hola Alice! Bienvenido al Servidor MCP Demo de Aitana.

# Get a random fact
aitana tool mcp demo_random_fact -s demo

# Perform calculations
aitana tool mcp demo_calculator -s demo -a '{"operation": "multiply", "a": 7, "b": 8}'

# Process text
aitana tool mcp demo_text_processor -s demo \
  -a '{"text": "Hello World", "operation": "reverse"}'

# Analyze data
aitana tool mcp demo_data_analyzer -s demo \
  -a '{"data": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]}'

# Use with JSON output for scripting
RESULT=$(aitana tool mcp demo_system_info -s demo --json-output)
echo "$RESULT" | jq '.content[0].text' | jq '.'

API Integration

API Endpoints & Curl Equivalents

AI Search Tool

CLI Command:

aitana tool ai-search -d aitana3 "BESS Germany"

Curl Equivalent:

curl -X POST http://localhost:1956/direct/tools/ai-search \
  -H "Content-Type: application/json" \
  -d '{
    "question": "BESS Germany",
    "datastore_id": "aitana3",
    "filter_str": "",
    "do_limit_content": true
  }'

Assistant List

CLI Command:

aitana assistant list

Curl Equivalent:

curl -X GET "http://localhost:1956/vac/assistants?include_templates=false&include_instances=true&limit=100" \
  -H "Accept: application/json"

Assistant Call

CLI Command:

aitana assistant call ASSISTANT_ID -p "What can you help me with?"

Curl Equivalent:

curl -X POST http://localhost:1956/vac/assistant/ASSISTANT_ID \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What can you help me with?",
    "tools": ["google-search", "file-browser"],
    "tool_configs": {},
    "user_email": "user@example.com"
  }'

Pretty-Printing JSON Responses

For better readability when using curl:

# Use python's json.tool
curl -X POST http://localhost:1956/direct/tools/ai-search \
  -H "Content-Type: application/json" \
  -d '{"question": "BESS", "datastore_id": "aitana3"}' \
  | python -m json.tool

# Use jq if installed
curl -X POST http://localhost:1956/direct/tools/ai-search \
  -H "Content-Type: application/json" \
  -d '{"question": "BESS", "datastore_id": "aitana3"}' \
  | jq '.'

Troubleshooting

Authentication Issues

# Check current authentication
aitana auth

# Re-authenticate with Google Cloud
gcloud auth application-default login

# Verify which email is being used
aitana --verbose assistant inspect ASSISTANT_ID

Connection Errors

# For local development, ensure backend is running
aitana server start

# Check server status
aitana server status

# Use deployed environments if local isn't working
aitana --env dev assistant inspect ASSISTANT_ID

Assistant Not Found

• Ensure the backend server is running: aitana server status
• Check the assistant ID is correct
• Verify you have access to the assistant

No Response Received

• Check backend logs: aitana server logs -s backend
• Ensure the assistant has appropriate tools configured
• Try with verbose mode: aitana -v assistant call ...

Permission Denied

# Ensure your email has permissions for the assistant
aitana --user-email your@email.com assistant inspect ASSISTANT_ID

# Check available tools for your email
# The output will show which tools you have access to

GCS Access Issues

# Verify GCS credentials
gcloud auth application-default login

# Test bucket access
gsutil ls gs://bucket-name/

# Use dry-run to test without processing
aitana batch-extract process files ASSISTANT_ID --prompt "test" --dry-run

Advanced Usage

Tool Configuration Overrides

Override specific tool configurations:

# Change bucket for file-browser
aitana batch-extract process files ASSISTANT_ID \
  --prompt "Analyze" \
  --config-override file-browser.bucketUrl=gs://other-bucket

# Multiple overrides
aitana batch-extract process files ASSISTANT_ID \
  --prompt "Process" \
  --config-override file-browser.no-stream=false \
  --config-override structured_extraction.schema=custom_schema

Custom Configuration File

Create a configuration file for complex setups:

# Use custom config
aitana --config my-config.json batch-extract process files ASSISTANT_ID --prompt "Process"

Verbose Debugging

# Enable verbose output for debugging
aitana --verbose batch-extract process files ASSISTANT_ID \
  --prompt "Debug test" \
  --dry-run

Environment Variables

Set default environment to avoid specifying --env each time:

export AITANA_ENV=dev
aitana assistant list  # Will use dev environment

Performance Considerations

1. Concurrency: Default is 5 concurrent requests. Increase for better throughput:

   --concurrency 20  # For high-performance processing
   

2. Max Files: Default limit is 1000 files. Adjust as needed:

   --max-files 50  # For testing
   --max-files 10000  # For large batches
   

3. Network: Ensure stable connection for bulk operations

4. Rate Limiting: The tool includes automatic throttling to prevent API overload

Security Notes

• Credentials are managed via Google Application Default Credentials
• User email preferences are stored in ~/.aitana/user_config.json with restrictive permissions (0600)
• API tokens are never stored in plain text
• Tool permissions are enforced server-side based on user email

Development

Project Structure

aitana/
├── __main__.py          # CLI entry point with all commands
├── api_client.py        # HTTP client for backend API
├── auth_manager.py      # Google auth and email management
├── config_manager.py    # Configuration parsing
├── server_manager.py    # Server start/stop/status commands
├── processors/          # Batch processing modules
│   ├── bulk_files.py    # GCS file processing
│   └── batch_api.py     # Batch request processing
└── CLAUDE.md           # Development guidelines for CLI

Architecture Principles

IMPORTANT: The aitana CLI uses API calls exclusively. Never import backend modules directly.

Key principles from aitana/CLAUDE.md:

• API-Based: All backend interactions go through HTTP API calls
• Isolated Environment: CLI runs in its own UV virtual environment
• No Backend Dependencies: Don’t add packages like fastmcp, sunholo, etc.
• Reinstall After Changes: Run uv tool install ./aitana --force

Adding New Commands

1. Add command to __main__.py using Click decorators
2. Add corresponding API method in api_client.py
3. Follow the async pattern for API calls
4. Update this documentation
5. See aitana/CLAUDE.md for detailed guidelines

Testing

# Reinstall CLI after changes
uv tool install ./aitana --force

# Test commands
aitana tool list --include-mcp
aitana tool mcp demo_greeting -s demo -a '{"name": "Test"}'

# Test with different environments
aitana --env dev tool list

# Verbose mode for debugging
aitana -v tool mcp demo_random_fact -s demo

Command Migration Guide

If you were using the old command structure, here’s how to update:

Old Command	New Command
aitana inspect ASSISTANT_ID	aitana assistant inspect ASSISTANT_ID
aitana create-sample	aitana batch-extract create-sample
aitana process files ...	aitana batch-extract process files ...
aitana process batch ...	aitana batch-extract process batch ...
aitana batch-extract ASSISTANT_ID ...	aitana batch-extract run ASSISTANT_ID ...

Tips & Best Practices

1. Use --full-output for complete responses: When analyzing detailed search results or extracted content, use --full-output to avoid truncation.

2. Save JSON output for processing:

   aitana assistant list --json-output > assistants.json
   aitana tool ai-search -d aitana3 "query" --full-output > results.txt
   

3. Batch operations for efficiency: Use the batch-extract commands for processing multiple files instead of calling tools individually.

4. Use verbose mode for debugging:

   aitana -v tool ai-search -d aitana3 "query"
   

Limitations

1. No Real-time Streaming: Due to backend architecture using callback-based streaming, responses are fetched completely before display
2. Chat History: Currently, chat history from JSON file is loaded but not fully integrated with the conversation context
3. Save History: The --save-history flag is present but not fully implemented

Future Enhancements

• MCP tool integration - Complete list and call functionality
• Better chat history integration
• Support for file attachments/documents in assistant calls
• Interactive mode for continuous conversation
• Batch processing of multiple prompts from file
• Auto-discovery of new MCP servers
• MCP resource access (beyond just tools)

Support

For issues or feature requests, please contact the Aitana team or file an issue in the repository.