API et intégrations

Utiliser la ligne de commande zl

Q: Quels codes de sortie zl utilise-t-il ?

0 fait, 1 refusé par l'API, 2 mauvaise utilisation, 3 pas de clé ou clé refusée, 4 pas de connexion. La ligne d'erreur indique la raison, par exemple key-expired.

Q: Un script peut-il relancer zl task create sans risque ?

Oui. Ajoutez --idempotency-key avec une valeur à vous, par exemple l'ID d'exécution de votre CI (jusqu'à 200 lettres, chiffres ou _.:-). Si la même commande avec la même valeur est relancée dans les 24 heures, Zeitlicht renvoie la première tâche au lieu d'en créer une deuxième. Tant que la première requête est en cours, une répétition reçoit 409 (idempotency-in-progress), pendant 60 secondes au plus. La même valeur avec d'autres informations reçoit 422.

Q: zl peut-il parler à un environnement de test ?

Oui. ZEITLICHT_API_URL dirige zl vers une autre adresse. Le HTTP non chiffré ne marche que pour votre propre ordinateur (localhost).

Q: Où se trouve exactement ma clé ?

Dans le trousseau de macOS, Windows ou Linux. Sans trousseau, dans ~/.config/zeitlicht/credentials.json, que vous seul pouvez lire. zl prévient si d'autres pouvaient lire ce fichier. ZL_NO_KEYRING=1 ignore le trousseau.

Je veux …

… lire et modifier les tâches de cet espace de travail depuis un terminal ou un script avec la commande zl.

Avant de commencer

Il vous faut Node.js 22 ou plus récent et une clé API de cet espace de travail, voir « Créer et révoquer des clés API ».
Les autorisations de la clé décident de ce que zl peut faire. Lecture seule lit. Lecture et écriture modifie aussi des tâches et remplit les tests. Accès complet supprime aussi.
Les clés API demandent le forfait Ultra de la personne Propriétaire ou Admin qui les crée, et elles sont en bêta.

Voici comment

Installez-la avec npm install -g zeitlicht-cli, ou lancez une seule commande avec npx zeitlicht-cli.
Enregistrez la clé dans un fichier, lancez zl auth login < key.txt, puis supprimez le fichier. zl vérifie la clé et la garde dans le trousseau de votre système ou, à défaut, dans un fichier que vous seul pouvez lire. En CI, définissez plutôt la variable d'environnement ZEITLICHT_API_KEY.
zl auth status affiche le nom, l'espace de travail, les autorisations et la date d'expiration de la clé. zl n'affiche jamais que le début de la clé.
zl boards liste les tableaux avec leurs ID, et zl board suivi de l'ID d'un tableau liste ses colonnes. zl members, zl tags et zl topics listent les personnes, les tags et les sujets. Avec une clé pour des tableaux sélectionnés, zl members n'affiche aucune adresse e-mail.
zl tasks --assignee me --open liste vos tâches ouvertes. Filtrez avec --board, --column, --tester, --done, --since et --query. --all charge toutes les pages.
zl task show 3f2a9c1e affiche une tâche, désignée par son ID court, son ID ou son lien.
Créez une tâche avec zl task create --title "Vérifier la connexion" --board BOARD_ID et, si vous voulez, --description-file notes.md, --assignee me, --tag TAG_ID, --due 2026-12-24 ou --priority high. Modifiez-la avec zl task update, déplacez-la avec zl task move 3f2a9c1e --column COLUMN_ID et supprimez-la avec zl task delete 3f2a9c1e --yes.
Transmettez une tâche aux tests avec zl test request 3f2a9c1e --instructions-file TESTING.md --tester mia@example.com --move-to COLUMN_ID. zl test status 3f2a9c1e affiche les testeurs, les verdicts et les bugs.
Il y a plus : zl comment add, zl checklist add, zl checklist check, zl bug report, zl bug status, zl link add et zl attach pour des fichiers jusqu'à 10 Mio. Comme dans l'app, Zeitlicht déduit le type de fichier de l'extension ; les types bloqués comme .exe ou .svg ne peuvent pas être joints. zl task id-from lit un nom de branche ou un titre de pull request et affiche l'ID de tâche qu'il contient. zl --help liste toutes les commandes.
Ajoutez --json à n'importe quelle commande pour une sortie lisible par un script.
zl auth logout oublie la clé enregistrée.

Le résultat

zl lit et modifie les tâches des tableaux autorisés par la clé, en votre nom. Chaque requête apparaît dans le journal d'accès de la clé.

Questions fréquentes

Quels codes de sortie zl utilise-t-il ?

0 fait, 1 refusé par l'API, 2 mauvaise utilisation, 3 pas de clé ou clé refusée, 4 pas de connexion. La ligne d'erreur indique la raison, par exemple key-expired.

Un script peut-il relancer zl task create sans risque ?

Oui. Ajoutez --idempotency-key avec une valeur à vous, par exemple l'ID d'exécution de votre CI (jusqu'à 200 lettres, chiffres ou _.:-). Si la même commande avec la même valeur est relancée dans les 24 heures, Zeitlicht renvoie la première tâche au lieu d'en créer une deuxième. Tant que la première requête est en cours, une répétition reçoit 409 (idempotency-in-progress), pendant 60 secondes au plus. La même valeur avec d'autres informations reçoit 422.

zl peut-il parler à un environnement de test ?

Oui. ZEITLICHT_API_URL dirige zl vers une autre adresse. Le HTTP non chiffré ne marche que pour votre propre ordinateur (localhost).

Où se trouve exactement ma clé ?

Dans le trousseau de macOS, Windows ou Linux. Sans trousseau, dans ~/.config/zeitlicht/credentials.json, que vous seul pouvez lire. zl prévient si d'autres pouvaient lire ce fichier. ZL_NO_KEYRING=1 ignore le trousseau.