ZEITLICHT
Back to overview

API and integrations

Use the zl command line

I want to …

… read and change this workspace's tasks from a terminal or a script with the zl command.

Before you start

  • You need Node.js 22 or newer and an API key of this workspace, see "Create and revoke API keys".
  • The key's permissions decide what zl may do. Read only reads. Read and write also changes tasks and fills in testing. Full access also deletes.
  • API keys need the Ultra plan of the Owner or Admin who creates them, and they are in beta.

Here's how

  1. Install it with npm install -g zeitlicht-cli, or run a single command with npx zeitlicht-cli.
  2. Save the key in a file, run zl auth login < key.txt, then delete the file. zl checks the key and keeps it in your system's keychain, or where there is none, in a file only you can read. In CI, set the environment variable ZEITLICHT_API_KEY instead.
  3. zl auth status shows the key's name, workspace, permissions, and end date. zl only ever shows the start of the key.
  4. zl boards lists the boards with their IDs, and zl board followed by a board ID lists its columns. zl members, zl tags, and zl topics list people, tags, and topics. With a key for selected boards, zl members shows no email addresses.
  5. zl tasks --assignee me --open lists your open tasks. Filter with --board, --column, --tester, --done, --since, and --query. --all loads every page.
  6. zl task show 3f2a9c1e shows one task, named by its short ID, its ID, or its link.
  7. Create a task with zl task create --title "Check the login" --board BOARD_ID and, if you like, --description-file notes.md, --assignee me, --tag TAG_ID, --due 2026-12-24, or --priority high. Change it with zl task update, move it with zl task move 3f2a9c1e --column COLUMN_ID, and delete it with zl task delete 3f2a9c1e --yes.
  8. Hand a task to testing with zl test request 3f2a9c1e --instructions-file TESTING.md --tester mia@example.com --move-to COLUMN_ID. zl test status 3f2a9c1e shows testers, verdicts, and bugs.
  9. There is more: zl comment add, zl checklist add, zl checklist check, zl bug report, zl bug status, zl link add, and zl attach for files of up to 10 MiB. As in the app, Zeitlicht takes the file type from the extension; blocked types such as .exe or .svg cannot be attached. zl task id-from reads a branch name or pull request title and prints the task ID in it. zl --help lists every command.
  10. Add --json to any command for output a script can read.
  11. zl auth logout forgets the stored key.

The result

zl reads and changes the tasks on the boards the key allows, as you. Every request shows up in the key's access log.

Common questions

Which exit codes does zl use?

0 done, 1 refused by the API, 2 wrong usage, 3 no key or the key was refused, 4 no connection. The error line names the reason, such as key-expired.

Can a script safely retry zl task create?

Yes. Add --idempotency-key with a value of your own, such as your CI run ID (up to 200 letters, digits, or _.:-). If the same command with the same key runs again within 24 hours, Zeitlicht returns the first task instead of creating a second one. While the first request still runs, a repeat gets 409 (idempotency-in-progress), for at most 60 seconds. The same key with different details gets 422.

Can zl talk to a test setup?

Yes. ZEITLICHT_API_URL points zl at another address. Plain HTTP works only for your own computer (localhost).

Where exactly is my key?

In the keychain of macOS, Windows, or Linux. Without one, in ~/.config/zeitlicht/credentials.json, which only you can read. zl warns when others could read that file. ZL_NO_KEYRING=1 skips the keychain.

Related topics