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.

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 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 logs Print the saved output of the most recent pull run.
hopper push [msg] Commit README changes, validate README syntax, push.
hopper commit <msg> Commit without pushing (recovery path).
hopper check Validate the README syntax in all student repositories.
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, 2 for ssh remotes)
  • Every pull reports local repos of students no longer assigned to you (they changed tutor or left the course). Those copies can still be pushed to and graded twice, so delete them with --prune, which shows a preview and asks for confirmation; --no-prune skips pruning.
  • Repos are synced concurrently, 4 at a time by default. When the instance's clone URL uses ssh, the default is 2: bursts of concurrent ssh handshakes can make the server reject some connections. Override with -j.
  • Per-repo failures are reported and skipped, and one bad repo does not abort the whole run. Repos that fail are retried once, serially, after the concurrent pass, since transient ssh failures usually succeed on a second try.
  • The final report lists every repo that still failed together with its error, and states that its local copy was NOT updated. For ssh authentication errors (Permission denied (publickey), Too many authentication failures) it adds a hint to check ssh-add -l and the key registration in your hopper profile.
  • Every run's full output is saved to a log file under the user cache dir, so a closed terminal does not lose a failure report. A failed run ends with Full output: <path> pointing at that file; inspect it later with hopper logs.
  • If the configured origin branch is missing but origin/main exists, hopper repairs the upstream automatically. Fresh clones with an invalid remote HEAD check out main; existing checkouts keep their local branch and changes.

logs

hopper logs        # print the saved output of the most recent pull run
hopper logs --path # print only the path to that file

Each hopper pull writes its full terminal output to pull-<timestamp>.log in the hopper logs directory under the user cache dir (~/.cache/hopper/logs/ on Linux, ~/Library/Caches/hopper/logs/ on macOS). The file starts with a header (command line, timestamp, profile, course, exit status) followed by the output exactly as it appeared in the terminal. Only the 5 most recent logs are kept; older ones are deleted automatically. The command does not touch the server, so it also works offline.

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 syntax is invalid
hopper commit "WIP grading"     # commit without pushing (recovery path)
hopper commit --allow-invalid "WIP grading"

Before committing or pushing, hopper validates each staged README against the README syntax contract (see docs/build.md in the orchestration repo):

  • The first line reads # <name> (X / Y) with exactly one points entry, because orchestration records the grade from that line alone. A second X / Y pattern in the heading (for example a title like 3/4 before the points) would silently grade the wrong number and is rejected.
  • Points are written with spaces around the slash: (X / Y), not (X/Y).
  • Task and subtask headings carry a well-formed trailing (X / Y) points entry.
  • All hopper region markers (tutor regions, task boxes, build region) are intact, task box keys are valid and unique, and the build region comes last.

Invalid commits and 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.

check

hopper check    # validate <exercise>/README.md in every student repo

Runs the same validation as push and commit, but on every README in the working tree, without staging or committing anything. Use it to find broken headings or markers across all repos at once; the command exits non-zero when it finds problems.

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, logs, 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 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:

  • 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.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 hopper-cli 1.4.0
File Size Uploaded Provenance Actions
hopper_cli-1.4.0.tar.gz 19.3 kB Without provenance Details for hopper_cli-1.4.0.tar.gz

Built distributions (wheels)

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

Total release size: 75.4 MB

Release files / hopper_cli-1.4.0.tar.gz

Download URL hopper_cli-1.4.0.tar.gz
Size 19.3 kB
Tags Source
SHA-256 checksum
How to use checksums
832a92ffd36e09a19434fb313276d5510c651703d1d7ecb734aa31373a166f4a
BLAKE2b-256 checksum
How to use checksums
4a650df5ca863e0f59923a42a63b9c1260ddbf8ef95c2abda81ca0fa38f6af2e
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.4.0-py3-none-win_arm64.whl

Download URL hopper_cli-1.4.0-py3-none-win_arm64.whl
Size 15.0 MB
Tags Python 3 Windows ARM64
SHA-256 checksum
How to use checksums
214f7be320112446e21b45917c792e1ecbb636c2db2978bba52ff18be913191a
BLAKE2b-256 checksum
How to use checksums
bf580efa62a06ffb3fc4851fc0d874793d03d61af8e0c7c2924958d2253b94b5
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.4.0-py3-none-win_amd64.whl

Download URL hopper_cli-1.4.0-py3-none-win_amd64.whl
Size 15.7 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
ca8b09d8842263bd830f21cd1b8bfd47277bdb8e316c281bd85a8a38632b16c2
BLAKE2b-256 checksum
How to use checksums
4d9288f6adce6806bebd3fd32394b089268d05d11a0f6ea3fc7da28f55c750ec
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.4.0-py3-none-manylinux2014_x86_64.whl

Download URL hopper_cli-1.4.0-py3-none-manylinux2014_x86_64.whl
Size 7.8 MB
Tags Linux glibc 2.17+ x86-64 Python 3
SHA-256 checksum
How to use checksums
d2a905980f16a7b3a33e116f7b92d497ccfc3f987fed243a5d0b22917d165605
BLAKE2b-256 checksum
How to use checksums
7387c56901a55a3f79fb9ae5cfdfc177dd9935a827f8588ace634f2ca2b1e871
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.4.0-py3-none-manylinux2014_aarch64.whl

Download URL hopper_cli-1.4.0-py3-none-manylinux2014_aarch64.whl
Size 14.3 MB
Tags Linux glibc 2.17+ ARM64 Python 3
SHA-256 checksum
How to use checksums
aa1b59d3983a11fcb0b9b3256e09db08b3095ac608e41d8a3f581f4613bc0d9e
BLAKE2b-256 checksum
How to use checksums
d04677b0a884f1e7c685fe6596ee7456f1e192dd042ab076ecd20b214981fae9
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.4.0-py3-none-macosx_11_0_arm64.whl

Download URL hopper_cli-1.4.0-py3-none-macosx_11_0_arm64.whl
Size 14.6 MB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
75dfc6f6f5189d4cb030b3edaf3d83f1ed8ba451163b941636836effef504f1d
BLAKE2b-256 checksum
How to use checksums
0513a6bb8bc5b1736f229e798e43e415a68a233812366e1b83f7e252e7284c3e
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.4.0-py3-none-macosx_10_9_x86_64.whl

Download URL hopper_cli-1.4.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
c083c38460b39d3624467ea766f6f5249449638568062a4a2476a00cbf610920
BLAKE2b-256 checksum
How to use checksums
873bd041eedc31745a7afda7894a2582ffa3cd27b3a62123c14f8d67369f3ef8
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.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.

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