Metadata-Version: 2.4
Name: godfather-cli
Version: 1.1.0
Summary: Free compute for ASU students: connect to AI Society at ASU GPU pods
Author-email: AI Society ASU <theaisocietyasu@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/theaisocietyasu/godfather
Project-URL: Repository, https://github.com/theaisocietyasu/godfather
Project-URL: Issues, https://github.com/theaisocietyasu/godfather/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Requires-Dist: rich>=13.0.0
Requires-Dist: packaging>=20.0
Dynamic: license-file

# 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](https://img.shields.io/badge/python-3.8+-blue.svg)
![License](https://img.shields.io/badge/license-MIT-green.svg)

## Installation

Install from PyPI:

```bash
pip install godfather-cli
```

Or install straight from GitHub:

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

For local development:

```bash
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

```bash
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/`:

```bash
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](https://discord.gg/fXWXwz6fEG)

Built by [AI Society at Arizona State University](https://ais-asu.com/).
