Skip to content

CLI Reference

Complete reference for all AIA command-line arguments, options, and flags.

Usage Patterns

# Basic usage
aia [options] [PROMPT_ID] [CONTEXT_FILE]*

# Chat mode
aia --chat [PROMPT_ID] [CONTEXT_FILE]*
aia --chat [CONTEXT_FILE]*

# Show help
aia --help

# Show version
aia --version

Mode Options

--chat

Begin a chat session with the LLM after processing all prompts in the pipeline.

aia --chat
aia --chat system_prompt
aia --chat my_prompt context.txt

-f, --fuzzy

Use fuzzy matching for prompt search (requires fzf to be installed).

aia --fuzzy
aia -f

Note: If fzf is not installed, AIA will exit with an error.

--terse

Adds a special instruction to the prompt asking the AI to keep responses short and to the point.

aia --terse my_prompt
aia --terse --chat

--tokens

Display token usage information after each response in chat mode. Shows input tokens, output tokens, and model ID.

aia --chat --tokens
aia --chat --tokens --model gpt-4

--cost

Include cost calculations with token usage. Automatically enables --tokens. Shows estimated cost based on the model's pricing.

aia --chat --cost
aia --chat --cost --model gpt-4,claude-3-sonnet

Note: --cost implies --tokens, so you don't need to specify both.

--mcp FILE

Load an MCP (Model Context Protocol) server from a JSON configuration file. MCP servers provide additional tools and context to AI models. Multiple --mcp options can be used to load multiple servers.

# Load a single MCP server
aia --mcp ~/.config/aia/mcp/github.json my_prompt

# Load multiple MCP servers
aia --mcp github.json --mcp filesystem.json my_prompt

# Combine with chat mode
aia --chat --mcp ~/mcp-servers/memory.json

JSON file format: 

{
  "name": "github",
  "command": "github-mcp-server",
  "args": ["stdio"],
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token"
  },
  "timeout": 8000
}

--no-mcp

Disable all MCP server processing, including servers defined in the configuration file.

# Disable MCP server processing
aia --no-mcp my_prompt

Use cases: - Use --no-mcp when you want faster responses without MCP tool overhead - Use --no-mcp to temporarily bypass MCP servers configured in your config file

Adapter Options

--adapter ADAPTER

Interface that adapts AIA to the LLM. Currently supported: ruby_llm

aia --adapter ruby_llm

Valid adapters: ruby_llm

--available-models [QUERY]

List (then exit) available models that match the optional query. Query is a comma-separated list of AND components.

# List all models
aia --available-models

# Filter by provider
aia --available-models openai

# Filter by capability and provider
aia --available-models openai,mini

# Filter by modality
aia --available-models text_to_text

# Complex filter
aia --available-models openai,gpt,text_to_image

Model Options

-m MODEL, --model MODEL

Name of the LLM model(s) to use. For multiple models, use comma-separated values.

Supports inline role assignment using MODEL=ROLE syntax to assign specific roles to individual models.

# Single model
aia --model gpt-4 my_prompt

# Multiple models (parallel processing)
aia --model "gpt-4,claude-3-sonnet,gemini-pro" my_prompt

# Short form
aia -m gpt-3.5-turbo my_prompt

# Single model with role (inline syntax)
aia --model gpt-4o=architect design_review.md

# Multiple models with different roles
aia --model "gpt-4o=architect,claude=security,gemini=performance" my_prompt

# Same model with multiple roles for diverse perspectives
aia --model "gpt-4o=optimist,gpt-4o=pessimist,gpt-4o=realist" project_plan.md

# Mixed: some models with roles, some without
aia --model "gpt-4o=expert,claude,gemini" my_prompt

See also: --role for applying a role to all models, --list-roles for discovering available roles.

--[no-]consensus

Enable/disable consensus mode for multi-model responses. When enabled, AIA attempts to create a consensus response from multiple models.

# Enable consensus mode (requires multiple models)
aia --model "gpt-4,claude-3-sonnet" --consensus my_prompt

# Disable consensus mode (default: show individual responses)
aia --model "gpt-4,claude-3-sonnet" --no-consensus my_prompt

--sm, --speech-model MODEL

Speech model to use for text-to-speech functionality.

aia --speech-model tts-1 --speak my_prompt
aia --sm tts-1-hd --speak my_prompt

--tm, --transcription-model MODEL

Transcription model to use for speech-to-text functionality.

aia --transcription-model whisper-1 audio_file.wav
aia --tm whisper-1 my_audio.mp3

File Options

