m-gpux 1.0.5

Professional CLI toolkit for Modal GPU workflows, account management, and billing visibility

m-gpux

m-gpux is a professional CLI toolkit for Modal power users who need fast GPU access, multi-profile account control, and simple cost visibility.

Highlights

• Interactive GPU hub for Jupyter, script execution, and web shell sessions
• Multi-account profile management in one command namespace
• Billing inspection per profile or across all configured accounts
• Friendly terminal UX with rich tables, prompts, and guided flows

Table of Contents

• Installation
• Quick Start
• Core Commands
• Documentation
• Architecture
• Troubleshooting
• Contributing

Installation

Requirements

• Python 3.10+
• Modal account credentials (token_id, token_secret)
• Modal CLI in PATH (modal command)

Install from source

git clone https://github.com/PuxHocDL/m-gpux.git
cd m-gpux
pip install -e .

Install from PyPI

pip install m-gpux

Quick Start

# 1) Add your first profile
m-gpux account add

# 2) Check configured profiles
m-gpux account list

# 3) Launch the interactive GPU hub
m-gpux hub

# 4) Inspect 30-day usage across all accounts
m-gpux billing usage --days 30 --all

Core Commands

Global

m-gpux --help
m-gpux info

Profile Management

m-gpux account list
m-gpux account add
m-gpux account switch <profile_name>
m-gpux account remove <profile_name>

Billing

m-gpux billing open
m-gpux billing usage --days 7
m-gpux billing usage --account personal
m-gpux billing usage --all

Interactive Hub

m-gpux hub

Hub actions:

• Jupyter Lab on selected GPU
• Run local Python script on selected GPU
• Interactive web Bash shell on selected GPU

Documentation

• Website: https://puxhocdl.github.io/m-gpux/
• Local docs index: docs/index.md
• Getting started: docs/getting-started.md
• Commands: docs/commands.md
• FAQ: docs/faq.md

Architecture

• m_gpux/main.py: CLI entrypoint and command registration
• m_gpux/commands/account.py: profile CRUD and active profile switching
• m_gpux/commands/billing.py: usage aggregation and billing dashboard links
• m_gpux/commands/hub.py: guided GPU runtime launcher

Configuration

Modal profiles are persisted in ~/.modal.toml.

If the active profile is removed, another existing profile is promoted automatically.

Troubleshooting

• No configured Modal profiles found
  • Run m-gpux account add.
• modal: command not found
  • Install Modal CLI and ensure PATH is set correctly.
• Script file does not exist in hub mode
  • Run command from the script directory or provide the correct filename.

Contributing

pip install -e .
python -m m_gpux.main --help

Open PRs are welcome for UX polish, command improvements, and docs quality.

Release to PyPI

The repository includes automated PyPI publishing via GitHub Actions.

1. Configure a Trusted Publisher on PyPI with:

• Project: m-gpux
• Owner: PuxHocDL
• Repository: m-gpux
• Workflow: publish-pypi.yml
• Environment: pypi

2. Create GitHub environment pypi in repository settings.
3. Bump version in pyproject.toml.
4. Create and push a version tag:

git tag v1.0.1
git push origin v1.0.1

The workflow Publish Python Package will build and publish automatically with OIDC.

License

MIT