Skip to main content

Codehood CLI

This is the command line interface for Codehood. It can be used by instructors or students to manage their Codehood projects and assignments.

Installation

uv tool install codehood-cli    # or: pipx install codehood-cli

It installs two commands, codehood and its short alias ch. Python 3.13 or later is required.

To work on the CLI itself, clone the Codehood repository with mdq checked out next to it:

git clone https://github.com/fabiommendes/codehood.git
git clone https://github.com/fabiommendes/mdq-spec.git mdq
uv tool install --editable codehood/cli

For instructors

In Codehood, you manage your course in a local repository, possibly under version control, and then push changes to the Codehood server. Your local files are the source of truth, and so you must init the course repository before anything.

codehood init

It asks for the discipline, your username, the edition and the server, and creates the following folder structure in your current working directory:

├── .local/codehood/
├── questions/
│   └── example.md
├── exams/
│   └── example.md
├── resources/
├── repositories/
├── .gitignore
├── codehood.toml
├── calendar.md
└── README.md

Then log in from inside the repository. codehood login asks for your password and stores a CLI key for the server in ~/.codehood/credentials.toml, never in codehood.toml:

codehood login

For CI and scripts, set CODEHOOD_TOKEN to a CLI key instead. When it is set (and not empty) it is used for every server, and credentials.toml is not read. codehood login and codehood logout still edit the file, and say that the variable overrides it.

We manage the course by editing or adding files in the local repository and then pushing changes to the Codehood server using a simple command:

codehood push

Two servers, one repository

--config (-c) reads another file in place of codehood.toml, so one repository can sync with two servers. Keep codehood.toml for one and, say, codehood.prod.toml (same [course], another [server] url) for the other:

codehood -c codehood.prod.toml login
codehood -c codehood.prod.toml push

The option goes before the command. CODEHOOD_CONFIG=codehood.prod.toml does the same, and --config wins when both are set. Only the config file changes: the repository root is still the current directory (or the push path), and a relative --config is relative to the current directory. Tokens are stored per server URL, so each config uses its own. codehood -c file init writes the config to file. To use a second identity on the same server, set CODEHOOD_TOKEN.

When the server changed

codehood push sends only what you changed locally. It compares your files, a record of the last sync and the server, and never overwrites something that changed on the server since. It lists those entities and leaves them alone:

  • pull: something was written on the server by anything but a CLI, such as an edit or a creation on the web or through the REST API. Nothing is written in your files yet, and the server's version stays.
  • conflict: you and the server both changed it. The push exits with code 1. codehood push --ours resource/intro sends your version (<kind>/<key>, globs allowed, repeatable).
  • other cli: another checkout pushed it. Run git pull first. If the file no longer exists anywhere, --ours <kind>/<key> deletes it from the server (or sends your copy, if you still have it).

The record of the last sync lives in .local/codehood/. Push creates it, with its own .gitignore, when it is missing, so Git never lists it, even in a fresh clone. It is safe to delete: the next push rebuilds it without writing anything for what matches the server (or carries the hash it last sent). What differs and has no record is a conflict, or a pull when only the server changed it. An entity that exists only on the server and carries a rev shows as other cli; --ours <kind>/<key> deletes it.

Keeping files out of a push

Files you do not want on the server (drafts, questions of a type the server does not support yet) can be excluded in codehood.toml:

[push]
exclude = [
    "questions/wip",            # a directory: everything under it
    "questions/**/draft-*.md",  # ** crosses directories
    "resources/private.md",
]

Patterns are relative to the repository root and gitignore-like: * and ? stay inside one path segment, ** matches any number of directories, and there is no ! negation. They apply to files under questions/ and resources/. An excluded file is not read, so it may even be invalid. What the server already holds for it is neither updated nor deleted. codehood push lists excluded files and does not fail because of them. __pycache__/, *.pyc, elm-stuff/ and node_modules/ are always excluded, at any depth.

.codehoodignore at the root takes gitignore syntax (with !). A match under questions/, resources/ or exams/ is treated like an exclude pattern: not pushed, and the server copy is kept. codehood init does not create the file.

