Astro CLI 🚀

English | 中文 | 日本語 | Français

Your gateway to cosmos — Query astronomical data from command line

✨ What is Astro CLI?

Astro CLI is a modern command-line tool that provides quick access to multiple astronomical data services. It integrates Astroquery and other data access methods (direct API calls, HTTP requests) to help astronomers, researchers, and anyone query astronomical databases efficiently from the terminal.

17 data sources. One command. Beautiful output. Multi-language support. Extensible for future services.

🧩 Supported Data Sources

Query data from 17 different astronomical databases and services:

| Service | Description | Command | Alias | |---------|------------|----------|--------| | SIMBAD | Basic astronomical data & object identification | astrocli simbad | astrocli sim | | VizieR | Catalog database search | astrocli vizier | astrocli viz | | ALMA | ALMA radio telescope observations | astrocli alma | - | | ESASky | Sky region visualization | astrocli esasky | - | | Gaia | ESA Gaia mission data | astrocli gaia | - | | IRSA | Infrared Science Archive | astrocli irsa | - | | HEASARC | X-ray and Gamma-ray data | astrocli heasarc | astrocli hea | | JPL Horizons | Solar System ephemerides | astrocli jpl | - | | MAST | Space Telescope Archive (HST, JWST, etc.) | astrocli mast | - | | ADS | Astrophysics literature search | astrocli ads | - | | NED | Extragalactic Database | astrocli ned | - | | NIST | Atomic spectra database | astrocli nist | - | | NASA Exoplanet | Exoplanet catalog | astrocli exoplanet | astrocli exo | | SDSS | Sloan Digital Sky Survey | astrocli sdss | - | | ESO | European Southern Observatory | astrocli eso | - | | Splatalogue | Molecular line database | astrocli splatalogue | astrocli spl | | AAVSO VSX | Variable Star Index | astrocli aavso | astrocli aav | | Fermi-LAT | Gamma-ray telescope data | astrocli fermi | astrocli fer |

🌟 Key Features

• 📦 Multi-Source Access: Query 17+ astronomical databases from a single interface
• 🌏 Internationalized UI: Built-in support for English, Chinese (Simplified), and Japanese
• 📊 Rich Output: Beautifully formatted tables with support for exporting to CSV, ECSV, FITS, and more
• ⚡ Smart Defaults: Sensible defaults with extensive customization options
• 🔍 Service Health: Built-in connectivity testing (--ping) and field validation (--field)
• 🧑‍💻 Shell Completion: Auto-completion support for Bash, Zsh, and Fish
• 🌌 Extensible: Easy to add new astronomical data services

📦 Installation

Astro CLI offers multiple installation methods. Choose the one that suits you:

Method 1: npm Global Install (Recommended)

# Global install (requires Node.js ≥18 and Python 3.11+)
npm install -g astroquery-cli

# After installation, all three commands are available:
astroquery-cli --help    # Full command name
aqc --help               # Short command (recommended)
astrocli --help          # Alias command

# Example: Query SIMBAD for M31
astrocli simbad object "M31"

Method 2: npx/pnpm (No Install Required)

# Using npx (no installation needed)
npx astroquery-cli --help

# Using pnpm
pnpm astroquery-cli --help

# Example
npx astroquery-cli simbad object "M31"

Method 3: PyPI Install (For Python Users)

# Install Python package from PyPI
pip install aqc-cli

# After installation, available commands:
aqc --help
astrocli --help

Method 4: Install from Source

git clone https://github.com/inoribea/astroquery-cli.git
cd astroquery-cli
pip install -e .

📋 Package Naming

| Platform | Package Name | Install Command | |----------|--------------|-----------------| | npm | astroquery-cli | npm install -g astroquery-cli | | PyPI | aqc-cli | pip install aqc-cli |

After installation, all three commands are available:

• astroquery-cli - Full command name
• aqc - Short command (recommended)
• astrocli - Alias command

Environment Variables

• AC_PYTHON - Specify Python interpreter path
• AC_VENV_DIR - Custom virtual environment cache directory (default: ~/.cache/astrocli)
• AC_FORCE_INSTALL=1 - Force reinstall/upgrade Python dependencies
• AC_DEBUG - Enable debug mode
• AC_LANG - Set default language (en/zh/ja)

