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 sign-in page in your browser and prints the link. Sign in with Discord. The browser sends the login back to the CLI, which checks it and stores the token in ~/.godfather/config.json.
  3. If the browser cannot reach the CLI (no browser on this computer, an older server, or no sign-in within 5 minutes), the CLI asks you to paste the token that the sign-in page shows. godfather auth --paste goes straight to that, for a browser on another computer.
  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, Sessions, Set up VS Code, 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. If none of your pods is running, the CLI shows the next session on your pods. A pod starts 10 minutes before its session.

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 connect --admin         # Ask for a root shell (officers, when pod admin is on)
godfather connect --forward 8080  # Also open http://localhost:8080 to port 8080 on the pod
godfather sessions                # Upcoming sessions on your pods, in local time
godfather vscode                  # Set up VS Code Remote-SSH for a pod, picking from a list
godfather vscode <pod-id>         # The same for one pod; run it again to renew the certificate
godfather status                  # Show server, org, login, token expiry and version
godfather auth                    # Log in with Discord in your browser
godfather auth --paste            # Log in by pasting the token
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

VS Code

godfather vscode sets up a pod for the VS Code Remote - SSH extension:

  1. It gets a 12-hour certificate for the pod and saves it as ~/.godfather/ssh/<pod-id>-cert.pub.
  2. It writes a Host godfather-<pod-id> block to ~/.godfather/ssh/config and adds one Include line for that file at the top of ~/.ssh/config.
  3. If the code command is on your PATH, it opens VS Code on /workspace/users/<you> on the pod. Otherwise run Remote-SSH: Connect to Host... in VS Code and pick godfather-<pod-id>.

VS Code runs as your pod account (godfather_<you>), with the same files and limits as godfather connect. After 12 hours VS Code cannot reconnect; run godfather vscode <pod-id> again. The pod must run image 2.3.0 or later. godfather vscode --admin gives officers a root login on a pod with pod admin on.

Web apps on a pod

A server that you start on the pod on 127.0.0.1:<port> (for example a llama.cpp chat UI or Jupyter) is reachable from your laptop through a forward:

godfather connect <pod-id> --forward 8080        # http://localhost:8080 opens port 8080 on the pod
godfather connect <pod-id> --forward 9000:8081   # http://localhost:9000 opens port 8081 on the pod

The forward stays open while the shell is open. VS Code forwards ports by itself. Other members of the pod can reach the same port, so protect a service with a token or password.

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.
  • ssh/<pod-id>-cert.pub, ssh/config: the certificate and Host block of each pod set up for VS Code.

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), login_server.py (the sign-in callback), 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/:

uv sync --group dev
uv run pytest -q tests

make check-cli at the repo root runs ruff, the tests and a build, as CI does.

Releases go to PyPI when a version bump is merged to main; see the repo README.

Contributing

See CONTRIBUTING.md.

License

MIT — see the LICENSE file for details.

Support

Built by AI Society at Arizona State University.

Metadata

Release files for godfather-cli 2.4.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.4.0
File Size Uploaded Provenance Actions
godfather_cli-2.4.0.tar.gz 33.1 kB With provenance Details for godfather_cli-2.4.0.tar.gz

Built distribution (wheel)

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

Total release size: 60.8 kB

Release files / godfather_cli-2.4.0.tar.gz

Download URL godfather_cli-2.4.0.tar.gz
Size 33.1 kB
Tags Source
SHA-256 checksum
How to use checksums
137ec2c6537a1fd7689174377b5d2cb76ea163fdcca0343c8cfcc599e9578294
BLAKE2b-256 checksum
How to use checksums
7e7de9dbf3f48e09c23487aa68304bd3db6309714f55cc2d035b939b63dfb490
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 5, 2026.

Transparency log

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

Download URL godfather_cli-2.4.0-py3-none-any.whl
Size 27.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b4339de3a72a6eb199c899d6af71640d13dbbede06fd9539d017fe9417db0d22
BLAKE2b-256 checksum
How to use checksums
6d520061d4543d969bc75aadc7f85aadf0db76045499ccbd5c49aa04e9ae9216
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 5, 2026.

Transparency log

Security for godfather-cli 2.4.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.4.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 Nov 5, 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