atmos ai exec

Give the AI a natural-language prompt and it will run Atmos commands, shell commands, and tool calls to carry out the task -- then return structured results. Designed for scripting, automation, and CI/CD pipelines where you need the AI to act, not just answer.

Experimental

Configure AI

Learn how to configure AI providers, skills, tools, and sessions in your atmos.yaml.

Configuration Reference

atmos ai exec --help

Description

The atmos ai exec command takes a natural-language prompt, lets the AI run Atmos commands and shell commands to fulfill it, and returns structured output. Unlike atmos ai ask which produces human-readable answers, exec actually executes tools and commands, then returns machine-parseable results with exit codes, tool call details, and token usage.

Use it for:

• Automation: The AI runs atmos describe, atmos validate, shell commands, etc. on your behalf
• CI/CD Pipelines: Reliable exit codes and JSON output for deployment workflows
• Batch Processing: Process multiple infrastructure tasks programmatically

Usage

atmos ai exec [prompt] [flags]

The prompt can be provided as:

• Command argument: atmos ai exec "your prompt"
• Stdin pipe: echo "your prompt" | atmos ai exec

Arguments

prompt

The prompt to execute (optional if using stdin). Use quotes for multi-word prompts.

Flags

--format, -f

Output format: text, json, markdown (default: text)

--output, -o

Output file path (default: stdout)

--no-tools

Disable tool execution for faster, simpler queries

--context

Include stack context in the prompt

--provider, -p

Override AI provider (anthropic, openai, gemini, grok, ollama, bedrock, azureopenai)

--session, -s

Session ID for conversation context (enables multi-turn execution)

--include

Add glob patterns to include in context (can be repeated)

--exclude

Add glob patterns to exclude from context (can be repeated)

--no-auto-context

Disable automatic context discovery

Exit Codes

The command uses standard Unix exit codes for automation:

0

Success.

1

AI error (API failure, invalid response, configuration error).

2

Tool execution error.

Output Formats

Text Format (Default)

Plain text response, suitable for human reading and logging:

atmos ai exec "List all available stacks"

Output:

Based on your configuration, here are the available stacks:
1. dev-us-east-1
2. staging-us-east-1
3. prod-us-east-1
...

JSON Format

Structured output with complete metadata:

atmos ai exec "Describe the vpc component" --format json

Output:

{
  "success": true,
  "response": "The VPC component creates a Virtual Private Cloud...",
  "tool_calls": [
    {
      "tool": "atmos_describe_component",
      "args": {"component": "vpc", "stack": "dev-us-east-1"},
      "duration_ms": 245,
      "success": true,
      "result": {...}
    }
  ],
  "tokens": {
    "prompt": 1234,
    "completion": 567,
    "total": 1801,
    "cached": 890
  },
  "metadata": {
    "model": "claude-sonnet-4-6",
    "provider": "anthropic",
    "duration_ms": 2340,
    "timestamp": "2025-10-31T10:00:00Z",
    "tools_enabled": true,
    "stop_reason": "end_turn"
  }
}

Markdown Format

Formatted output with tool execution summaries:

atmos ai exec "Analyze prod stacks" --format markdown

Output:

The production stacks are configured with:
- High availability across 3 AZs
- Auto-scaling enabled
- Enhanced monitoring

---

## Tool Executions (3)

1. ✅ **atmos_list_stacks** (45ms)
2. ✅ **atmos_describe_component** (120ms)
3. ❌ **atmos_validate_component** (89ms)

Examples

Basic Execution

basic examples

# Simple question
atmos ai exec "What is Atmos?"

# With JSON output
atmos ai exec "List all stacks" --format json

# Save to file
atmos ai exec "Analyze VPC configuration" --output analysis.md --format markdown

# Disable tools for faster execution
atmos ai exec "Explain Atmos concepts" --no-tools

Stdin Piping

stdin examples

# Pipe prompt from stdin
echo "Validate stack configuration" | atmos ai exec --format json

# From file
cat prompt.txt | atmos ai exec --format json > result.json

# Multi-line prompt
atmos ai exec --format json <<EOF
Analyze the following stacks:
- dev-us-east-1
- staging-us-east-1
- prod-us-east-1
EOF

CI/CD Integration

ci/cd examples

# Validate configuration in pipeline
atmos ai exec "Check for security issues" --format json > security.json
if jq -e '.success == false' security.json; then
  echo "Security issues found"
  exit 1
fi

# Generate deployment report
atmos ai exec "Analyze prod environment" \
  --output deployment-report.md \
  --format markdown

# Pre-deployment validation
for stack in $(atmos list stacks); do
  echo "Validating $stack..."
  atmos ai exec "Validate stack $stack" --format json --no-tools
done

