Skip to main content

atmos ai sessions

Use this command to manage your AI chat sessions. List active sessions, clean old ones, export sessions for backup or sharing, and import sessions from checkpoint files.

Experimental

Configure AI

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

atmos ai sessions --help

Description​

The atmos ai sessions command provides session management capabilities for Atmos AI conversations. Sessions allow you to:

  • Save and resume conversations with full context
  • Share AI interactions with your team via checkpoint files
  • Back up important troubleshooting sessions
  • Clean up old sessions to manage storage
  • Import sessions from other team members or projects

Each session maintains its own message history, allowing you to have multiple ongoing conversations about different aspects of your infrastructure.

Subcommands​

atmos ai sessions list​

Lists all available AI chat sessions with their details.

Usage:

atmos ai sessions list

Example:

Name                  Created              Updated              Messages  Model               Provider
eks-troubleshooting   2025-10-29 11:20:00  2025-10-29 16:45:00  18        gpt-4o              openai
vpc-migration         2025-10-30 14:30:00  2025-10-31 09:15:00  42        claude-sonnet-4-6   anthropic

Output uses the standard list format. When piped, it outputs a plain newline-separated list of session names.

atmos ai sessions clean​

Remove old AI chat sessions based on retention policy.

Usage:

atmos ai sessions clean [flags]

Flags:

--older-than <duration>
Delete sessions older than this duration. Supported units: h (hours), d (days), w (weeks), m (months). Default: 30d

Examples:

# Delete sessions older than 30 days (default)
atmos ai sessions clean

# Delete sessions older than 7 days
atmos ai sessions clean --older-than 7d

# Delete sessions older than 24 hours
atmos ai sessions clean --older-than 24h

# Delete sessions older than 2 weeks
atmos ai sessions clean --older-than 2w

# Delete sessions older than 3 months
atmos ai sessions clean --older-than 3m

atmos ai sessions export​

Export an AI chat session to a checkpoint file for backup or sharing.

Usage:

atmos ai sessions export <session-name> [flags]

Flags:

-o, --output <file>
Output file path (required). Format is auto-detected from file extension.
-f, --format <format>
Explicit output format: json, yaml, or markdown. If not specified, format is detected from the file extension.
--context
Include project context (ATMOS.md content, files accessed). Default: false
--metadata
Include session metadata. Default: true

Export Formats:

  • JSON - Machine-readable format, perfect for programmatic processing and archival
  • YAML - Human-readable and editable, good for version control
  • Markdown - Human-readable report format, ideal for documentation and sharing

Examples:

# Export to JSON (auto-detected from extension)
atmos ai sessions export vpc-migration --output session.json

# Export to YAML with project context
atmos ai sessions export eks-troubleshooting --output backup.yaml --context

# Export to Markdown for documentation
atmos ai sessions export security-audit --output report.md --format markdown

# Export with explicit JSON format
atmos ai sessions export my-session --output backup.txt --format json

Checkpoint File Contents:

A checkpoint file contains:

  • Version - Checkpoint format version for compatibility
  • Exported metadata - Export timestamp and user
  • Session information - Name, model, provider, timestamps, custom metadata
  • Complete message history - All user and assistant messages with timestamps
  • Session statistics - Message counts by role, token usage (if tracked)
  • Project context (optional) - ATMOS.md content, working directory, files accessed

atmos ai sessions import​

Import an AI chat session from a checkpoint file.

Usage:

atmos ai sessions import <checkpoint-file> [flags]

Flags:

-n, --name <name>
Name for the imported session. If not specified, uses the checkpoint's session name.
--overwrite
Overwrite existing session with the same name. Default: false (will error if session exists)
--context
Include project context from checkpoint. Default: true

Examples:

# Import session from JSON checkpoint
atmos ai sessions import session.json

# Import with custom name
atmos ai sessions import backup.yaml --name restored-session

# Import and overwrite existing session
atmos ai sessions import session.json --overwrite

# Import without project context
atmos ai sessions import backup.json --context=false

After Import:

Once imported, the session can be resumed with:

atmos ai chat --session <imported-session-name>

Use Cases​

Team Collaboration​

Export and share sessions with your team to collaborate on complex infrastructure problems:

# Developer exports troubleshooting session
atmos ai sessions export db-migration-issue --output db-migration.json

# Share file with team (git, Slack, email)

# Team member imports and continues the conversation
atmos ai sessions import db-migration.json --name db-migration-collab
atmos ai chat --session db-migration-collab

Session Backup and Archival​

Back up important sessions for future reference:

# Export critical sessions as markdown documentation
atmos ai sessions export prod-incident-2025-10 --output docs/incidents/2025-10-incident.md

# Export to YAML for version control
atmos ai sessions export architecture-decisions --output .atmos/archives/architecture.yaml

Knowledge Transfer​

New team members can import sessions from experienced colleagues:

# Senior engineer exports onboarding session
atmos ai sessions export atmos-getting-started --output onboarding/atmos-intro.json --context

# New team member imports and reviews
atmos ai sessions import onboarding/atmos-intro.json --name my-onboarding
atmos ai sessions export my-onboarding --output onboarding-review.md --format markdown

Cross-Project Learning​

Import sessions from other projects to reuse solutions:

# Export session from project A
cd /path/to/project-a
atmos ai sessions export vpc-setup --output ~/vpc-setup.json --context

# Import to project B with new name
cd /path/to/project-b
atmos ai sessions import ~/vpc-setup.json --name vpc-reference

Session Lifecycle​

  1. Create - Sessions are created automatically when you start a new chat:

    atmos ai chat --session my-new-session

  2. List - View all your sessions:

    atmos ai sessions list

  3. Resume - Continue a previous conversation:

    atmos ai chat --session my-new-session

  4. Export - Save a session for backup or sharing:

    atmos ai sessions export my-new-session --output backup.json

  5. Import - Restore or share a session:

    atmos ai sessions import backup.json

  6. Clean - Remove old sessions:

    atmos ai sessions clean --older-than 30d

Tips​

  • Use descriptive session names - Makes it easier to find and resume sessions later
  • Export before major changes - Create checkpoints before significant configuration changes
  • Regular cleanup - Use atmos ai sessions clean regularly to manage storage
  • Markdown exports for docs - Export important sessions as Markdown for team documentation
  • YAML for version control - YAML format works well with git and is human-readable
  • JSON for automation - Use JSON format for programmatic processing and archival