Skip to main content

AI Tools

The ai.tools section controls which Atmos commands the AI assistant can execute and whether user confirmation is required.

Experimental
Renamed in a recent release

tools.allowed_tools, tools.restricted_tools, and tools.blocked_tools were renamed to tools.allowed, tools.restricted, and tools.blocked — the tools: block already establishes what these are lists of. The old names are no longer read; update atmos.yaml to the new names. tools.allowed also picked up a second responsibility: see Tool Settings below.

How Tool Calling Works​

When you ask a question that requires infrastructure data, the AI decides which tool to call, requests permission (if configured), executes the tool locally, and uses the result to answer your question.

What Gets Sent to the AI Provider​

Only metadata is sent initially — tool definitions (names, parameters, descriptions) and your question. No actual infrastructure data leaves your machine until the AI specifically requests it by calling a tool.

When the AI calls a tool, it runs locally and only the tool's output is sent back. You control this through the permission system.

Configuration​

atmos.yaml
ai:
  tools:
    enabled: true
    require_confirmation: true
    allowed:
      - atmos_describe_component
      - atmos_list_stacks
      - atmos_validate_stacks
      - atmos_describe_*            # Wildcard patterns supported
    restricted:
      - write_component_file
      - write_stack_file
      - edit_file
    blocked:
      - execute_bash_command
    yolo_mode: false                # Skip all confirmations (DANGEROUS!)

Tool Settings​

tools.enabled
Enable or disable the tool subsystem for atmos ai chat/ask/exec (default: false). When disabled, the AI can only answer from its training data and conversation context. This does not affect atmos mcp start — see MCP note below.
tools.require_confirmation
Prompt the user before executing any tool (default: true). Set to false to allow all tools except restricted to execute automatically.
tools.allowed
When non-empty, restricts which tools exist at all — only tools matching one of these name patterns are registered; every other tool simply isn't available this session. Listed tools also skip the confirmation prompt. Supports wildcard patterns like atmos_describe_*. Empty/unset (default: []) means every tool is registered, subject to normal confirmation rules.
tools.restricted
List of tools (from whatever allowed already let through) that always require user confirmation, even when require_confirmation: false (default: []). Use this to protect write and execute operations.
tools.blocked
List of tools completely blocked from execution (default: []). The AI cannot invoke these tools under any circumstances.
tools.yolo_mode
Skip all permission checks and execute tools immediately (default: false). Only use in trusted, isolated CI/CD environments. Never use in production or shared environments.

MCP Server Note​

atmos mcp start always registers tools (subject to tools.allowed/restricted/blocked) regardless of tools.enabled — mcp.enabled: true is that command's own, sufficient opt-in. tools.enabled only gates atmos ai chat/ask/exec's own tool-use loop. See MCP Configuration.

Available Tools​

Atmos Commands​

