zriz quick start

Install zz, log in, make a project, and run the sample test in four commands. The work is done when the run has status pass. The commands need zz 0.4.0 or later.

Draft. Guide · zz 0.4.0 or later · Updated 2026-10-09 · Plain text for agents: /docs.md

zriz runs end-to-end tests of your own app. A test is a pipeline file in your repo. It calls your HTTP API, checks your database, and says pass or fail.

The CLI is zz. zriz tests your real app, end to end, before your customers do.

zriz is in open beta. The page Limits gives the free tier.

Before you start

• The computer has macOS or Linux: uname -s
• curl is installed: curl --version
• The current folder is the folder of your service, not the home folder: test "$PWD" != "$HOME"

1. Install zz

Do

curl -fsSL https://zriz.io/install | sh

Why

The script puts zz in ~/.local/bin. One install is sufficient for the computer.

You should see

zz: checksum ok
zz: installed <dir>/zz
Next: <command> login

If not

• curl is required: Install curl. Then do the command again.
• tar is required: Install tar. Then do the command again.
• Add zz to your PATH: This is not an error. The next commands use the full path.

2. Log in

Do

Your user must approve the login in a browser tab. The command opens the tab. Tell your user this sentence:

A zriz tab opened. Sign in if asked, then click Yes, connect.

Your user signs in with GitHub, Google, or email and password. A person with no account signs up in the same tab.

Note: On a machine with no browser, do zz login --no-wait first. Show verify-url and user-code of its reply to your user.

Note: zz login --add adds a login for a second org. zz switch lists the logins and changes the current login.

~/.local/bin/zz login

Why

The login gives this computer an API key of your org.

You should see

{"ok":true,"command":"login",

If not

• login-pending: Your user did not approve in 90 seconds. Do the command again. It waits for the same login.
• login expired: Do the command again. It starts a new login.

3. Make the project

Do

Replace http://localhost:3000 with the base URL of your app, if it is different.

zz looks for a health path that answers 200. If you know the path, add --path /your/health/path.

~/.local/bin/zz init --url http://localhost:3000

Why

The command makes the project folder .zriz with the sample pipeline hello. hello does one GET on your app and expects status 200.

You should see

{"ok":true,"command":"init",

If not

• must start with http:// or https://: Give the full base URL, with the scheme.
• the home folder cannot be a zriz project: Go to the folder of your service. Then do the command again.
• no path answered 200: Start your app. Then set path of the action check in .zriz/resources/target.json to a path that answers 200.

4. Run the sample test

Do

Start your app.

A run needs a runner. The first command writes the files of a runner for this machine and starts it. Docker must be installed.

The second command takes a pipeline name, never a path.

~/.local/bin/zz runners init --start
~/.local/bin/zz run hello

Why

A run with status pass shows that the install, the login, and the project are correct.

You should see

"status":"pass"

If not

• not logged in: Do step 2 again.
• not a zriz project: Do step 3 again, in the folder of your service.
• "status":"fail": Your app did not answer 200. Do the command in hints of the reply. It shows the failed step.
• runner-unavailable: No runner is connected. Do zz runners init --start.
• runner-start-failed: A runner on this machine gives the fix for each step.
• too-many-runs: The org is at the limit of the free tier. Read What happens at the limit?

What you get

my-service/             the folder of your service
  .zriz/                the project folder
    project.json        the project name and the default environment
    environments/       values and secrets, one file per environment
    resources/          what a test may call: an HTTP app, a database
    pipelines/          the tests
    README.md           a short description for a person
    AGENTS.md           a short description for an agent
    .gitignore          keeps environments/local.json out of git

Commit .zriz with your code. environments/local.json belongs to one computer and is not committed.

After a clone, do zz init --url <url> one time, with the base URL of your service. It writes only that file.

Each service has its own project. zz finds .zriz from each sub-folder of your service.

The loop

1. Write or change a pipeline file.
2. zz run <name>, for example zz run hello. It checks the files first and says how to fix them, then runs them.
3. Done only when the answer is status pass. If it fails, zz runs <id> shows the failed step.

Upgrade from zz 0.3.1

zz 0.3.1 kept the project in zriz/. zz 0.4.0 keeps it in .zriz/. The hints of zz 0.4.0 give each step:

1. zz run zriz/pipelines/hello.json gives an error. Its hint is an mv command.
2. Do the mv command. zz run hello then works.
3. The reply warns about the sample name hello. Set name in .zriz/project.json to the name of your service.
4. Do zz init. It writes .gitignore and the new README.md and AGENTS.md.
5. Do git rm --cached .zriz/environments/local.json, if that file is in your repository.
6. In scripts, change each path to a pipeline name.

For AI agents

Each command of zz prints one JSON object. Its hints field names the next command.

zz never asks a question and never waits for input.

• zz alone shows where you are and the next command.
• zz guide prints one page on how to write a pipeline.
• zz <command> --help gives flags and examples as data.
• A plain-text version of this site is at /llms.txt.

Next

• Write your first test: one call of your own service and one check.
• Pipelines: steps, checks, placeholders, secrets.
• Runner: run the same pipelines inside your own network.
• Security: what leaves your machine and what never does.