zord
Zord is a small, dependency-free task runner where a task is a regular Python function.
It's meant for Python projects because they already depend on Python, and it's primarily meant for me. I believe declarative task runners just (foreshadowing) cannot do everything I want them to, like cleaning up a bunch of artifacts in a cross-platform way.
I could use a justfile and shell out, but then it's no longer cross-platform. I
could use justfile's [script], but then I might as well just write a Python
script and call it directly instead.
poethepoet and tox, being declarative, suffer from much of the same issues.
Then there's nox, where you do write tasks in Python, but it's a full-blown
environment manager and more, and I'd have to go out of my way to stop it from
doing a bunch of extra work.
Table Of Contents
Installation
Zord requires Python 3.14 or newer because it uses
t-strings.
Add it to your project's development dependencies with
uv:
uv add --dev zord
You can then run it with uv run zord, or uv run python -m zord.
The examples below use zord for brevity.
Usage
Create a tasks.py file in your project root and decorate your functions with
@task:
from zord import Cmd, task
@task(default=True)
def lint() -> None:
"""Check the code with Ruff."""
Cmd("ruff").args(t"check").run()
@task(default=True)
def test() -> None:
"""Run the test suite."""
Cmd("pytest").run()
@task
def ci() -> None:
"""Run all checks."""
lint()
test()
Run Zord from the directory containing tasks.py:
zord # List the available tasks
zord lint # Run a task
zord lint test # Run several tasks in order
zord ci # Call other tasks from a task
zord --default # Run tasks marked default=True
zord --help # Show command-line help
The function name becomes the task name, with underscores replaced by hyphens.
For example, build_docs becomes build-docs. The docstring becomes its
description. You can override either with @task(name="...", description="...").
When you pass several task names, Zord checks that all of them exist before running anything. Tasks run in the order you pass them, stopping at the first failure.
--default runs the tasks marked default=True in the order they appear in
tasks.py, using their parameter defaults.
Task arguments
Zord uses your function's signature to build its command-line interface. Positional parameters become positional arguments, and keyword-only parameters become options:
from zord import task
@task
def greet(name: str = "World", *, count: int = 1, loud: bool = False) -> None:
"""Greet someone a number of times."""
message = f"Hello, {name}!"
for _ in range(count):
print(message.upper() if loud else message)
Put -- between the task name and its arguments:
zord greet -- Alice
zord greet -- Bob --count 3
zord greet -- Charlie --count 2 --loud
zord greet -- Dana --no-loud
zord greet -- --help
Without the separator, Alice would be treated as another task name. Arguments
can only be passed to one task at a time. Underscores in option names become
hyphens too, so output_dir becomes --output-dir.
Supported types
Every parameter except *args needs a default value. Parameters without a type
annotation are parsed as strings.
| Annotation | Behavior |
|---|---|
str, int, float, Path |
Convert the argument to the given type. |
bool |
Accept --flag and --no-flag. Must be keyword-only. |
Literal["dev", "prod"] |
Accept one of the listed strings. |
Literal[1, 2] |
Accept one of the listed integers. |
I'll add more types here if I find real use cases.
Variable arguments
Use *args to accept any number of positional values. You can also have
keyword-only parameters after it:
from pathlib import Path
from zord import task
@task
def paths(*paths: Path, absolute: bool = False) -> None:
"""Print the given paths."""
for path in paths:
print(path.absolute() if absolute else path)
zord paths -- src tests
zord paths -- --absolute src tests
Options can appear before or after the positional values. *args can't be
combined with other positional parameters, and **kwargs isn't supported.
Running commands
Cmd lets you build and reuse external commands:
from zord import Cmd
uv = Cmd("uv").args(t"run")
uv.args(t"ruff check").run()
uv.args(t"pytest").run()
.run() waits for the command to finish and uses the parent's stdin, stdout, and
stderr. A nonzero exit status raises subprocess.CalledProcessError by default.
Arguments and t-strings
Pass the executable to Cmd, then add arguments with .args(). Each call accepts
either one t-string or any number of strings and paths:
from pathlib import Path
from zord import Cmd
paths = [Path("first file.py"), Path("second file.py")]
Cmd("git").args("add", *paths).run()
Cmd("git").args(t'commit -m "release build"').run()
destination = Path("build files")
Cmd("uv").args(t"build --out-dir={destination}").run()
Notice how I never quoted {destination}.
Thanks to t-strings, we can automatically quote interpolated values appropriately.
This was inspired by PEP 787 – Safer subprocess usage using t-strings.
To pass a collection as separate arguments, unpack it with *:
flags = ["-q", "-k", "slow tests"]
Cmd("pytest").args(*flags).run()
A regular string is passed as is, which is important for filenames with spaces.
add = Cmd("git").args("add")
add.args("my file.py").run() # git add "my file.py"
Executables
Pass a program name to look it up on the current PATH when the command is
created, as in Cmd("git"). You can also pass an absolute executable path:
Relative executable paths such as ./tool or bin/tool aren't accepted.
This is because their resolution is ambiguous. Should it be relative to
tasks.py or relative to your cwd?
Configuration and reuse
Cmd is an immutable object, so every method returns a new instance:
from zord import Cmd
base = Cmd("pytest").env({"CI": "1", "DEBUG": "0"})
debug = base.env({"DEBUG": "1"}).args("-s")
base.run() # DEBUG=0
debug.run() # DEBUG=1, with -s
Output and exit status
.run() returns a Run with .executable, .args (excluding the executable),
and .returncode. To handle a nonzero exit status yourself, turn off checking:
from zord import Cmd
result = Cmd("git").args(t"diff --quiet").check(False).run()
print(result.returncode)
.capture() captures stdout and stderr as UTF-8 text, returning a Capture
with the same fields plus .stdout and .stderr:
result = Cmd("git").args(t"status --short").capture()
print(result.stdout)
print(result.stderr)
commit = Cmd("git").args(t"rev-parse HEAD").stdout()
.stdout() returns captured stdout with leading and trailing whitespace stripped.
Use .capture().stdout if you need to preserve whitespace.
Errors and limitations
Zord loads tasks.py from the current directory and runs tasks in the same
process and environment. It doesn't search parent directories or create an
environment for you.
Task functions must be synchronous. Async functions, generators, and required parameters aren't supported. Return values are ignored.
| Exit code | Meaning |
|---|---|
0 |
Success. |
1 |
A task failed, or there was an error loading or defining tasks. |
2 |
Invalid command, missing task file, unknown task, or no default tasks. |
130 |
Interrupted with Ctrl-C. |
License
Distributed under the Mozilla Public License 2.0. See LICENSE for more information.
Metadata
Release files for zord 0.0.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 |
|---|---|---|---|---|
| zord-0.0.2.tar.gz | 39.4 kB | With provenance | Details for zord-0.0.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| zord-0.0.2-py3-none-any.whl | Python 3 | none | any | Details for zord-0.0.2-py3-none-any.whl |
Total release size: 65.1 kB
Release files / zord-0.0.2.tar.gz
| Download URL | zord-0.0.2.tar.gz |
|---|---|
| Size | 39.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c1390af428957482887ef222b53af04178b1510b9126d4639cf9c2dce7b7e336
|
|
BLAKE2b-256 checksum How to use checksums |
16f1650189dd7b178b4a230d28f30b3736a8d89fec84e1d2a0799a7bfb6a1b40
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logRelease files / zord-0.0.2-py3-none-any.whl
| Download URL | zord-0.0.2-py3-none-any.whl |
|---|---|
| Size | 25.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dcb5d5e08f40e676022afda8016c86f8eb48dba9ebbe3d279fa98011a73a688f
|
|
BLAKE2b-256 checksum How to use checksums |
1357d048b6c1acd57aa205a7d3266ab54efa66850c98bd8ed34446d4244e6ca4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logSecurity for zord 0.0.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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for zord-0.0.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logA 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.