OpenParable
Skip to content
← Back to skills

Atmos Diagnostics

Testing & Quality
atmos-diagnostics

Atmos Diagnostics is an Agent Skill for testing & quality published in the cloudposse/atmos repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Atmos diagnostics: machine-readable JSONL event streams, diagnostics.enabled/file/include_output, subprocess start/end/output events, masking, and debugging Atmos execution

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/cloudposse/atmos/blob/HEAD/agent-skills/skills/atmos-diagnostics/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/atmos-diagnostics, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Atmos Diagnostics

Use this skill when debugging what Atmos is doing at runtime with machine-readable diagnostics. Diagnostics are configuration-driven, not a standalone command.

Configuration

Enable diagnostics in atmos.yaml:

diagnostics:
  enabled: true
  file: .atmos/diagnostics/events.jsonl
  include_output: false

Or with environment variables:

export ATMOS_DIAGNOSTICS_ENABLED=true
export ATMOS_DIAGNOSTICS_FILE=/tmp/atmos-events.jsonl
export ATMOS_DIAGNOSTICS_INCLUDE_OUTPUT=false

Diagnostics are active only when enabled is true and file is non-empty.

Event Stream

Atmos appends one JSON object per line to the configured file. Events are flat JSON for easy inspection with jq, grep, and CI artifact upload.

Common event types include:

  • process.start
  • process.end
  • process.output when include_output: true

Fields can include type, time, id, command, args, cwd, TTY flags, started, success, canceled, exit_code, duration_ms, signal details, error, stream, data, bytes, and sequence.

Debugging Workflow

ATMOS_DIAGNOSTICS_ENABLED=true \
ATMOS_DIAGNOSTICS_FILE=/tmp/atmos-events.jsonl \
atmos terraform plan vpc -s plat-ue2-dev

jq . /tmp/atmos-events.jsonl

Set include_output: true only when command output is needed. Output events can be noisy, though Atmos masks sensitive values before writing diagnostics.

Guidance

  • Use diagnostics when a command runs a subprocess unexpectedly, exits with an unclear code, or behaves differently in CI and locally.
  • Attach the JSONL file as a CI artifact for failed runs.
  • Keep diagnostics files out of version control.
  • Diagnostics are best-effort and should not be used as a replacement for command exit codes.
  • If a user asks for a CLI diagnostics command, verify current atmos --help; the shipped surface is config/env driven unless a newer command exists.