Skip to content

Directives Reference

Directives are special commands embedded in prompts that provide dynamic functionality. All directives begin with // and are processed before the prompt is sent to the AI model.

Directive Syntax

//directive_name arguments

Examples: 

//config model gpt-4
//include my_file.txt
//shell ls -la

<%= "Hello World" %>

Configuration Directives

//config

Configure AIA settings from within prompts.

Syntax: //config [option] [value]

Examples: 

//config model gpt-4
//config temperature 0.8
//config max_tokens 2000
//config verbose true

Usage: - //config - Display all configuration - //config option - Display specific configuration option - //config option value - Set configuration option

Aliases: //cfg

//model

Display or configure the AI model.

Syntax: //model [model_name]

Examples: 

//model gpt-4
//model claude-3-sonnet
//model

Usage: - //model - Display current model configuration and details - //model name - Set the model to use

For multi-model configurations, displays: - Model count and primary model - Consensus mode status - Detailed information for each model including provider, context window, costs, and capabilities

//temperature

Set the creativity/randomness of AI responses.

Syntax: //temperature value

Examples: 

//temperature 0.1    # Very focused
//temperature 0.7    # Balanced (default)
//temperature 1.2    # Creative
//temperature 2.0    # Very creative

Aliases: //temp

//top_p

Set nucleus sampling parameter (alternative to temperature).

Syntax: //top_p value

Examples: 

//top_p 0.1     # Very focused
//top_p 0.9     # More diverse

Aliases: //topp

File and Web Directives

//include

Include content from files or websites.

Syntax: //include path_or_url

Examples: 

//include README.md
//include /path/to/config.yml
//include ~/Documents/notes.txt
//include https://example.com/page

Features: - Supports tilde (~) and environment variable expansion - Prevents circular inclusions - Can include web pages (requires PUREMD_API_KEY) - Handles both absolute and relative file paths

Aliases: //import

//webpage

Include content from web pages (requires PUREMD_API_KEY).

Syntax: //webpage url

Examples: 

//webpage https://docs.example.com/api
//webpage https://github.com/user/repo/blob/main/README.md

Prerequisites: Set the PUREMD_API_KEY environment variable: 

export PUREMD_API_KEY="your_api_key"

Aliases: //website, //web

Execution Directives

//shell

Execute shell commands and include their output.

Syntax: //shell command arguments

Examples: 

//shell ls -la
//shell git status
//shell grep -n "TODO" *.rb
//shell ps aux | grep ruby
//shell curl -s https://api.github.com/user | jq '.name'

Security Note: Use with caution in shared environments. Commands execute with your current user permissions.

Aliases: //sh

//ruby

Execute one line of Ruby code and include the result.

Syntax: //ruby (followed by Ruby code)

Examples: 

//ruby Time.now

//ruby Dir.pwd

//ruby File.read('config.yml')

//ruby [1,2,3,4,5].sum

//ruby "Hello, #{ENV['USER']}!"

//ruby require 'json'; JSON.pretty_generate({hello: 'world'})

Features: - Full Ruby environment available - Can use require for additional libraries (use --require CLI option) - Access to all Ruby standard library - Error handling with descriptive messages

Aliases: //rb

//say

Speak text using system text-to-speech (macOS/Linux).

Syntax: //say text to speak

Examples: 

//say Build completed successfully
//say Warning: Check the logs

Platform Support: - macOS: Uses built-in say command - Linux: Requires espeak or similar TTS software

Utility Directives

//tools

Display available RubyLLM tools.

Syntax: //tools

Example Output: 

Available Tools
===============

FileReader
----------
    Read and analyze file contents with support for multiple formats
    including text, JSON, YAML, and CSV files.

WebScraper
----------
    Extract and parse content from web pages with customizable
    selectors and filters.

//next

Set the next prompt to execute in a workflow.

Syntax: //next prompt_id

Examples: 

//next analyze_results
//next generate_report

Usage: - //next - Display current next prompt - //next prompt_id - Set next prompt in workflow

//pipeline

Define or modify a prompt workflow sequence.

Syntax: //pipeline prompt1,prompt2,prompt3

Examples: 

//pipeline extract_data,analyze,report
//pipeline code_review,optimize,test

Usage: - //pipeline - Display current pipeline - //pipeline prompts - Set pipeline sequence - Can use comma-separated or space-separated prompt IDs

Aliases: //workflow

//terse

Add instruction for brief responses.

Syntax: //terse

Example: 

//terse
Explain machine learning algorithms.

Adds: "Keep your response short and to the point." to the prompt.

//robot

Generate ASCII art robot.

