Skip to main content

CLI

zb is the DAGZ command-line tool. It manages the local daemon and inspects test results: jobs, tests, spans, coverage, and logs.

Install​

curl -LsSf https://dagz.run/install.sh | bash

Daemon and environments​

zb env​

List available environments. DAGZ maintains one env per workspace under ~/.dagz/<env>.env/; the default local is used unless you've switched.

zb env

zb env local up / down​

Manage the local daemon (embedded ClickHouse, KV store, and web server). The daemon is shared across repos. Start it once and run pytest --dagz in any project.

zb env local up                  # start in foreground
zb env local up --bg             # daemonize; logs to ~/.dagz/local.env/web/web.log
zb env local up --restart --bg   # stop a running daemon first, then start fresh
zb env local down                # stop the daemon

The dashboard runs at http://localhost:29111.

zb env use <env-id>​

Switch the current environment (e.g. to a deployed team server).

zb env login​

Authenticate the CLI with a remote DAGZ server.

Running tests​

zb select-tests​

Preview test selection for the current working tree.

zb select-tests                    # list selected tests
zb select-tests --trace            # show why each test was selected

Inspecting jobs​

zb jobs​

List recent jobs with status, duration, and selected/skipped counts.

zb jobs                # last 10 jobs
zb jobs --last 50      # last 50

zb logs <job>​

Print the captured stdout/stderr from a finished job.

zb logs j10                    # the 10th job today
zb logs j1201.1                # December 1st's first job
zb logs j10 --group-by-worker  # group output per worker

For the daemon's own log, tail ~/.dagz/local.env/web/web.log directly.

Inspecting spans​

A span is a single execution flow inside a job (a test, a fixture, a subprocess, etc.). See Concepts: Spans.

zb spans <job>...​

Tree of spans for one or more jobs, sorted by start time (default), elapsed time, CPU, wait, or memory.

zb spans j10
zb spans j10 j11 --sort elapsed

zb span-deps --span <name>​

Show the dependencies discovered by a single span. Useful for understanding why a test was selected, or for debugging missing/spurious dependencies.

zb span-deps --span 'test:tests/test_foo.py::test_bar'
zb span-deps --span 'test:tests/test_foo.py::test_bar' --job j10

zb span-logs <span>​

Captured stdout/stderr from a single span across recent runs. Pulls the last N occurrences of that span (across jobs) so you can compare its log output over time.

zb span-logs 'test:tests/test_foo.py::test_bar'
zb span-logs 'test:tests/test_foo.py::test_bar' -n 20   # last 20 occurrences
zb span-logs 'test:tests/test_foo.py::test_bar' --no-logs  # summary only

The span identifier is <type>:<name>, e.g. test:path/to/test.py::TestClass::test_method. If you omit the type prefix, test: is assumed.

Coverage​

zb cov <path>...​

Annotate source files with hit/miss markers in the terminal.

zb cov src/dagz/scheduler.py
zb cov src/dagz/                  # whole directory
zb cov src/foo.py --job j10       # coverage from a specific job

zb export-cov​

Export coverage as a standard report file. See Coverage → Exporting coverage for details.

zb export-cov --format pycoverage          # .coverage (SQLite, coverage.py-compatible)
zb export-cov --format xml                 # coverage.xml (Cobertura)
zb export-cov --format xml -j j10 -o out.xml

Misc​

zb version​

Print the embedded zb version.

Daemon config​

On first start the daemon writes ~/.dagz/local.env/daemon.yaml. Edit it and run zb env local up --restart --bg to apply. See Running on Mac with Docker for an example.