hopper
A git-like CLI for tutors on the hopper
platform. It wraps git and the hopper orchestration services to safely
pull, grade, and push all of a tutor's assigned student repositories.
Admins can use the CLI for any course and operate on all its student repositories, even when enrolled as a student or assigned as a tutor there.
Installation
Install via uv
(recommended) or pipx, or grab
a prebuilt binary from the
Forgejo releases page. Do not
install via go install or build from source unless you are developing
hopper — see Development for why.
uv (recommended, installs an isolated executable):
uv tool install hopper-cli
or with pipx (also installs an isolated executable):
pipx install hopper-cli
To upgrade later:
uv tool upgrade hopper-cli
pipx upgrade hopper-cli
Use the upgrade command matching how you installed hopper.
Avoid installing directly with pip: it installs into the active Python
environment and may conflict with other packages or be blocked by a
system-managed Python installation. Use uv or pipx for an isolated installation.
If you already installed hopper with pip, update it with
pip install --upgrade hopper-cli in that same environment.
Prebuilt binaries
Prebuilt binaries for recent releases are available on the Forgejo releases page.
Requirements
- git — hopper drives
gitunder the hood - Python 3.8+ (only for the pip/pipx installation)
- An account as tutor/staff/admin on a hopper instance
Getting started
hopper auth # set up an instance profile + API key
hopper init <course> # create a workspace directory bound to a course
cd <course-uid>
hopper pull # clone/update all your assigned student repos
Concepts
Profiles
A profile is a set of service URLs plus your API key — typically one per
university. They live in the global config at os.UserConfigDir()/hopper/config.yaml
(~/.config/hopper/ on Linux, ~/Library/Application Support/hopper/ on
macOS, %AppData%\hopper\ on Windows).
hopper auth interactively creates a profile, offering known presets (e.g.
alu for Albert-Ludwigs-Universität Freiburg) or custom URLs. You can hold
several profiles and pick which one a workspace uses at init time.
Workspaces
hopper init [profile/]<course> creates a ./<course-uid>/ directory with a
.hopper.yaml inside. <course> may be a UID (2025WS-EidP) or numeric ID.
With multiple profiles, prefix the profile: hopper init alu/2025WS-EidP.
All commands run inside that directory and never write outside it.
Commands
| Command | Description |
|---|---|
hopper auth |
Interactively set up a profile (preset or custom). |
hopper auth list / status / remove <id> |
Manage profiles. |
hopper init [profile/]<course> |
Bind a new directory to a course. |
hopper pull |
Clone or pull --rebase --autostash every assigned student repo. |
hopper push [msg] |
Commit README changes, validate point schema, push. |
hopper commit <msg> |
Commit without pushing (recovery path). |
hopper status |
Per-student branch, ahead/behind, dirty state. |
hopper students |
List students assigned to you. |
hopper info |
Course info, your role, exercises. |
hopper version |
Print version. |
Run hopper <command> --help for the full flag reference of each command.
auth
hopper auth # interactive setup (preset picker or custom URLs)
hopper auth --custom # skip the preset picker and enter custom URLs
hopper auth list # list configured profiles
hopper auth status # show the current authentication state
hopper auth remove alu # remove a profile
Authorization happens in your browser: hopper opens the instance's authorize page and receives the new API key via a local callback. If that fails, it falls back to asking you to paste a key manually.
init
hopper init 2025WS-EidP # uses the only/default configured profile
hopper init alu/2025WS-EidP
hopper init alu/42 # numeric course ID also works
hopper init --force alu/2025WS-EidP # overwrite an existing .hopper.yaml
pull
hopper pull # sync all assigned student repos
hopper pull --student alice # pull a single student by username
hopper pull --only a,b,c # pull only the listed usernames
hopper pull --prune # remove local repos of students no longer assigned
hopper pull -j 8 # 8 concurrent git operations (default 4)
--pruneremoves local repos of students no longer assigned to you, after showing a preview and asking for confirmation;--no-pruneskips pruning.- Per-repo failures are reported and skipped — one bad repo does not abort the whole run.
push / commit
hopper push # commit */README.md changes and push (default msg: "Grade exercises")
hopper push "Grade exercise 3" # custom commit message
hopper push --all # stage all changes, not just */README.md
hopper push --allow-invalid # push even when the README point schema is invalid
hopper commit "WIP grading" # commit without pushing (recovery path)
Before pushing, hopper validates that each modified README's first line
contains exactly one point schema like (12/15). Invalid pushes are blocked
unless --allow-invalid is given. A conflicting rebase surfaces the conflict
and halts that repo instead of destroying local work — hopper never runs
git reset --hard.
status / students / info
hopper status # table: student, branch, ahead/behind, dirty/clean
hopper students # table: username, name, matrikel
hopper info # course name/uid/id, profile, your user and role, exercises
Version gate
On every command that touches the server (everything except auth,
version, and help), hopper asks the active profile's orchestration server
for the minimum supported CLI version:
- running version < minimum → the CLI refuses to run and tells you to upgrade;
- running version >= minimum → proceeds;
- server unreachable → proceeds silently (can't check offline).
License
Licensed under AGPL-3.0-or-later.
Development
Requires Go (see go.mod for the minimum version) and
Task.
⚠️ Note: Building from source without injecting the version via ldflags produces a binary with a wrong/fallback version string (
v0.1.0ordev). This breakshopper version, the CLI's self-upgrade check, and the server-side minimum-version gate. End users should install via uv/pipx or the prebuilt release binaries instead — see Installation. If you do build from source, always inject the version as shown below.
A plain go install works for quick local experiments only:
go install codeberg.org/hopper/cli/cmd/hopper@latest
Or clone the repository and build with Task (task build below produces
bin/hopper). Useful tasks:
task build # build the CLI binary to bin/hopper
task test # run unit tests
task lint # run golangci-lint
task fmt # format Go code and imports
task default # fmt, lint, vet, test, build
task ci # strict CI gate: fmt, lint, vet, test, build, clean tree
task hooks:install # point git at the versioned githooks directory
The version is injected at build time via ldflags:
go build -ldflags "-X codeberg.org/hopper/cli/internal/cmd.Version=vX.Y.Z" -o hopper ./cmd/hopper/
User-facing output
Use internal/ui for messages so commands share the same styling and spacing:
Successmarks completed actions;Infois for neutral progress and hints.WarnandErrorwrite diagnostics to stderr. Keep recovery instructions in the same message so they stay with the error when output is redirected.- Message helpers terminate output with one newline and indent multiline details beneath the message text.
Sectionprints only a heading. UseBreakonce between output blocks, never before the first heading or after the last message.- Keep raw output such as the version line unstyled.
- Disable ANSI styling for redirected output,
NO_COLOR, andTERM=dumb.
Metadata
Release files for hopper-cli 1.3.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| hopper_cli-1.3.2.tar.gz | 17.6 kB | Without provenance | Details for hopper_cli-1.3.2.tar.gz |
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| hopper_cli-1.3.2-py3-none-win_arm64.whl | Python 3 | none | Windows ARM64 | Details for hopper_cli-1.3.2-py3-none-win_arm64.whl |
| hopper_cli-1.3.2-py3-none-win_amd64.whl | Python 3 | none | Windows x86-64 | Details for hopper_cli-1.3.2-py3-none-win_amd64.whl |
| hopper_cli-1.3.2-py3-none-manylinux2014_x86_64.whl | Python 3 | none | Linux glibc 2.17+ x86-64 | Details for hopper_cli-1.3.2-py3-none-manylinux2014_x86_64.whl |
| hopper_cli-1.3.2-py3-none-manylinux2014_aarch64.whl | Python 3 | none | Linux glibc 2.17+ ARM64 | Details for hopper_cli-1.3.2-py3-none-manylinux2014_aarch64.whl |
| hopper_cli-1.3.2-py3-none-macosx_11_0_arm64.whl | Python 3 | none | macOS 11.0+ ARM64 | Details for hopper_cli-1.3.2-py3-none-macosx_11_0_arm64.whl |
| hopper_cli-1.3.2-py3-none-macosx_10_9_x86_64.whl | Python 3 | none | macOS 10.9+ x86-64 | Details for hopper_cli-1.3.2-py3-none-macosx_10_9_x86_64.whl |
Total release size: 74.9 MB
Release files / hopper_cli-1.3.2.tar.gz
| Download URL | hopper_cli-1.3.2.tar.gz |
|---|---|
| Size | 17.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7256c0a3bdfeea83c9f71c6fac780b0985b90551e8bf43ca5ae443db9f0071f6
|
|
BLAKE2b-256 checksum How to use checksums |
e49b47d7dd69a46755e48dd30f82ac81e2723218eae411f94c63657f249750e7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.2
|
Release files / hopper_cli-1.3.2-py3-none-win_arm64.whl
| Download URL | hopper_cli-1.3.2-py3-none-win_arm64.whl |
|---|---|
| Size | 14.9 MB |
| Tags | Python 3 Windows ARM64 |
|
SHA-256 checksum How to use checksums |
7806660793832598115a2aa6273c0e77f5d388d990ec03a63688ed4403720ec9
|
|
BLAKE2b-256 checksum How to use checksums |
4f2af40a664677f8c368e6e5f6db08f165f9b631e8fcafbbe830ad680e0aa37a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.2
|
Release files / hopper_cli-1.3.2-py3-none-win_amd64.whl
| Download URL | hopper_cli-1.3.2-py3-none-win_amd64.whl |
|---|---|
| Size | 15.6 MB |
| Tags | Python 3 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
d3bbe3553a13e7926a4b9ad4410273d1341a8735ca756120709af6cc8abe3c13
|
|
BLAKE2b-256 checksum How to use checksums |
9afc01ac02e0e8da1307dd56b6bd74d45bf4c9003e8b0cd6a6484a825a409132
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.2
|
Release files / hopper_cli-1.3.2-py3-none-manylinux2014_x86_64.whl
| Download URL | hopper_cli-1.3.2-py3-none-manylinux2014_x86_64.whl |
|---|---|
| Size | 7.7 MB |
| Tags | Linux glibc 2.17+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
42ec03db24cd8e597fa087d9450edeb4b4ce438fa91f7709e16d5a9e08037e10
|
|
BLAKE2b-256 checksum How to use checksums |
ecba618fb8d6583f8972b2aa894677697f049590a06e5c18ab60589c376d3d60
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.2
|
Release files / hopper_cli-1.3.2-py3-none-manylinux2014_aarch64.whl
| Download URL | hopper_cli-1.3.2-py3-none-manylinux2014_aarch64.whl |
|---|---|
| Size | 14.2 MB |
| Tags | Linux glibc 2.17+ ARM64 Python 3 |
|
SHA-256 checksum How to use checksums |
c3698aa90cabe9bdc4995db653a341418df9b07cd541836c7775bb65138e11e6
|
|
BLAKE2b-256 checksum How to use checksums |
0ea6badec30238dbc21dca35f6a3ebb41dd62d51887431a3f16ef048d36b2dee
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.2
|
Release files / hopper_cli-1.3.2-py3-none-macosx_11_0_arm64.whl
| Download URL | hopper_cli-1.3.2-py3-none-macosx_11_0_arm64.whl |
|---|---|
| Size | 14.5 MB |
| Tags | Python 3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
3e38577be812f355cda4451cf7a3fe3db107f70cc18739f69849acbb3fa5aa02
|
|
BLAKE2b-256 checksum How to use checksums |
7e8bff68577167cb16d92d5c9e84f62f4053fdfaaa01923b697233aaa2174f9b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.2
|
Release files / hopper_cli-1.3.2-py3-none-macosx_10_9_x86_64.whl
| Download URL | hopper_cli-1.3.2-py3-none-macosx_10_9_x86_64.whl |
|---|---|
| Size | 7.9 MB |
| Tags | Python 3 macOS 10.9+ x86-64 |
|
SHA-256 checksum How to use checksums |
eb8c0a3beb617353077b49f65deab139177cc3b9fe8c95adc633339d59748711
|
|
BLAKE2b-256 checksum How to use checksums |
179749cc9835b97a3cf428be227da5b9729cb1e8920f8205205318c3bbc24cde
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.2
|
Security for hopper-cli 1.3.2
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
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.