API und Integrationen

Die Kommandozeile zl nutzen

Q: Welche Exit-Codes nutzt zl?

0 erledigt, 1 von der API abgelehnt, 2 falsch aufgerufen, 3 kein Schlüssel oder Schlüssel abgelehnt, 4 keine Verbindung. Die Fehlerzeile nennt den Grund, etwa key-expired.

Q: Kann ein Skript zl task create gefahrlos wiederholen?

Ja. Gib --idempotency-key mit einem eigenen Wert an, etwa der Run-ID deines CI-Jobs (bis zu 200 Buchstaben, Ziffern oder _.:-). Läuft derselbe Befehl mit demselben Wert innerhalb von 24 Stunden noch einmal, gibt Zeitlicht die erste Aufgabe zurück, statt eine zweite anzulegen. Solange die erste Anfrage noch läuft, bekommt eine Wiederholung 409 (idempotency-in-progress), höchstens 60 Sekunden lang. Derselbe Wert mit anderen Angaben bekommt 422.

Q: Kann zl mit einer Testumgebung sprechen?

Ja. ZEITLICHT_API_URL lenkt zl an eine andere Adresse. Unverschlüsseltes HTTP geht nur für deinen eigenen Rechner (localhost).

Q: Wo genau liegt mein Schlüssel?

Im Schlüsselbund von macOS, Windows oder Linux. Ohne Schlüsselbund in ~/.config/zeitlicht/credentials.json, die nur du lesen kannst. zl warnt, wenn andere die Datei lesen könnten. ZL_NO_KEYRING=1 überspringt den Schlüsselbund.

Ich möchte …

… die Aufgaben dieses Arbeitsbereichs mit dem Befehl zl aus einem Terminal oder Skript lesen und ändern.

Bevor du startest

Du brauchst Node.js 22 oder neuer und einen API-Schlüssel dieses Arbeitsbereichs, siehe „API-Schlüssel erstellen und widerrufen“.
Die Berechtigungen des Schlüssels bestimmen, was zl darf. Nur lesen liest. Lesen und schreiben ändert außerdem Aufgaben und füllt das Testmodul. Vollzugriff löscht auch.
API-Schlüssel brauchen den Ultra-Plan der Person mit der Rolle Inhaber oder Admin, die sie erstellt, und sind in der Beta.

So geht's

Installiere zl mit npm install -g zeitlicht-cli, oder führe einen einzelnen Befehl mit npx zeitlicht-cli aus.
Speichere den Schlüssel in einer Datei, führe zl auth login < key.txt aus und lösche die Datei danach. zl prüft den Schlüssel und legt ihn im Schlüsselbund deines Systems ab, und wo es keinen gibt, in einer Datei, die nur du lesen kannst. In CI setzt du stattdessen die Umgebungsvariable ZEITLICHT_API_KEY.
zl auth status zeigt Name, Arbeitsbereich, Berechtigungen und Ablaufdatum des Schlüssels. zl zeigt immer nur den Anfang des Schlüssels.
zl boards listet die Boards mit ihren IDs, und zl board mit einer Board-ID dahinter listet dessen Spalten. zl members, zl tags und zl topics listen Personen, Tags und Themen. Mit einem Schlüssel für ausgewählte Boards zeigt zl members keine E-Mail-Adressen.
zl tasks --assignee me --open listet deine offenen Aufgaben. Filtere mit --board, --column, --tester, --done, --since und --query. --all lädt alle Seiten.
zl task show 3f2a9c1e zeigt eine Aufgabe, genannt über ihre Kurz-ID, ihre ID oder ihren Link.
Lege eine Aufgabe mit zl task create --title "Login prüfen" --board BOARD_ID an, auf Wunsch mit --description-file notizen.md, --assignee me, --tag TAG_ID, --due 2026-12-24 oder --priority high. Ändere sie mit zl task update, verschiebe sie mit zl task move 3f2a9c1e --column SPALTEN_ID und lösche sie mit zl task delete 3f2a9c1e --yes.
Übergib eine Aufgabe an die Tester mit zl test request 3f2a9c1e --instructions-file TESTING.md --tester mia@example.com --move-to SPALTEN_ID. zl test status 3f2a9c1e zeigt Tester, Urteile und Bugs.
Es gibt mehr: zl comment add, zl checklist add, zl checklist check, zl bug report, zl bug status, zl link add und zl attach für Dateien bis 10 MiB. Den Dateityp erkennt Zeitlicht wie in der App an der Endung; gesperrte Typen wie .exe oder .svg lassen sich nicht anhängen. zl task id-from liest einen Branch-Namen oder Titel eines Pull Requests und gibt die Aufgaben-ID darin aus. zl --help listet alle Befehle.
Hänge --json an einen Befehl, um eine Ausgabe zu bekommen, die ein Skript lesen kann.
zl auth logout vergisst den gespeicherten Schlüssel.

Das Ergebnis

zl liest und ändert die Aufgaben auf den Boards, die der Schlüssel erlaubt, und zwar in deinem Namen. Jede Anfrage erscheint im Zugriffsprotokoll des Schlüssels.

Häufige Fragen

Welche Exit-Codes nutzt zl?

0 erledigt, 1 von der API abgelehnt, 2 falsch aufgerufen, 3 kein Schlüssel oder Schlüssel abgelehnt, 4 keine Verbindung. Die Fehlerzeile nennt den Grund, etwa key-expired.

Kann ein Skript zl task create gefahrlos wiederholen?

Ja. Gib --idempotency-key mit einem eigenen Wert an, etwa der Run-ID deines CI-Jobs (bis zu 200 Buchstaben, Ziffern oder _.:-). Läuft derselbe Befehl mit demselben Wert innerhalb von 24 Stunden noch einmal, gibt Zeitlicht die erste Aufgabe zurück, statt eine zweite anzulegen. Solange die erste Anfrage noch läuft, bekommt eine Wiederholung 409 (idempotency-in-progress), höchstens 60 Sekunden lang. Derselbe Wert mit anderen Angaben bekommt 422.

Kann zl mit einer Testumgebung sprechen?

Ja. ZEITLICHT_API_URL lenkt zl an eine andere Adresse. Unverschlüsseltes HTTP geht nur für deinen eigenen Rechner (localhost).

Wo genau liegt mein Schlüssel?

Im Schlüsselbund von macOS, Windows oder Linux. Ohne Schlüsselbund in ~/.config/zeitlicht/credentials.json, die nur du lesen kannst. zl warnt, wenn andere die Datei lesen könnten. ZL_NO_KEYRING=1 überspringt den Schlüsselbund.