Aitana CLI API Commands

The Aitana CLI provides direct access to backend API endpoints for testing, debugging, and automation. These commands allow you to interact with models, tools, and agents without going through the web interface.

Table of Contents

• Installation
• API Information Commands
• Model Commands
• Tool Commands
• Testing
• Examples

Installation

Ensure the Aitana CLI is installed:

# From the frontend directory
uv tool install ./aitana --force

API Information Commands

List API Overview

aitana api info

Shows API version, available categories, and documentation links.

List Available Tools

aitana api tools

Displays all available tool endpoints with their descriptions.

List Available Models

aitana api models

Shows all available model endpoints and their supported model variants.

Model Commands

Gemini Models

aitana model gemini "Your prompt here" [OPTIONS]

Options:
  --model, -m        Model name (default: gemini-2.0-flash)
  --temperature, -t  Temperature 0.0-2.0 (default: 0.7)
  --max-tokens       Maximum tokens (default: 2048)

Available models:

• gemini-2.5-pro-exp
• gemini-2.5-pro
• gemini-2.5-flash
• gemini-2.5-flash-lite
• gemini-2.0-flash-thinking-exp
• gemini-2.0-flash

Anthropic Models

aitana model anthropic "Your prompt here" [OPTIONS]

Options:
  --model, -m        Model name (default: claude-3-5-haiku-20241022)
  --temperature, -t  Temperature 0.0-2.0 (default: 0.7)

Available models:

• claude-opus-4-1-20250805
• claude-sonnet-4-20250514
• claude-3-7-sonnet-20250219
• claude-3-5-sonnet-20241022
• claude-3-5-haiku-20241022

OpenAI Models

aitana model openai "Your prompt here" [OPTIONS]

Options:
  --model, -m        Model name (default: openai-gpt-5)
  --temperature, -t  Temperature 0.0-2.0 (default: 0.7)

Available models:

• openai-gpt-5 - Most advanced (fallback: gpt-4o)
• openai-gpt-5-mini - Fast and efficient (fallback: gpt-4o-mini)
• openai-gpt-5-nano - Ultra-lightweight (fallback: gpt-3.5-turbo)
• openai-o3 - Advanced reasoning (fallback: o1-preview)
• openai-o3-mini - Efficient reasoning (fallback: o1-mini)

Smart Unified Endpoint

aitana model smart "Your prompt here" [OPTIONS]

Options:
  --tool, -t  Smart tool/model to use (default: gemini-2.5-flash)

Available tools:

• Anthropic Models:
  • anthropic-3.7-sonnet
  • anthropic-3.5-sonnet
  • anthropic-4.0-sonnet
  • anthropic-4.0-opus
  • anthropic-4.1-opus
• Gemini Models:
  • gemini-2.5-pro
  • gemini-2.5-flash
  • gemini-2.5-flash-thinking
  • gemini-2.5-pro-thinking
• OpenAI Models:
  • openai-gpt-5
  • openai-gpt-5-mini
  • openai-gpt-5-nano
  • openai-o3
  • openai-o3-mini

Tool Commands

Google Search

aitana tool search "search query"

Performs a Google search and returns AI-processed results.

Structured Data Extraction

aitana tool extract "text to extract from" [OPTIONS]

Options:
  --schema, -s       Schema name (default: summary)
  --custom-schema    Path to custom schema JSON file

Built-in schemas:

• summary - Extract a structured summary with key points

URL Processing

aitana tool url "question about URLs" [OPTIONS]

Options:
  --url, -u  URL(s) to process (required, can be multiple)

Example:

aitana tool url "What are these pages about?" \
  --url https://example.com \
  --url https://another.com

AI Search (Vertex AI)

aitana tool ai-search "search query" [OPTIONS]

Options:
  --datastore, -d   Datastore ID (required)
  --filter, -f      Filter string (optional)
  --limit/--no-limit  Limit content (default: true)

Extract Files from GCS

aitana tool extract-files "question/instruction" [OPTIONS]

Options:
  --gs-uri, -g       GCS URI(s) to extract from (required, can be multiple)
  --batch-size, -b   Batch size (default: 10)
  --timeout, -t      Timeout per file in seconds (default: 120)
  --sequential       Force sequential processing

User History Search

aitana tool user-history "search query" [OPTIONS]

Options:
  --email, -e   User email or domain (required)
  --type, -t    Search type: email or domain (default: email)

Testing

Test All Endpoints

A comprehensive test script is provided to validate all API endpoints:

# Run the test script
./scripts/test_aitana_api_commands.sh

The test script will:

1. Check server health
2. Test all API information endpoints
3. Test all model endpoints
4. Test all tool endpoints
5. Generate a summary report

Configuration

Edit the test script to configure:

• TEST_AI_SEARCH - Enable/disable AI search tests
• TEST_EXTRACT_FILES - Enable/disable file extraction tests
• TEST_USER_HISTORY - Enable/disable user history tests
• DATASTORE_ID - Datastore for AI search
• GS_URI - GCS file for extraction tests

Examples

Quick Model Comparison

# Compare responses from different models
aitana model gemini "Explain quantum computing in one sentence"
aitana model anthropic "Explain quantum computing in one sentence"
aitana model smart "Explain quantum computing in one sentence" --tool anthropic-4.1-opus

Research Workflow

# Search for information
aitana tool search "latest developments in AI safety 2025"

# Process specific URLs
aitana tool url "Summarize the key points" \
  --url https://arxiv.org/abs/2025.12345 \
  --url https://openai.com/research/safety

# Extract structured data
aitana tool extract "The paper discusses three main approaches..." \
  --schema summary

Document Processing

# Process a PDF from GCS
aitana tool extract-files "Extract all technical requirements" \
  --gs-uri gs://my-bucket/specifications.pdf

# Search in a datastore
aitana tool ai-search "compliance requirements" \
  --datastore company-docs-datastore

Custom Schema Extraction

Create a custom schema file (person_schema.json):

{
  "type": "object",
  "properties": {
    "name": {"type": "string"},
    "age": {"type": "number"},
    "occupation": {"type": "string"},
    "location": {"type": "string"}
  },
  "required": ["name"]
}

Use it for extraction:

aitana tool extract "John Doe, 35, works as an engineer in Seattle" \
  --custom-schema person_schema.json

Environment Selection

All commands support environment selection:

# Use local backend (default)
aitana api info

# Use development environment
aitana --env dev api info

# Use production environment
aitana --env prod model gemini "Hello"

# Override with custom URL
aitana --api-base https://custom-backend.com api info

Error Handling

Common issues and solutions:

Backend Not Running

❌ Backend server is not running

Solution: Start the backend with aitana server start --no-frontend

Authentication Required

❌ Authentication required

Solution: Run aitana auth or use --user-email flag

Invalid Model/Tool

Check available options with:

aitana api models  # List available models
aitana api tools   # List available tools

Output Formats

All commands output formatted results to the console. For automation, you can redirect output:

# Save to file
aitana model gemini "Generate a report" > report.txt

# Parse JSON responses
aitana tool extract "..." --schema summary | jq '.structured_output'

Performance Notes

• Model commands typically respond in 1-5 seconds
• File extraction can take 30-120 seconds depending on file size
• AI search response time depends on datastore size
• URL processing depends on webpage size and complexity

Related Documentation

• Aitana CLI Main Documentation
• API Endpoints Testing Guide
• Backend API Documentation