Godfather CLI

Command-line client for Godfather, free compute for ASU students run by the AI Society at ASU. Log in with your Discord account and SSH into a GPU or CPU machine the club pays for, with your own private workspace.

Installation

Install from PyPI:

pip install godfather-cli

Or install straight from GitHub:

pip install git+https://github.com/theaisocietyasu/godfather.git#subdirectory=cli

For local development:

git clone https://github.com/theaisocietyasu/godfather.git
cd godfather/cli
pip install -e .

Getting started

1. Run godfather with no arguments. On first run you won't be logged in yet, so it'll walk you into the login flow.
2. It prints a link to the admin portal's /cli-auth page. Open it, sign in with Discord, and copy the token shown there.
3. Paste the token back into the terminal. The CLI verifies it with the backend and stores it in ~/.godfather/config.json.
4. From the menu (or godfather connect), pick a pod. The CLI creates an SSH key on your machine the first time, asks the server for a 12-hour certificate for that pod, and opens the connection.

A token lasts 30 days. When it expires, or if you leave the Discord server, the CLI asks you to log in again.

You need OpenSSH installed (ssh and ssh-keygen). macOS, Linux and Windows 10+ ship it.

Usage

Interactive menu

Running godfather with no arguments opens a menu to list pods, connect, check status, or log out.

Commands

godfather list                    # List pods you can connect to
godfather connect                 # Connect to a pod, picking from a list
godfather connect <pod-id>        # Connect to a specific pod
godfather status                  # Show login and configuration status
godfather auth                    # Log in, or refresh an expired session
godfather logout                  # Clear the stored session
godfather update                  # Update the CLI to the latest version

# Point the CLI at a non-default backend (mainly for local development)
godfather --api-url https://your-backend.example.com list

Files it keeps

Everything lives in ~/.godfather/:

• config.json: your token (mode 600). Treat it like a password.
• ssh/id_ed25519, ssh/id_ed25519.pub: your SSH key, created on first connect. The private key never leaves your machine.
• ssh/id_ed25519-cert.pub: the certificate for the last pod you connected to.

Delete the folder to reset everything.

Backend URL

By default the CLI talks to https://admin.ais-asu.com. You can override this with, in order of priority: GODFATHER_API_URL, BACKEND_URL, NEXT_PUBLIC_BACKEND_URL, NEXT_PUBLIC_API_URL, or the --api-url flag. This mainly matters if you're running the backend locally.

Troubleshooting

• "Couldn't reach <url>" — check your internet connection and that the API URL is correct (godfather status shows what's currently configured).
• "That token is invalid or expired" — get a fresh token from the admin portal's /cli-auth page and try again.
• "SSH could not log in to the pod" — the pod was created before Godfather 1.1.0 or does not run the godfather-base image. Ask an admin to recreate it.
• "A valid SSH public key is required" — your CLI is older than the server. Run godfather update.
• ssh: command not found — install OpenSSH; the CLI uses your system's ssh and ssh-keygen.

Development

The code is in godfather_cli/: cli.py (commands and menu), auth.py (token login), pod_manager.py (API calls), ssh_connector.py (keys, certificate, running ssh), update_checker.py (PyPI version check), ui.py (shared console styling). Tests are in tests/:

pip install -e . pytest
pytest -q tests

Releases go to PyPI when a cli-v<version> tag is pushed; see DEPLOYMENT.md in the repo root.

Contributing

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/your-feature).
3. Commit your changes and open a Pull Request.

License

MIT — see the LICENSE file for details.

Support

• Discord

Built by AI Society at Arizona State University.