/
MWA ASVO: Command Line Client (mwa-cli)

MWA ASVO: Command Line Client (mwa-cli)

Version: 1.0

Status: ACTIVE DEVELOPMENT

Overview

mwa-cli is a modern command-line interface for interacting with the MWA ASVO. It provides a streamlined, type-safe interface for:

  • searching MWA observations

  • submitting data processing jobs (conversion, download, voltage, beamformer, imaging)

  • monitoring job status and progress

  • downloading completed job results

Why mwa-cli?

mwa-cli represents a complete modernization of the manta-ray-client command-line experience:

Feature

mwa-cli

manta-ray-client

Feature

mwa-cli

manta-ray-client

Technology

Modern Python 3.12+ with async/await

Modern Python 3.12+

Type safety

Full type hints with mypy strict

Limited typing

API integration

Auto-synced with OpenAPI schema

Manual maintenance

Authentication

JWT tokens with auto-refresh

API key only

User Experience

Rich terminal output with colours

Plain text with colours (colorama)

Error messages

Helpful suggestions with context

Generic errors

Testing

80%+ coverage, integration tests

Limited test coverage

Relationship to other CLI tools

  • giant-squid The preferred CLI for most users. Feature-rich with interactive features.

  • manta-ray-client (mwa_client): Legacy tool being phased out. Still supported for batch CSV workflows.

  • mwa-cli: Modern replacement for manta-ray-client with enhanced capabilities

Prerequisites

Required

  • Python 3.12 or higher

    • check your verion: python3 --version

    • Install Python

  • MWA ASVO Account

Recommended

  • pip 24.0+ or uv (modern Python package installer)

    • Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh

  • Terminal with colour support

    • Modern terminsl (iTerm2, Windows Terminal, GNOME Terminal) recommended

    • Rich output formatting for better user experience

Installation

Option 1: Install from PyPI (Recommended)

Once published to PyPI:

pip install mwa-cli

Or using uv (faster):

uv pip install mwa-cli

Verify installation

mwa-cli --version

Option 2: Install from source (development)

For the latest development version:

# Clone repository git clone https://github.com/MWATelescope/manta-ray-client.git cd manta-ray-client # Create virtual environment python 3.12 -m venv venv source venv/bin/activate # On windows: venv\Scripts\activate # Install in development mode pip install -e ".[dev]" # Verify mwa-cli --version

Getting started

Quick start (5 minutes)

  1. Install mwa-cli (see installation above)

  2. Login to MWA ASVO

mwa-cli auth login

You’ll be prompted for an API key unless you’ve added the API key as an environment variable. Alternatively, the key can also be passed directly with the --api-key flag:

mwa-cli auth login --api-key=<YOUR_API_KEY>

  1. Monitor job status

# List all your jobs mwa-cli jobs list # Show specific job details mwa-cli jobs show 12345

  1. Search for observations (coming soon)

# Search by observation ID mwa-cli search --obs-id 1234567890 # Search by date range mwa-cli search --date-from 2026-06-01 --date-to 2026-07-01

  1. Submit a simple job (coming soon)

# Convert and download visibility data mwa-cli jobs submit conversion \ --obs-id 1234567890 \ --avg-time-res 8 \ --avg-freq-res 40 \ --delivery acacia

  1. Check login status

mwa-cli status

Authentication

Login

The login command authenticates with the MWA ASVO and stores JWT tokens locally:

mwa-cli login

Output:

+ Logged in as <username> Email example@example.com Token expires: 2026-07-07T06:29:56.572755+00:00Z

Token Storage

Tokens are securely stored at ~/.mwa-asvo/tokens.json:

  • File permissions: 0600 (readable only by you)

  • Contents: Access token, refresh token, expiration time

  • Auth-refresh: Token automatically refresh before expiration

Check Login status

mwa-cli auth status

Output:

Authentication Status User: <username> Email: example@example.com ID: 1234 Access token: 2026-07-07T06:32:08.692945+00:00Z Refresh token: 2026-07-14T06:17:08.692945+00:00Z

Logout

Clear stored credentials:

mwa-cli logout

Core commands

Schema management

Update local OpenAPI schema and generate models:

# Fetch latest schema from server mwa-cli schema update # Schema is cached at ~/.mwa-asvo/openapi.json # Models auto-generated to src/mwa_cli/models/generated.py

This ensures your CLI stays in sync with the latest API changes.

Observation Search

coming soon

Job Submission

coming soon