📚 Usage

View All Available Commands

# Show all available modules and commands
astrocli --help

# Show help for a specific module
astrocli <module> --help

Query Examples

1. Query SIMBAD for an object

astrocli simbad object "M31"
astrocli simbad object "Crab Nebula" --show-all-cols

2. Search VizieR catalogs

# Find catalogs by keywords
astrocli vizier find-catalogs --keyword photometry --keyword galaxy

# Query a specific catalog
astrocli vizier object "M31" --radius 0.1 --catalog "I/261/gaiadr3"

3. Query AAVSO Variable Star Index (NEW!)

# Query a variable star by name
astrocli aavso object "SS Cyg"

# Search variable stars in a sky region
astrocli aavso region 196.421 18.018 --radius 0.5

# Get results in JSON format
astrocli aavso object "T CrB" --format json

4. Query Fermi-LAT Data (NEW!)

# Query Fermi data for a target
astrocli fermi object "Crab Nebula" --energy "1000,100000" --dates "2020-01-01 00:00:00, 2020-01-02 00:00:00"

# Clear Fermi cache
astrocli fermi clear-cache

5. Search ADS literature

astrocli ads search --title "exoplanet detection"
astrocli ads bibcode "2023A&A...555..959W"

🌐 Multi-Language Support

Change output language on-the-fly:

astrocli --lang en simbad object "M31"    # English
astrocli --lang zh simbad object "M31"    # Chinese (Simplified)
astrocli --lang ja simbad object "M31"    # Japanese
astrocli --lang fr simbad object "M31"    # French

Supported languages: English (en), Chinese (zh), Japanese (ja), French (fr)

🔧 Global Options

| Option | Description | |--------|-------------| | -l, --lang | Set output language (en/zh/ja) | | -p, --ping | Test connectivity to all services (top-level only) | | -f, --field | Check available fields for a module (top-level only) | | -d, --debug | Enable debug mode with verbose output | | -v, --verbose | Enable verbose output |

🧑‍💻 Shell Autocompletion

Install completion for your shell:

astrocli --install-completion bash   # Bash
astrocli --install-completion zsh    # Zsh
astrocli --install-completion fish   # Fish

Add this to your shell config (e.g., ~/.zshrc):

# For zsh
eval "$(astrocli --install-completion zsh)"

# For bash
eval "$(astrocli --install-completion bash)"

📊 Output & Export

Save query results to file:

astrocli simbad object "M31" --output-file results.csv

# Specify format explicitly
astrocli simbad object "M31" --output-file data.ecsv --output-format ecsv

Supported formats: csv, ecsv, fits, votable, html, latex, ascii

🔍 Testing Service Connectivity

Check if all data services are accessible:

astrocli --ping

🛠️ Development

Project Structure

astrocli/
├── src/                    # Source code (renamed from astroquery_cli)
│   ├── modules/           # Service-specific modules
│   │   ├── simbad_cli.py
│   │   ├── vizier_cli.py
│   │   ├── aavso_cli.py      # AAVSO VSX
│   │   ├── fermi_cli.py      # Fermi-LAT
│   │   └── ...
│   ├── utils.py            # Common utilities
│   ├── common_options.py   # Shared CLI options
│   ├── i18n.py            # Internationalization
│   └── main.py            # CLI entry point
├── locales/                # Translation files
│   ├── en/LC_MESSAGES/     # English
│   ├── zh/LC_MESSAGES/     # Chinese
│   ├── ja/LC_MESSAGES/     # Japanese
│   └── fr/LC_MESSAGES/     # French
├── package.json           # npm/npx configuration
├── pyproject.toml         # Python package config
└── README.md

Adding a New Module

1. Create modules/<service>_cli.py following existing patterns
2. Import in main.py's setup_subcommands()
3. Add to README module list
4. Add translations to locales/ directories

📄 License

BSD 3-Clause License

🙏 Acknowledgments

• aqc-mcp - MCP server for AI assistants
• Astroquery - Astronomical data access library
• Typer - Modern CLI framework
• Rich - Beautiful terminal output
• AAVSO - American Association of Variable Star Observers
• Fermi Team - Fermi Gamma-ray Space Telescope