--- kind: guide zz: "0.4.0" updated: 2026-10-09 state: draft rules: https://zriz.io/llms.txt --- # 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. zriz runs end-to-end tests of your own app. A test is a [pipeline](https://zriz.io/docs/words.md#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](https://zriz.io/docs/limits.md#runs-a-day) gives the free tier. ## Before you start {#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 {#install} ### Do ```sh 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 ```text zz: checksum ok zz: installed /zz Next: 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 {#log-in} ### Do Your user must approve the login in a browser tab. The command opens the tab. Tell your user this sentence: ```text 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. ```sh ~/.local/bin/zz login ``` ### Why The login gives this computer an API key of your [org](https://zriz.io/docs/words.md#org). ### You should see ```text {"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 {#init} ### 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`. ```sh ~/.local/bin/zz init --url http://localhost:3000 ``` ### Why The command makes the [project](https://zriz.io/docs/words.md#project) folder `.zriz` with the sample pipeline `hello`. `hello` does one GET on your app and expects status 200. ### You should see ```text {"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 {#run} ### Do Start your app. A [run](https://zriz.io/docs/words.md#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. ```sh ~/.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 ```text "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](https://zriz.io/docs/words.md#step). - `runner-unavailable`: No runner is connected. Do `zz runners init --start`. - `runner-start-failed`: [A runner on this machine](https://zriz.io/docs/runner.md#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?](https://zriz.io/docs/limits.md#at-the-limit) ## What you get {#what-you-get} ```text 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 ` 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 {#the-loop} 1. Write or change a pipeline file. 2. `zz run `, 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 ` shows the failed step. ## Upgrade from zz 0.3.1 {#upgrade} 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 {#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 --help` gives flags and examples as data. - A plain-text version of this site is at [/llms.txt](/llms.txt). ## Next {#next} - [Write your first test](https://zriz.io/docs/first-test.md): one call of your own service and one check. - [Pipelines](https://zriz.io/docs/pipelines.md): steps, checks, placeholders, secrets. - [Runner](https://zriz.io/docs/runner.md): run the same pipelines inside your own network. - [Security](https://zriz.io/docs/security.md): what leaves your machine and what never does.