atmos_describe_component
Describe a component's configuration in a stack. Read-only.
atmos_list_stacks
List all available stacks. Read-only.
atmos_validate_stacks
Validate stack configurations against schemas and policies. Read-only.
atmos_validate_schema
Validate atmos.yaml (plus atmos.d and profile fragments) and other configured YAML files against their JSON Schemas. Read-only.
describe_affected
Show components affected by git changes. Read-only.
get_template_context
Debug Go template variable context. Read-only.
execute_atmos_command
Execute any Atmos CLI command. Permissions vary by command.
atmos_list_findings
List security findings from AWS Security Hub for Atmos stacks. Read-only.
atmos_describe_finding
Get detailed information about a specific security finding by ID. Read-only.
atmos_analyze_finding
Analyze a security finding using AI to determine root cause and remediation steps. Read-only.
atmos_compliance_report
Generate a compliance posture report for a framework (CIS AWS, PCI DSS, SOC2, HIPAA, NIST). Read-only.
atmos_config_get
Read a value from the active atmos.yaml using a dot-notation path. Read-only.
atmos_config_list
List the dot-notation setting paths defined in the active atmos.yaml. Read-only.
atmos_config_set
Set a value in the active atmos.yaml using a dot-notation path, preserving comments and anchors. Requires confirmation by default.
atmos_config_delete
Delete a value from the active atmos.yaml using a dot-notation path. Requires confirmation by default.
atmos_config_format
Format the active atmos.yaml file in place, preserving comments and anchors. Requires confirmation by default.
atmos_stack_config_get
Read the effective value of a component-relative dot-path for a component in a stack. Read-only.
atmos_stack_config_list
List editable component-relative config paths for a component in a stack. Read-only.
atmos_stack_config_set
Set a component-relative value for a component in a stack, using provenance to find the defining manifest. Requires confirmation by default.
atmos_stack_config_delete
Delete a component-relative value from the manifest that defines it for a component in a stack. Requires confirmation by default.
atmos_stack_config_format
Format the manifest files that define a stack component in place. Requires confirmation by default.
atmos_vendor_config_get
Read a raw value from a vendor manifest (vendor.yaml) by dot-notation path. Read-only.
atmos_vendor_config_list
List raw setting paths from a vendor manifest and its imports. Read-only.
atmos_vendor_config_set
Set a raw value in a vendor manifest by dot-notation path. Requires confirmation by default.
atmos_vendor_config_delete
Delete a raw value from a vendor manifest by dot-notation path. Requires confirmation by default.
atmos_vendor_config_format
Format a vendor manifest file in place, preserving comments and anchors. Requires confirmation by default.
atmos_vendor_check_updates
Check whether vendored Git-sourced components have a newer version available than the one currently pinned. Read-only.
atmos_vendor_diff
Show a unified diff between a vendored component's pinned version and another ref. Read-only.
atmos_vendor_update
Update vendored Git-sourced components' pinned version to the latest available tag. Requires confirmation by default.
atmos_list_commands
List Atmos CLI commands and subcommands. Read-only.
atmos_command_help
Get detailed help for a specific Atmos CLI command. Read-only.
atmos_describe_dependents
List the Atmos components that depend on a given component/stack pair. Read-only.
atmos_describe_workflows
List all Atmos workflows discovered under the configured workflows base path. Read-only.
atmos_list_workflows
List all Atmos workflows with their defining file, description, and step count. Read-only.
atmos_list_components
List unique Atmos components defined across all stacks. Read-only.
atmos_list_values
List a component's values across every stack where it's used. Read-only.
atmos_auth_whoami
Show the currently active Atmos authentication identity and credential status. Read-only.
atmos_auth_list
List configured Atmos authentication providers and identities. Read-only.
atmos_toolchain_list
List tools declared in the project's .tool-versions file. Read-only.
atmos_toolchain_add
Add a tool dependency to the project's .tool-versions file. Requires confirmation by default.
atmos_toolchain_remove
Remove a tool dependency from the project's .tool-versions file. Requires confirmation by default.
atmos_toolchain_set
Set a tool's default pinned version in the project's .tool-versions file. Requires confirmation by default.
atmos_version_track_status
Check every dependency in an Atmos version track against its datasource for available updates. Read-only.
atmos_version_track_add
Add a dependency entry to an Atmos version track. Requires confirmation by default.
atmos_version_track_set
Update fields of an existing Atmos version track dependency entry. Requires confirmation by default.
atmos_version_track_remove
Remove a dependency entry from an Atmos version track. Requires confirmation by default.
atmos_version_track_update
Advance an Atmos version track's locked versions within each entry's update policy. Requires confirmation by default.
atmos_secret_list
List declared secrets and their initialization status. Read-only.
atmos_validate_component
Validate an Atmos component's configuration in a stack using JSON Schema or OPA policies. Read-only.

File Operations​

read_file
Read any file from the repository. Read-only.
read_component_file
Read a file from the components directory. Read-only.
read_stack_file
Read a file from the stacks directory. Read-only.
list_component_files
List files in a component directory. Read-only.
search_files
Search for patterns across files. Read-only.
edit_file
Edit an existing file with targeted changes. Requires confirmation by default.
write_component_file
Write or modify a component file. Requires confirmation by default.
atmos_terraform_component_hcl_get
Read an attribute value or block from a Terraform component file using an hcledit-style HCL address. Read-only.
atmos_terraform_component_hcl_edit
Structurally edit a Terraform component file using hcledit, preserving comments and formatting. Requires confirmation by default.
write_stack_file
Write or modify a stack file. Requires confirmation by default.

Execution​

execute_bash_command
Execute shell commands. Requires confirmation by default.

Validation and Web​

validate_file_lsp
Validate files using LSP diagnostics (requires LSP). Read-only.
atmos_validate_file
Validate a YAML file against a JSON Schema with line numbers, no LSP required. Read-only.
web_search
Search the web via DuckDuckGo or Google. Requires confirmation by default.

