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/introsends your version (<kind>/<key>, globs allowed, repeatable).other cli: another checkout pushed it. Rungit pullfirst. 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
.gitignorefiles inside a repository folder apply at every level,!included, and are published with the repository. The.gitignoreat the course root does not apply..gitdirectories 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 is100644. [push] excludepatterns also work underrepositories/<slug>/.- A repository whose folder is gone stays on the server, because deleting it
breaks its clone URL and history.
codehood push --drop-repositoriesdeletes it. - A link in a lesson of
calendar.mdtorepositories/<slug>orrepositories/<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,closesandteam.lockrefuse a date without a time, since2026-12-20would silently mean midnight UTC. checkpointslists intermediate dates, each withslug,titleandat(all required). Slugs are unique within the assignment. A checkpoint removed from the file is removed from the server on the next push.- No
teammeans an individual assignment (min = max = 1). - A file whose name starts with
_, a file that is not.mdand anything in a subfolder is not pushed. - A problem in one file (unknown key, bad date,
minabovemax,dueaftercloses, atemplatethat is not a folder ofrepositories/, 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-assignmentsdeletes 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 buty, 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.