Skip to main content

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.

Python License

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 opens the AI Society platform's sign-in page in your browser (and prints the link). Sign in with Discord and copy the token shown there.
  3. Paste the token back into the terminal. The CLI checks it with the platform 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 90 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. Use the arrow keys to choose Connect to a pod, List pods, Status, Log out or Exit, and press Enter. Ctrl-C quits.

Connect to a pod shows a list of your pods with their status, access and pod ID. A pod that is not running shows with the reason and cannot be chosen. If only one pod is running, the CLI asks for a yes instead.

When input is not a terminal (for example in a script), the menu and the pod list use numbered prompts.

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 server, org, login, token expiry and version
godfather auth                    # Log in, or refresh an expired session
godfather logout                  # Clear the stored session
godfather update                  # Update the CLI to the latest version

# Use another platform server or organization
godfather --api-url https://platform.example.com --org soda 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.

Server and organization

By default the CLI talks to the AI Society platform with the org ais. --api-url and --org (or GODFATHER_API_URL and GODFATHER_ORG) pick another server or org; the ones you last logged in with are remembered.

Troubleshooting

  • "Couldn't reach <url>" — check your internet connection and that the API URL is correct (godfather status shows what's currently configured).
  • "Your token is invalid or expired" — run godfather auth and sign in again. In the menu, the CLI offers to do this for you.
  • "Pod is not running" — the pod stopped. Ask an officer to start it.
  • "You are no longer a member of this organization" — rejoin the club's Discord server, then try again.
  • "SSH could not log in to the pod" — the pod does not run the godfather-base image. Ask an officer 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), picker.py (arrow-key menu and pod picker), auth.py (platform sign-in), 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 version bump is merged to main; see the repo README.

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

Built by AI Society at Arizona State University.

Metadata

Release files for godfather-cli 2.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for godfather-cli 2.1.0
File Size Uploaded Provenance Actions
godfather_cli-2.1.0.tar.gz 20.3 kB With provenance Details for godfather_cli-2.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for godfather-cli 2.1.0
File Interpreter ABI Platform Actions
godfather_cli-2.1.0-py3-none-any.whl Python 3 none any Details for godfather_cli-2.1.0-py3-none-any.whl

Total release size: 41.0 kB

Release files / godfather_cli-2.1.0.tar.gz

Download URL godfather_cli-2.1.0.tar.gz
Size 20.3 kB
Tags Source
SHA-256 checksum
How to use checksums
1492dc9008dcd6892c5a42b62c18df7f3f5cac003b65f3e6595fed17bfb1e089
BLAKE2b-256 checksum
How to use checksums
bf3ddd99db1b477883925ed6d088dee2967ca5b56e4c7707902cd7d51a9687ce
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 9, 2026.

Transparency log

Release files / godfather_cli-2.1.0-py3-none-any.whl

Download URL godfather_cli-2.1.0-py3-none-any.whl
Size 20.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2d1d340dec570464fcca835ad2e43ad849c49518a09809d9cc2403458af6a53f
BLAKE2b-256 checksum
How to use checksums
d2ad5dbde93baa76729f67941d910a979373b59d273553f8b8ae0065ef4c111f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 9, 2026.

Transparency log

Security for godfather-cli 2.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for godfather_cli-2.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 9, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page