All file operations include path traversal protection -- files can only be accessed within configured directories.

Web Search Configuration​

atmos.yaml
ai:
  web_search:
    enabled: true
    max_results: 10
    # Google Custom Search (optional)
    # google_api_key: !env "GOOGLE_API_KEY"
    # google_cse_id: !env "GOOGLE_CSE_ID"

See Web Search in the AI configuration reference for all settings.

Permission Modes​

Prompt (default)
Set require_confirmation: true. Ask before each tool execution. The most secure mode.
Allow
Set require_confirmation: false. Auto-execute all tools except those in restricted.
YOLO
Set yolo_mode: true. Skip all permission checks. Only use in isolated CI/CD environments.

Permission Flow​

A tool must first be registered to be callable at all: if tools.allowed is non-empty, only matching tools are registered in the first place. Everything below only applies to a tool that made it that far:

1. YOLO Mode?     → Yes → Execute immediately
2. Blocked?       → Yes → Deny
3. Allowed list?  → Yes → Execute without prompt
4. Restricted?    → Yes → Always prompt
5. Default        → Prompt if require_confirmation is true

Permission Prompts​

When a tool requires confirmation:

Tool Execution Request
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Tool: atmos_describe_component
Description: Describe an Atmos component configuration in a specific stack

Parameters:
  component: vpc
  stack: prod-use1

Options:
  [a] Always allow (save to .atmos/ai.settings.local.json)
  [y] Allow once
  [n] Deny once
  [d] Always deny (save to .atmos/ai.settings.local.json)

Choice (a/y/n/d):

Wildcard Patterns​

Tool lists support glob-style wildcard patterns:

allowed:
  - atmos_describe_*      # Match all describe commands
  - atmos_list_*          # Match all list commands
  - *_validate            # Match anything ending in _validate

Persistent Permission Cache​

"Always allow" and "always deny" choices from interactive prompts are saved to .atmos/ai.settings.local.json. This file is user-specific and gitignored by default.

Priority order: tools.allowed (registration filter) > Blocked tools (config) > Cached denials > Allowed tools (config) > Cached allowances > Restricted tools > Default behavior.

Skill-Specific Tool Access​

Each AI skill defines which tools it can use, creating a safety layer where specialized skills only perform actions relevant to their purpose.

General
Can read all, write all, execute all. Full access (respects global config).
atmos-stacks
Can read stacks, components, files. No write or execute. Analysis only.
atmos-components
Can read components, files. Can write and execute (with confirmation). Code-focused.
atmos-terraform
Can read stacks, components, files. No write. Can execute (with confirmation). Plan/review only.
atmos-validation
Can read stacks, files, LSP. No write or execute. Validation only.

Workflow tip: Use different skills for different phases — analyze with atmos-stacks, refactor with atmos-components, validate with atmos-validation. Switch skills with Ctrl+A in the chat TUI.

Security Best Practices​

Start conservative. The default (prompt for everything) is the most secure. Relax permissions over time as you build trust:

atmos.yaml
# Production: very restrictive
ai:
  tools:
    enabled: true
    allowed: []                    # All tools registered; prompt for everything
    blocked:
      - execute_*                  # Block all execution tools
      - write_*                    # Block all write operations

# Development: more permissive
ai:
  tools:
    enabled: true
    allowed:
      - atmos_*                    # ONLY atmos_* tools are registered, and auto-approved
    blocked:
      - atmos_validate_stacks      # Still registered (it matches atmos_*) but every call is denied

Note: allowed only controls registration (whether a tool exists this session at all). blocked/restricted are checked at execution time, against whatever allowed already let through — a blocked tool can still appear in tools/list (MCP) or the AI's tool set, but every call to it is denied. A tool listed in both allowed and restricted is auto-approved, not prompted — allowed is checked first, before restricted.

YOLO Mode

Never use yolo_mode in production, shared environments, or workstations with production access. Reserve it for isolated CI/CD runners and sandboxed testing.

Troubleshooting​

Tools not executing: Check tools.enabled: true in your config, verify the tool isn't in blocked, and — if you've set tools.allowed — verify the tool is actually in that list (otherwise it was never registered in the first place).

No permission prompts: The tool may be in allowed or you may have previously chosen "always allow" in .atmos/ai.settings.local.json. Delete the cache file to reset.

Timeouts: Tools have a 30-second timeout. Long-running operations are automatically cancelled. Run them manually if needed.