-c, --config-file FILE

Load configuration from a specific file.

aia --config-file /path/to/config.yml my_prompt
aia -c ~/.aia/custom_config.yml my_prompt

-o, --[no-]output [FILE]

Output file for saving AI responses.

# Save to default file (temp.md)
aia --output my_prompt

# Save to specific file
aia --output output.txt my_prompt

# Use absolute path
aia --output /tmp/ai_response.md my_prompt

# Disable file output
aia --no-output my_prompt

-a, --[no-]append

Append to output file instead of overwriting.

# Append mode
aia --output log.md --append my_prompt

# Overwrite mode (default)
aia --output log.md --no-append my_prompt

--[no-]history-file [FILE]

Conversation history file for logging prompts and responses.

# Enable history logging to default location
aia --history-file my_prompt

# Log to specific file
aia --history-file /var/log/aia_history.log my_prompt

# Disable history logging
aia --no-history-file my_prompt

--md, --[no-]markdown

Format output with Markdown.

# Enable Markdown formatting
aia --markdown my_prompt

# Disable Markdown formatting
aia --no-markdown my_prompt

Prompt Options

--prompts-dir DIR

Directory containing prompt files.

aia --prompts-dir /custom/prompts my_prompt
aia --prompts-dir ~/work/prompts my_prompt

--roles-prefix PREFIX

Subdirectory name for role files (default: roles).

# Use custom roles directory
aia --roles-prefix personas --role expert

# Results in looking for roles in ~/.prompts/personas/expert.txt

-r, --role ROLE_ID

Role ID to prepend to the prompt. This applies the same role to all models.

For per-model role assignment, use the inline MODEL=ROLE syntax with --model instead.

# Apply role to all models
aia --role expert my_prompt
aia -r teacher explain_concept

# With multiple models (same role for all)
aia --model "gpt-4,claude" --role architect design.md

# Per-model roles (inline syntax - see --model)
aia --model "gpt-4=architect,claude=security" design.md

See also: --model for inline role syntax, --list-roles for discovering available roles.

--list-roles

List all available roles and exit. Shows role IDs and their descriptions from the roles directory.

# List all available roles
aia --list-roles

# Example output:
# Available roles in /Users/you/.prompts/roles:
#   architect    - Software architecture expert
#   security     - Security analysis specialist
#   performance  - Performance optimization expert
#   debugger     - Expert debugging assistant
#   optimist     - Positive perspective analyzer
#   pessimist    - Critical risk analyzer
#   realist      - Balanced pragmatic analyzer

Roles are discovered from: - Default location: ~/.prompts/roles/ - Custom location: Set via --prompts-dir and --roles-prefix - Nested directories: Supports subdirectories like roles/software/architect.txt

Use case: Discover available roles before using them with --role or inline MODEL=ROLE syntax.

See also: --role, --model, --prompts-dir, --roles-prefix

-n, --next PROMPT_ID

Next prompt to process (can be used multiple times to build a pipeline).

aia my_prompt --next second_prompt --next third_prompt
aia -n analysis -n summary my_prompt

-p PROMPTS, --pipeline PROMPTS

Pipeline of comma-separated prompt IDs to process.

aia --pipeline "analysis,summary,report" my_data
aia -p "review,optimize,test" my_code.py

-x, --[no-]exec

Designate an executable prompt file.

# Treat prompt as executable
aia --exec my_script_prompt

# Treat as regular prompt (default)
aia --no-exec my_script_prompt

--system-prompt PROMPT_ID

System prompt ID to use for chat sessions.

aia --system-prompt helpful_assistant --chat
aia --system-prompt code_expert --chat my_code.py

--regex PATTERN

Regex pattern to extract parameters from prompt text.

aia --regex '\{\{(\w+)\}\}' my_template_prompt
aia --regex '<%=\s*(\w+)\s*%>' erb_prompt

AI Parameters

-t, --temperature TEMP

Temperature for text generation (0.0 to 2.0). Higher values make output more creative and random.

# Conservative/focused
aia --temperature 0.1 analysis_prompt

# Balanced (default ~0.7)
aia --temperature 0.7 my_prompt

# Creative
aia --temperature 1.5 creative_writing

# Very creative
aia -t 2.0 brainstorm_ideas

--max-tokens TOKENS

Maximum tokens for text generation.

aia --max-tokens 100 short_summary
aia --max-tokens 4000 detailed_analysis

--top-p VALUE

Top-p sampling value (0.0 to 1.0). Alternative to temperature for controlling randomness.