Syntax: //robot

Inserts a fun ASCII robot character for visual breaks in prompts.

Context Management Directives

//clear

Clear conversation context in chat mode.

Syntax: //clear

Usage: Only available during chat sessions. Clears the conversation history while keeping the session active.

//review

Display current conversation context.

Syntax: //review

Aliases: //context

Shows the current context manager state, including conversation history and metadata.

Model and Information Directives

//available_models

List available AI models with filtering.

Syntax: //available_models [filter1,filter2,...]

Examples: 

//available_models
//available_models openai
//available_models gpt,4
//available_models text_to_image
//available_models claude,sonnet

Filter Options: - Provider names: openai, anthropic, google, etc. - Model names: gpt, claude, gemini, etc. - Capabilities: vision, function_calling, image_generation - Modalities: text_to_text, text_to_image, image_to_text

Output includes: - Model name and provider - Input cost per million tokens - Context window size - Input/output modalities - Capabilities

Aliases: //am, //available, //models, //all_models, //llms

//compare

Compare responses from multiple models.

Syntax: //compare prompt --models model1,model2,model3

Examples: 

//compare "Explain quantum computing" --models gpt-4,claude-3-sonnet,gemini-pro
//compare "Write a Python function to sort a list" --models gpt-3.5-turbo,gpt-4,claude-3-haiku

Features: - Side-by-side model comparison - Error handling for unavailable models - Formatted output with clear model labels

Aliases: //cmp

//help

Display available directives and their descriptions.

Syntax: //help

Output: Complete list of all directives with descriptions and aliases.

Directive Processing Order

Directives are processed in the order they appear in the prompt:

  1. Configuration directives (like //config, //model) are processed first
  2. File inclusion directives (//include, //webpage) are processed next
  3. Execution directives (//shell, //ruby) are processed
  4. Utility directives are processed last

Advanced Usage Patterns

Combining Directives

//config model gpt-4
//config temperature 0.3
//include project_context.md

Based on the project information above:
//shell git log --oneline -5

Analyze these recent commits and suggest improvements.

Dynamic Configuration

<% model_name = ENV['PREFERRED_MODEL'] || 'gpt-3.5-turbo' %>
//config model <%= model_name %>
//config temperature <%= ENV['AI_TEMPERATURE'] || '0.7' %>

Process this data with optimized settings.

Conditional Execution

<% if File.exist?('production.yml') %>
//include production.yml
<% else %>
//include development.yml
<% end %>

Configure the system based on environment.

Workflow Automation

//pipeline data_extraction,data_cleaning,analysis,reporting
//config model claude-3-sonnet
//config temperature 0.2

Begin automated data processing workflow.

Error Handling

Common Errors

File Not Found: 

Error: File 'missing.txt' is not accessible

Ruby Execution Error: 

This ruby code failed: invalid_syntax
SyntaxError: unexpected token

Web Access Error: 

ERROR: PUREMD_API_KEY is required in order to include a webpage

Missing Context Manager: 

Error: Context manager not available for //clear directive.

Custom Directives

You can extend AIA with custom directives by creating Ruby files that define new directive methods:

# examples/directives/ask.rb
module AIA
  class DirectiveProcessor
    private
    desc "A meta-prompt to LLM making its response available as part of the primary prompt"
    def ask(args, context_manager=nil)
      meta_prompt = args.empty? ? "What is meta-prompting?" : args.join(' ')
      AIA.config.client.chat(meta_prompt)
    end
  end
end

Usage: Load custom directives with the --tools option:

# Load custom directive
aia --tools examples/directives/ask.rb --chat

# Use the custom directive in prompts
//ask gather the latest closing data for the DOW, NASDAQ, and S&P 500

Best Practices

  1. Test directives individually before combining them
  2. Use absolute paths for file includes when possible
  3. Handle errors gracefully with conditional Ruby code
  4. Validate environment variables before using them
  5. Use appropriate models for different task types

Security Considerations

  • Shell directives execute with your user permissions
  • Ruby directives have full access to the Ruby environment
  • File inclusion can access any readable file
  • Web access requires API keys and network access

Safe Usage Tips

  1. Avoid shell commands that modify system state in shared prompts
  2. Use environment variables for sensitive data, not hardcoded values
  3. Validate inputs in Ruby code before execution
  4. Limit file access to necessary directories only
  5. Review prompts from untrusted sources before execution

Environment Variables for Directives

  • PUREMD_API_KEY - Required for web page inclusion
  • PREFERRED_MODEL - Default model selection
  • AI_TEMPERATURE - Default temperature setting
  • AI_MAX_TOKENS - Default token limit