codehood push reports "not pushed (no handler)" only for files under questions/, resources/ and exams/ that it did not read. Anything else (extra files at the root, folders such as solutions/, another tool's config) is never read and never reported. The report follows git's rules in a git repository (.gitignore at any level, .git/info/exclude, core.excludesFile), and the root .gitignore only otherwise.

Linking resources from a lesson

A markdown link in a lesson of calendar.md to a file under resources/, such as [Slides](resources/w03/recursion.pdf), attaches that resource to the lesson's event. On push, the link in the published lesson points to the resource's page on the server; your local calendar.md is not changed. A resource can belong to at most one lesson, and a link to a file that is not under resources/ is an error. Push writes the calendar before the resources.

Repositories

Each folder directly under repositories/ is a git repository of the course, and the folder name is its slug (lowercase letters, digits, ., _ and -). codehood push uploads the files and makes one commit per change, and students clone it from the course page:

codehood push -m "Fix the lab 1 test"   # -m sets the commit message
  • .gitignore files inside a repository folder apply at every level, ! included, and are published with the repository. The .gitignore at the course root does not apply. .git directories are never published.
  • Symlinks, files loose in repositories/, files over 16 MB and folders with no file to publish are errors. The executable bit is kept (100755); on Windows every file is 100644.
  • [push] exclude patterns also work under repositories/<slug>/.
  • A repository whose folder is gone stays on the server, because deleting it breaks its clone URL and history. codehood push --drop-repositories deletes it.
  • A link in a lesson of calendar.md to repositories/<slug> or repositories/<slug>/<path> ties the repository to that lesson. The link in the published lesson points to the repository page on the server. A link to a repository or path that does not exist is an error.

A student who commits in their clone should update with git pull --no-rebase: recent git versions refuse a plain git pull when the local and the server's branches diverge.

Assignments with a repository

An assignment is one Markdown file, assignments/<slug>.md: the front matter sets the rules and the body is the statement students read.

---
title: Calculator lab
due: 2026-12-10T23:59:00-03:00   # deadline; needs a time of day
closes: 2026-12-12 23:59          # last push the server takes (optional)
opens: 2026-12-01                 # visible from here (optional, a date is enough)
team:
  min: 2                          # default 1; max defaults to min
  max: 3                          # at most 10
  lock: 2026-12-05 12:00          # teams frozen from here (optional)
template: lab-calculadora         # a folder of repositories/ (optional)
restrictions:
  maxRepoBytes: 10mb              # a number of bytes or 10kb, 10mb, 1gb (powers of 1024)
  maxFileBytes: 2mb
  deny: ["*.exe", "node_modules/**"]
  require: [README.md]
checkpoints:                      # intermediate dates (optional)
  - slug: parser
    title: Parser working
    at: 2026-12-05 12:00          # needs a time; after opens, before due
---

# Calculator

Build a calculator. Push to your team's repository before the deadline.
  • Dates are written as in exam files. A time without an offset is UTC. due, closes and team.lock refuse a date without a time, since 2026-12-20 would silently mean midnight UTC.
  • checkpoints lists intermediate dates, each with slug, title and at (all required). Slugs are unique within the assignment. A checkpoint removed from the file is removed from the server on the next push.
  • No team means an individual assignment (min = max = 1).
  • A file whose name starts with _, a file that is not .md and anything in a subfolder is not pushed.
  • A problem in one file (unknown key, bad date, min above max, due after closes, a template that is not a folder of repositories/, a name that is not a slug) fails that file and the push, and leaves the assignment on the server as it is.
  • Repositories are pushed before assignments. Like everything else, an assignment is synced in three ways: a second push of an unchanged file writes nothing.
  • An assignment whose file is gone stays on the server. codehood push --drop-assignments deletes it; when it has teams, the push shows how many and asks before deleting them and their repositories too. Without a terminal, or on any answer but y, it stays.

codehood assignment works with the teams:

codehood assignment status lab                        # teams, deliveries, notes
codehood assignment clone lab                         # submissions/lab/<team>/
codehood assignment clone lab --late --dest ~/grading # the late delivery instead
codehood assignment clone lab --checkpoint parser     # each team's commit at that checkpoint
codehood assignment extend lab "Team A" "2026-12-12 18:00"
codehood assignment move lab bob "Team A"

clone makes one git repository per team in <dest>/<slug>/<team>/ (a sanitized team name, or the username for an individual assignment) and parks it on the delivered commit with no local branch. Run it again to update. A folder whose tracked files you edited is left alone with a warning. Teams with no delivery get no folder and are listed at the end. With --checkpoint <slug>, each folder is parked on the commit the team had pushed by that checkpoint; teams with none are skipped and listed. It cannot be combined with --late. status shows one column per checkpoint with the short commit. Your API key goes to git through its environment only; it is never written to .git/config or the remote URL. Add submissions/ to your course .gitignore.

extend and move take the team by name or, when no name matches, by the username of a member.

Final grades

Codehood does not compute a course's final grade. You compute it on your machine and push the result as grade columns, which the Grades tab shows beside the exams. Declare the columns in codehood.toml, in the order they should appear:

[[grades.column]]
slug = "assignments"
title = "Assignments"

[[grades.column]]
slug = "final"
title = "Final grade"
kind = "label"        # "number" is the default

Scores you keep outside Codehood go in grades.csv, one row per student. The header of the first column says how students are identified: school_id, username, github or email.

school_id,assignments
190012345,82.5
190054321,60

A column whose slug is a header of grades.csv needs nothing else. To compute one, write a grade function in grades.py. It is called once per enrolled student and returns that student's value for each column it computes:

from codehood.grades import Student

def grade(student: Student) -> dict[str, float | str | None]:
    midterm = student.exams["midterm"].score or 0.0   # 0 to 100, or None
    total = 0.6 * midterm + 0.4 * (student.scores["assignments"] or 0.0)
    return {"final": "pass" if total >= 50 else "fail"}

codehood grades prints the resulting table without sending anything, and codehood push sends it. A pushed column stays hidden from students until you release it on the Grades tab.

grades.py runs inside the CLI, so it can import the standard library and whatever is installed beside the CLI. To use another package, install the CLI with it: uv tool install --editable codehood/cli --with pandas.

Releasing exam grades

Students see the grades of an exam only after you release them:

codehood exam release midterm

The server refuses while the exam is still open, while answers wait for a grade, or while a student exception keeps a personal window open, and the command says which and how many. Releasing an exam twice changes nothing.

Question slugs in exams

A student sees a question's slug while the exam is open, so the slug must not give away the answer or the trap. The CLI never reads exam questions for students: the server hands them out only to a student who holds a grant from their own attempt.

For students

TBD!

Contributing

The CLI is developed in the cli/ directory of the Codehood repository. Open issues and pull requests there. See its CONTRIBUTING.md.

License

MIT.

Metadata

Release files for codehood-cli 0.7.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for codehood-cli 0.7.1
File Size Uploaded Provenance Actions
codehood_cli-0.7.1.tar.gz 169.9 kB Without provenance Details for codehood_cli-0.7.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for codehood-cli 0.7.1
File Interpreter ABI Platform Actions
codehood_cli-0.7.1-py3-none-any.whl Python 3 none any Details for codehood_cli-0.7.1-py3-none-any.whl

Total release size: 367.9 kB

Release files / codehood_cli-0.7.1.tar.gz

Download URL codehood_cli-0.7.1.tar.gz
Size 169.9 kB
Tags Source
SHA-256 checksum
How to use checksums
ebb8f55657377f90f4eb65def9d9cd1132d60a7afaa0a249a5852692259bdeed
BLAKE2b-256 checksum
How to use checksums
902728821431e1a69bf181a521f294a108fa541ab5cc9d1c1766d1bee75afb24
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / codehood_cli-0.7.1-py3-none-any.whl

Download URL codehood_cli-0.7.1-py3-none-any.whl
Size 198.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fdb572f33eb050f3c23e400f423a93b15424972d794ac3e42daf0d069e7ff604
BLAKE2b-256 checksum
How to use checksums
bc41b01db1ab56f7cb0387c1180879e62c9d4357818e778d348c968753925958
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for codehood-cli 0.7.1

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