aia --top-p 0.1 precise_answer
aia --top-p 0.9 creative_response

--frequency-penalty VALUE

Frequency penalty (-2.0 to 2.0). Positive values discourage repetition.

# Discourage repetition
aia --frequency-penalty 0.5 my_prompt

# Encourage repetition
aia --frequency-penalty -0.5 my_prompt

--presence-penalty VALUE

Presence penalty (-2.0 to 2.0). Positive values encourage discussing new topics.

# Encourage new topics
aia --presence-penalty 0.5 broad_discussion

# Focus on current topics
aia --presence-penalty -0.5 deep_dive

Audio/Image Options

--speak

Convert text to audio and play it. Uses the configured speech model and voice.

aia --speak my_prompt
aia --speak --voice nova my_prompt

--voice VOICE

Voice to use for speech synthesis.

aia --voice alloy --speak my_prompt
aia --voice echo --speak my_prompt
aia --voice fable --speak my_prompt
aia --voice nova --speak my_prompt  
aia --voice onyx --speak my_prompt
aia --voice shimmer --speak my_prompt

--is, --image-size SIZE

Image size for image generation.

aia --image-size 1024x1024 image_prompt
aia --is 1792x1024 wide_image
aia --is 1024x1792 tall_image

Common sizes: 256x256, 512x512, 1024x1024, 1792x1024, 1024x1792

--iq, --image-quality QUALITY

Image quality for image generation.

aia --image-quality standard image_prompt
aia --iq hd high_quality_image

Values: standard, hd

--style, --image-style STYLE

Style for image generation.

aia --image-style vivid colorful_image
aia --style natural realistic_image

Values: vivid, natural

Tool Options

--rq LIBS, --require LIBS

Ruby libraries to require for Ruby directive execution.

aia --require json,csv data_processing_prompt
aia --rq "net/http,uri" web_request_prompt

--tools PATH_LIST

Add tool file(s) or directories. Comma-separated paths.

# Single tool file
aia --tools ./my_tool.rb my_prompt

# Multiple tools
aia --tools "./tool1.rb,./tool2.rb" my_prompt

# Tool directory
aia --tools ./tools/ my_prompt

# Mixed paths
aia --tools "./tools/,./special_tool.rb" my_prompt

--at, --allowed-tools TOOLS_LIST

Allow only these tools to be used. Security feature to restrict tool access.

# Allow specific tools
aia --allowed-tools "calculator,file_reader" my_prompt
aia --at "web_scraper,data_analyzer" analysis_prompt

--rt, --rejected-tools TOOLS_LIST

Reject/block these tools from being used.

# Block dangerous tools
aia --rejected-tools "file_writer,system_command" my_prompt
aia --rt "network_access" secure_prompt

Utility Options

Log Level Options

AIA provides multiple log level options to control logging verbosity. These options set the log level for all three loggers: - aia: Used within the AIA codebase for application-level logging - llm: Passed to the RubyLLM gem's configuration (RubyLLM.logger) - mcp: Passed to the RubyLLM::MCP process (RubyLLM::MCP.logger)

Only one log level option should be used at a time.

-d, --debug

Enable debug output (most verbose) and set all loggers to DEBUG level. Also sets $DEBUG_ME = true for the debug_me gem.

aia --debug my_prompt
aia -d --chat

--no-debug

Explicitly disable debug output. Sets $DEBUG_ME = false.

aia --no-debug my_prompt

--info

Set all loggers to INFO level. Shows informational messages and above.

aia --info my_prompt
aia --info --chat

--warn

Set all loggers to WARN level (this is the default). Shows warnings, errors, and fatal messages.

aia --warn my_prompt

--error

Set all loggers to ERROR level. Shows only errors and fatal messages.

aia --error my_prompt
aia --error --chat

--fatal

Set all loggers to FATAL level (least verbose). Shows only critical/fatal messages.

aia --fatal my_prompt

Log Level Hierarchy (from most to least verbose): 1. debug - All messages including detailed debugging information 2. info - Informational messages and above 3. warn - Warnings, errors, and fatal messages (default) 4. error - Only errors and fatal messages 5. fatal - Only critical/fatal messages

-v, --[no-]verbose

Enable/disable verbose output.

# Verbose mode
aia --verbose my_prompt
aia -v my_prompt

# Quiet mode
aia --no-verbose my_prompt

--refresh DAYS

Refresh models database interval in days.

# Refresh immediately
aia --refresh 0

# Refresh weekly
aia --refresh 7

# Refresh monthly
aia --refresh 30

--dump FILE

Dump current configuration to a file for inspection or backup.

