AIA allows you to create prompts that are themselves executable files, enabling powerful CLI-based workflows and pipelines.

See The "run" Prompt ID for more details.

1. Add a shebang line to your prompt file:

   #!/usr/bin/env aia run --no-out_file

2. Make the file executable:

   chmod +x my_prompt

3. Run it like any script:

   ./my_prompt

For executable prompt files that contain dynamic content (environment variables, shell commands, ERB templates, or directives), use the --exec option in the shebang line:

#!/usr/bin/env aia run --exec --no-out_file

• With --exec: Dynamic content is processed (envars, shell integration, ERB, directives)
• Without --exec: File is treated as static context content

#!/usr/bin/env aia run --exec --no-out_file
# File: user_report
# Generate report for current user

Generate a system report for user: [USER]
Current directory: [PWD]

#!/usr/bin/env aia run --exec --no-out_file
# File: log_analyzer
# Analyze recent system logs

//shell find /var/log -name "*.log" -mtime -1
Analyze the log files listed above for error patterns.

#!/usr/bin/env aia run --exec --no-out_file
# File: config_report
# Show current system configuration

//shell hostname
//shell uname -a
//shell df -h
Create a summary report of the system information above.

#!/usr/bin/env aia run --no-out_file
# File: top10
# Desc: The top 10 cities by population

what are the top 10 cities by population in the USA. Summarize what people like about living in each city. Include an average cost of living. Include links to the Wikipedia pages. Format your response as a markdown document.

You can pipe the output to other CLI tools, e.g.:

./top10 | glow

• Use --next for chaining two prompts:

  aia one --next two

• Use --pipeline for chaining multiple prompts:

  aia one --pipeline two,three,four

Problem: When using an executable prompt file that references a base prompt containing a __END__ marker, the executable file's content may not appear in the LLM input.

Why This Happens: In memory, the executable prompt content is appended after the base prompt content. If the base prompt has a __END__ marker, everything after it (including your executable prompt content) is treated as comments and filtered out.

Example of the Problem:

Base prompt file (~/.prompts/system.txt):

You are a helpful system assistant.

__END__
Documentation comments here

Your executable prompt (my_script):

#!/usr/bin/env aia run system --exec --no-out_file
Check disk usage and report any issues.

Result: Only the "You are a helpful system assistant." text gets processed.

Solutions:

1. Replace __END__ with HTML comments in your base prompt:

   You are a helpful system assistant.
   
   <!--
   Documentation comments here
   -->
   

2. Remove __END__ entirely from base prompts used with executable files.

3. Move comments to the top of the base prompt file.

Dynamic Content Not Processing:

• Ensure you're using --exec in your shebang line
• Test with simple environment variables first: echo "User: [USER]"

File Permission Errors:

chmod +x my_prompt  # Make file executable
ls -la my_prompt    # Verify permissions

Shebang Line Problems:

# Verify AIA location
which aia

# Test shebang syntax
head -1 my_prompt

• Keep your executable prompts in a directory in your $PATH or reference them directly by path.
• Use the --no-out_file option for STDOUT output to enable piping workflows.
• Use the --exec option when your prompt contains dynamic content (envars, shell commands, ERB, directives).
• Avoid __END__ markers in base prompts that will be used with executable prompt files.
• Use HTML comments (<!-- -->) instead of __END__ for documentation.
• Test executable prompts both standalone and in pipeline workflows.
• Debug with --debug --verbose flags when troubleshooting.

For more on prompt management, see prompt_management.md. For advanced chaining, see prompt_directives.md. For detailed troubleshooting, see troubleshooting.md.