Skip to main content

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.

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. API: anthropic, openai, gemini, github, grok, openrouter, deepseek, zai, ollama, bedrock, azureopenai. CLI: claude-code, codex-cli, copilot-cli, opencode, gemini-cli.
--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
--mcp <servers>
MCP servers to use (comma-separated). Skips automatic server routing and starts only the specified servers. Can be repeated: --mcp aws-iam --mcp aws-billing. Use atmos mcp list to see available server names. Environment variable: ATMOS_AI_MCP
Smart MCP Routing

When multiple MCP servers are configured with API providers, Atmos automatically selects only the servers relevant to your prompt using a lightweight routing call. Use --mcp to bypass routing and specify servers directly. CLI providers (claude-code, codex-cli, copilot-cli, opencode, gemini-cli) skip routing — all servers are passed to the CLI tool, which handles selection internally.

Claude Code Tool Permissions​

Both ask and exec apply the Atmos permission system to Claude Code tool requests. With the default ai.tools.mode: require_confirmation, an unattended run fails if a tool needs approval and no terminal is available.

Migration for existing MCP configurations

Previously, configuring mcp.servers implicitly approved all Claude Code tools, including built-in tools such as Bash and Edit. That implicit approval has been removed for both commands. Existing CI jobs may need an explicit permission policy before upgrading.

For unattended execution, set allow to avoid prompts while retaining the blocked list for requests delegated to Atmos:

ai:
  default_provider: claude-code
  tools:
    mode: allow
    blocked: ["Edit", "Write"]

To pre-approve only specific tools in Claude Code, configure ai.providers.claude-code.allowed_tools, for example ["Read", "Bash(atmos list stacks)"]. Claude-native and provider-preapproved requests follow Claude’s permission policy and do not reach Atmos’s blocked-list check. The yolo mode bypasses all Atmos permission checks, including blocked tools. See Claude Code tool approval for cached decisions and interactive behavior.

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

MCP Server Integration​

mcp examples
# Auto-routing selects the right server
atmos ai exec "Check security posture in us-east-1" --format json

# Specify servers directly
atmos ai exec --mcp aws-iam "List all admin roles" --format json
atmos ai exec --mcp aws-security,aws-iam "Audit our security posture" --format markdown

# Environment variable
ATMOS_AI_MCP=aws-billing atmos ai exec "Monthly cost report" --format json > costs.json

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
Human-readable answers with interactive tool approval when needed. 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 ai.tools.mode: allow in config (use yolo only in isolated runners). The older require_confirmation: false and yolo_mode: true settings are deprecated aliases for these modes
  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​