aia --dump current_config.yaml
aia --dump /tmp/aia_config_backup.yml

--completion SHELL

Show completion script for shell integration.

# Bash completion
aia --completion bash > ~/.bash_completion.d/aia

# Zsh completion  
aia --completion zsh > ~/.zsh/completions/_aia

# Fish completion
aia --completion fish > ~/.config/fish/completions/aia.fish

Supported shells: bash, zsh, fish

--version

Show AIA version and exit.

aia --version

-h, --help

Show help message and exit.

aia --help
aia -h

Usage Examples

Basic Examples

# Simple prompt execution
aia hello_world

# Chat mode
aia --chat

# Use specific model
aia --model gpt-4 code_review my_script.py

# Fuzzy prompt selection
aia --fuzzy

Advanced Examples

# Multi-model consensus
aia --model "gpt-4,claude-3-sonnet" --consensus analysis_prompt data.csv

# Creative writing with voice output
aia --model gpt-4 --temperature 1.2 --speak --voice nova story_prompt

# Secure tool usage
aia --tools ./safe_tools/ --allowed-tools "calculator,file_reader" --rejected-tools "system_command" analysis_prompt

# Pipeline with custom configuration
aia --pipeline "extract,analyze,summarize" --temperature 0.3 --max-tokens 2000 --output report.md data_source.txt

# Debug mode with verbose output
aia --debug --verbose --model claude-3-sonnet problematic_prompt

Configuration Examples

# Use custom configuration
aia --config-file ./project_config.yml --prompts-dir ./project_prompts/ my_prompt

# Save output with markdown formatting
aia --output analysis.md --markdown --append data_analysis dataset.csv

# Audio processing
aia --transcription-model whisper-1 --speech-model tts-1-hd --voice echo audio_prompt audio_file.wav

Exit Codes

  • 0 - Success
  • 1 - General error (invalid arguments, file not found, etc.)
  • 2 - Configuration error
  • 3 - Model/API error
  • 4 - Tool execution error

Environment Variables

Many CLI options have corresponding environment variables with the AIA_ prefix. Use double underscore (__) for nested configuration sections:

# Model configuration (top-level, supports MODEL=ROLE syntax)
export AIA_MODEL="gpt-4"
export AIA_MODEL="gpt-4o=architect"
export AIA_MODEL="gpt-4o=architect,claude=security,gemini=performance"

# LLM settings (nested under llm:)
export AIA_LLM__ADAPTER="ruby_llm"
export AIA_LLM__TEMPERATURE="0.8"
export AIA_LLM__MAX_TOKENS="2048"

# Prompts settings (nested under prompts:)
export AIA_PROMPTS__DIR="/custom/prompts"
export AIA_PROMPTS__ROLES_PREFIX="roles"

# Output settings (nested under output:)
export AIA_OUTPUT__FILE="./output.md"
export AIA_OUTPUT__APPEND="true"
export AIA_OUTPUT__HISTORY_FILE="~/.prompts/_prompts.log"

# Audio settings (nested under audio:)
export AIA_AUDIO__VOICE="alloy"
export AIA_AUDIO__SPEECH_MODEL="tts-1"

# Image settings (nested under image:)
export AIA_IMAGE__SIZE="1024x1024"
export AIA_IMAGE__QUALITY="hd"

# Flags (nested under flags:)
export AIA_FLAGS__CHAT="true"
export AIA_FLAGS__VERBOSE="true"
export AIA_FLAGS__DEBUG="false"
export AIA_FLAGS__TOKENS="true"
export AIA_FLAGS__COST="true"
export AIA_FLAGS__NO_MCP="false"
export AIA_FLAGS__CONSENSUS="true"

# Registry settings (nested under registry:)
export AIA_REGISTRY__REFRESH="7"

# Paths settings (nested under paths:)
export AIA_PATHS__AIA_DIR="~/.config/aia"
export AIA_PATHS__CONFIG_FILE="~/.config/aia/aia.yml"

Note: The AIA_MODEL environment variable supports the same inline MODEL=ROLE syntax as the --model CLI option.

See Configuration for a complete list.

Configuration Precedence

Options are resolved in this order (highest to lowest precedence):

  1. Command line arguments (including inline MODEL=ROLE syntax)
  2. Environment variables (including inline syntax in AIA_MODEL)
  3. Configuration files (including array format with roles)
  4. Built-in defaults

Role-specific precedence: When using the role feature, inline MODEL=ROLE syntax takes precedence over the --role flag, which takes precedence over roles in config files.