Skip to main content

hopper

License: AGPL-3.0-or-later PyPI Python Forgejo

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.

Installation

Install via pipx or pip, 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.

pipx (recommended, installs an isolated executable):

pipx install hopper-cli

or with pip:

pip install hopper-cli

To upgrade later:

pipx upgrade hopper-cli    # or: pip install --upgrade hopper-cli

Prebuilt binaries

Prebuilt binaries for recent releases are available on the Forgejo releases page.

Requirements

  • git — hopper drives git under 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)
  • --prune removes local repos of students no longer assigned to you, after showing a preview and asking for confirmation; --no-prune skips 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.0 or dev). This breaks hopper version, the CLI's self-upgrade check, and the server-side minimum-version gate. End users should install via pipx/pip 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:

  • Success marks completed actions; Info is for neutral progress and hints.
  • Warn and Error write 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.
  • Section prints only a heading. Use Break once 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, and TERM=dumb.

Metadata

Release files for hopper-cli 1.3.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 hopper-cli 1.3.0
File Size Uploaded Provenance Actions
hopper_cli-1.3.0.tar.gz 17.4 kB Without provenance Details for hopper_cli-1.3.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for hopper-cli 1.3.0
File Actions
hopper_cli-1.3.0-py3-none-win_arm64.whl Python 3 none Windows ARM64 Details for hopper_cli-1.3.0-py3-none-win_arm64.whl
hopper_cli-1.3.0-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for hopper_cli-1.3.0-py3-none-win_amd64.whl
hopper_cli-1.3.0-py3-none-manylinux2014_x86_64.whl Python 3 none Linux glibc 2.17+ x86-64 Details for hopper_cli-1.3.0-py3-none-manylinux2014_x86_64.whl
hopper_cli-1.3.0-py3-none-manylinux2014_aarch64.whl Python 3 none Linux glibc 2.17+ ARM64 Details for hopper_cli-1.3.0-py3-none-manylinux2014_aarch64.whl
hopper_cli-1.3.0-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for hopper_cli-1.3.0-py3-none-macosx_11_0_arm64.whl
hopper_cli-1.3.0-py3-none-macosx_10_9_x86_64.whl Python 3 none macOS 10.9+ x86-64 Details for hopper_cli-1.3.0-py3-none-macosx_10_9_x86_64.whl

Total release size: 74.8 MB

Release files / hopper_cli-1.3.0.tar.gz

Download URL hopper_cli-1.3.0.tar.gz
Size 17.4 kB
Tags Source
SHA-256 checksum
How to use checksums
955225410736e154c0c2e941203da967ff536326ebc6bc8e6cd7cd18a7a14fcf
BLAKE2b-256 checksum
How to use checksums
a5df2fe0cf55ff13b5243b5d07a768b0969906691e2a7716b00ecb6908eff081
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.0-py3-none-win_arm64.whl

Download URL hopper_cli-1.3.0-py3-none-win_arm64.whl
Size 14.9 MB
Tags Python 3 Windows ARM64
SHA-256 checksum
How to use checksums
ce6bf5f9452d1a044a00298ae0ff0e0ab045d6268e84c3f66bf6a613ba5ede6f
BLAKE2b-256 checksum
How to use checksums
6364afda6e9ba537733765ac75ae48b9c0f0bef518a7d8e621f06677f7c1fae2
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.0-py3-none-win_amd64.whl

Download URL hopper_cli-1.3.0-py3-none-win_amd64.whl
Size 15.6 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
154e7d5daa9552afd853fdfa22c42c9930dcb9ac91b2ca1a08982b0302d8d993
BLAKE2b-256 checksum
How to use checksums
490e28c7c48ec415aa6eb492706017aa712520e277c83e7320892a996008497a
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.0-py3-none-manylinux2014_x86_64.whl

Download URL hopper_cli-1.3.0-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
74c3beb0724aaaa4fc66491aa9a0fca8713b828f450ada31b88bcfa1899bcb4d
BLAKE2b-256 checksum
How to use checksums
715f26498df70844bfa1bdba002ea3d8f91f66ec501bddb963eea2620fcb45e0
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.0-py3-none-manylinux2014_aarch64.whl

Download URL hopper_cli-1.3.0-py3-none-manylinux2014_aarch64.whl
Size 14.2 MB
Tags Linux glibc 2.17+ ARM64 Python 3
SHA-256 checksum
How to use checksums
633d314d4f6b994cd86caa6e65d787d38dbccce58da015909fac5f2c551c1b6d
BLAKE2b-256 checksum
How to use checksums
c1217d6c57095073b396ea694ffb7f28c5080124d9ebb21aa801fa83a0be9b6b
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.0-py3-none-macosx_11_0_arm64.whl

Download URL hopper_cli-1.3.0-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
019abb36ea25f33aa62ebd778fe468bd3f50411717dbda9bfb4edf46014f9a58
BLAKE2b-256 checksum
How to use checksums
ca93b288e7cd830e105564356625412de93005ddf7be7931a3db74a2e0e3d77e
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.0-py3-none-macosx_10_9_x86_64.whl

Download URL hopper_cli-1.3.0-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
2491a0f25fdb711a52394ae31cf4f2747bacb5b2eface6e168f925591a1a53c8
BLAKE2b-256 checksum
How to use checksums
941aff53986609321750ebd0a6c798111deb08d674b72c12121f20edc0778e31
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.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.

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.

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