# GitHub Actions integration
- name: AI Review
  run: |
    result=$(atmos ai exec "Review changes" --format json)
    echo "$result" | jq -r '.response' >> $GITHUB_STEP_SUMMARY

Multi-Turn Automation

Use --session to maintain conversation context across multiple exec calls. The session name is an arbitrary string that groups related calls together -- the AI remembers all previous messages in the same session.

multi-turn examples

# First call - establish context
atmos ai exec "Plan deployment for staging" \
  --session staging-deploy \
  --format json > plan.json

# Second call - AI remembers the plan from the first call
atmos ai exec "What are the risks?" \
  --session staging-deploy \
  --format json > risks.json

# Third call - builds on all previous context in this session
atmos ai exec "Generate rollback procedure" \
  --session staging-deploy \
  --format json > rollback.json

Batch Processing

batch processing

#!/bin/bash

# Process multiple stacks
stacks=$(atmos list stacks)
for stack in $stacks; do
  echo "Analyzing $stack..."
  atmos ai exec "Analyze stack $stack for cost optimization" \
    --format json \
    --output "reports/${stack}-cost-analysis.json"
done

# Aggregate results
jq -s '.' reports/*.json > aggregated-report.json

Error Handling

error handling

#!/bin/bash

# Check exit code
if ! atmos ai exec "Validate configuration" --format json; then
  echo "Validation failed with exit code $?"
  exit 1
fi

# Parse JSON for errors
result=$(atmos ai exec "Check stacks" --format json)
if echo "$result" | jq -e '.success == false'; then
  error_type=$(echo "$result" | jq -r '.error.type')
  error_msg=$(echo "$result" | jq -r '.error.message')
  echo "Error ($error_type): $error_msg"
  exit 1
fi

# Tool execution error handling
result=$(atmos ai exec "Complex analysis" --format json)
tool_errors=$(echo "$result" | jq '[.tool_calls[] | select(.success == false)]')
if [ "$(echo "$tool_errors" | jq 'length')" -gt 0 ]; then
  echo "Tool execution errors detected:"
  echo "$tool_errors" | jq -r '.[] | "- \(.tool): \(.error)"'
fi

Provider Override

provider override

# Use specific provider for a task
atmos ai exec "Complex reasoning task" --provider anthropic --format json

# Fast provider for simple queries
atmos ai exec "List stacks" --provider openai --format json --no-tools

# Local provider for privacy
atmos ai exec "Analyze sensitive config" --provider ollama --format json

Advanced Usage

Output Parsing with jq

# Extract just the response
atmos ai exec "Question" --format json | jq -r '.response'

# Check for specific tool execution
atmos ai exec "Analyze" --format json | \
  jq '.tool_calls[] | select(.tool == "atmos_describe_component")'

# Get token usage
atmos ai exec "Question" --format json | jq '.tokens'

# Check execution time
atmos ai exec "Question" --format json | jq '.metadata.duration_ms'

Integration Patterns

Email Reports:

atmos ai exec "Weekly infrastructure summary" --format markdown | \
  mail -s "Weekly Report" team@example.com

Slack Notifications:

result=$(atmos ai exec "Check production health" --format json)
response=$(echo "$result" | jq -r '.response')
curl -X POST $SLACK_WEBHOOK -d "{\"text\":\"$response\"}"

Ticket Creation:

analysis=$(atmos ai exec "Identify issues in prod" --format json)
if echo "$analysis" | jq -e '.success == true'; then
  issues=$(echo "$analysis" | jq -r '.response')
  # Create ticket with issues
  gh issue create --title "Infrastructure Issues" --body "$issues"
fi

Comparison with Other Commands

atmos ai ask

Non-interactive. Human-readable text output. Best for quick terminal questions.

atmos ai chat

Interactive. Rich TUI with markdown. Best for extended conversations.

atmos ai exec

Non-interactive. JSON/Text/Markdown output. Best for automation, scripting, CI/CD.

Best Practices

1. Use --format json for automation - Provides structured, parseable output
2. Set --no-tools for simple queries - Faster execution when tools aren't needed
3. Use --session for multi-turn workflows - Maintains context across calls
4. Check exit codes in scripts - Handle errors appropriately
5. Disable tool confirmation in CI/CD - Set require_confirmation: false in config
6. Use --output for file persistence - Avoid shell redirection issues
7. Parse JSON with jq - Robust handling of structured output
8. Set appropriate timeouts - Adjust timeout_seconds based on your needs

Related Commands

📄️ atmos ai ask

Quick command-line questions

📄️ atmos ai chat

Interactive chat sessions

📄️ atmos ai sessions

Manage AI chat sessions

📄️ AI Skills

Install and use 21+ specialized AI skills