Skip to main content

Existing project

DAGZ is already integrated into the project you're working on (look for a .dagz/ directory at the project root). Here's how to start using it.

If your project pins dagz in requirements.txt or similar, your usual install step already covers this.

1. Local environment​

DAGZ can be managed with the zb command-line tool. It runs the local daemon (which stores execution baselines and serves the dashboard) and provides commands to inspect jobs, tests, and coverage.

Install the binary:

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

Start the local daemon in the background:

zb daemon up --bg

The daemon binds to loopback and to the Docker bridge by default, so containers on the default bridge reach it without --network=host. See the daemon config reference for ports, alternative bridge addresses, and extra listen interfaces.

2. Login to your team's DAGZ server​

cd /.../your-project
zb login

3. Inspect latest results​

zb -r tells zb to use your Project's central DAGZ server (from public_url).

zb -r jobs [-l LAST_JOBS]                  # list recent jobs
zb -r logs jMMDDD.nnn                      # view a job's logs
zb -r spans jMMDDD.nnn [jMMDDD.nnn...]     # view a job's spans, optionally compare to other jobs
zb -r span-logs <test-name>                # Generate rich context for a span/test, useful as agent prompt

4. Run tests locally​

On Linux:​

pytest --dagz

On your first run, DAGZ records a baseline of which tests cover which code. On subsequent runs, only the tests affected by your change are selected.

Useful flags:

  • --dagz-debug: detailed logs from the plugin and runtime.
  • --dagz-workers=N: number of parallel workers. The default is based on your hardware.

The full list is in pytest options.

5. Make a change and run again​

pytest --dagz

Preview which tests would be selected without running them:

zb select-tests

To see why each test was selected, add --trace:

zb select-tests --trace

6. Open the dashboard​

Visit your team's DAGZ URL, or http://localhost:29111 if you're using the local environment. Each job page shows selected tests, skipped tests, failures, timing, and selection traces.

Platform notes​

  • Linux: fully supported.
  • macOS: the pytest plugin is unsupported and may not work correctly. Run tests in a Linux Docker container against the daemon on your Mac. The New project page shows the Docker setup.
  • Windows: not supported.