Skip to main content

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)

Source distribution for zord 0.0.2
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)

Table of built distributions (wheels) for zord 0.0.2
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

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.

Release history Release notifications | RSS feed

This release

0.0.2 This release

2 release files Full provenance

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