Skip to main content

atmos version list

List recent Atmos releases with pagination and filtering options.

atmos version list --help

Usage​

Execute the version list command like this:

atmos version list

This command displays recent Atmos releases in a clean, formatted table with support for pagination, date filtering, and multiple output formats.

tip

Run atmos version list --help to see all the available options

Examples​

List the last 10 releases (default):

atmos version list

List the last 20 releases:

atmos version list --limit 20

List releases starting from offset 10:

atmos version list --offset 10

Include pre-release versions:

atmos version list --include-prereleases

List releases since a specific date (ISO 8601 format):

atmos version list --since 2025-01-01

Output as JSON:

atmos version list --format json

Output as YAML:

atmos version list --format yaml

Combine multiple options:

atmos version list --limit 5 --include-prereleases --format json

Flags​

--limit
Maximum number of releases to display (1-100). Default: 10
--offset
Number of releases to skip for pagination. Default: 0
--since
Only show releases published after this date. Format: ISO 8601 (YYYY-MM-DD)
--include-prereleases
Include pre-release versions (beta, alpha, rc). Default: false
--format
Output format: table, json, or yaml. Default: table

Features​

  • Clean table view - Borderless table with header separator
  • Markdown-rendered titles - Release titles displayed with proper formatting and colors
  • Date filtering - Filter releases with --since for specific time ranges
  • Pagination support - Browse through extensive release history with --limit and --offset
  • Current version indicator - Green bullet (●) marks your installed version
  • Spinner feedback - Visual feedback during GitHub API calls (when TTY is available)
  • Terminal width detection - Automatically adapts to your terminal size

GitHub API Rate Limits​

The command uses the GitHub API which has rate limits:

  • Without authentication: 60 requests/hour
  • With authentication: 5,000 requests/hour

To increase your rate limit, set a GitHub token:

# Using GitHub CLI (recommended)
export ATMOS_GITHUB_TOKEN=$(gh auth token)

# Or set GITHUB_TOKEN directly
export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
note

ATMOS_GITHUB_TOKEN takes precedence over GITHUB_TOKEN. This allows you to use a different token for Atmos without affecting other tools that use GITHUB_TOKEN.

No special scopes are needed for accessing public repositories.

Use Cases​

Browse Release History​

Quickly review recent changes before upgrading:

atmos version list --limit 5

Export Release Data​

Export release data for compliance or auditing:

atmos version list --format json > releases.json

Script Version Discovery​

Use in CI/CD pipelines to discover versions:

VERSION=$(atmos version list --format json | jq -r '.[0].tag')

Find Specific Releases​

Filter by date to find releases in a specific timeframe:

atmos version list --since 2025-01-01 --limit 20