API e integraciones

Usar la línea de comandos zl

Q: ¿Qué códigos de salida usa zl?

0 hecho, 1 rechazado por la API, 2 uso incorrecto, 3 sin clave o clave rechazada, 4 sin conexión. La línea de error indica el motivo, como key-expired.

Q: ¿Puede un script repetir zl task create sin riesgo?

Sí. Añade --idempotency-key con un valor propio, como el ID de ejecución de tu CI (hasta 200 letras, cifras o _.:-). Si el mismo comando con el mismo valor se ejecuta otra vez en 24 horas, Zeitlicht devuelve la primera tarea en lugar de crear otra. Mientras la primera solicitud sigue en curso, una repetición recibe 409 (idempotency-in-progress), como mucho durante 60 segundos. El mismo valor con otros datos recibe 422.

Q: ¿Puede zl hablar con un entorno de pruebas?

Sí. ZEITLICHT_API_URL dirige zl a otra dirección. HTTP sin cifrar solo funciona para tu propio ordenador (localhost).

Q: ¿Dónde está exactamente mi clave?

En el llavero de macOS, Windows o Linux. Sin llavero, en ~/.config/zeitlicht/credentials.json, que solo tú puedes leer. zl avisa si otras personas pudieran leer ese archivo. ZL_NO_KEYRING=1 omite el llavero.

Quiero …

… leer y cambiar las tareas de este espacio de trabajo desde una terminal o un script con el comando zl.

Antes de empezar

Necesitas Node.js 22 o más reciente y una clave de API de este espacio de trabajo, consulta «Crear y revocar claves de API».
Los permisos de la clave deciden qué puede hacer zl. Solo lectura lee. Lectura y escritura además cambia tareas y rellena las pruebas. Acceso total también elimina.
Las claves de API necesitan el plan Ultra de la persona Propietario o Admin que las crea, y están en beta.

Así se hace

Instálalo con npm install -g zeitlicht-cli, o ejecuta un solo comando con npx zeitlicht-cli.
Guarda la clave en un archivo, ejecuta zl auth login < key.txt y borra el archivo después. zl comprueba la clave y la guarda en el llavero de tu sistema o, si no hay, en un archivo que solo tú puedes leer. En CI, define en su lugar la variable de entorno ZEITLICHT_API_KEY.
zl auth status muestra el nombre, el espacio de trabajo, los permisos y la fecha de caducidad de la clave. zl solo muestra el comienzo de la clave.
zl boards lista los tableros con sus ID, y zl board seguido del ID de un tablero lista sus columnas. zl members, zl tags y zl topics listan personas, etiquetas y temas. Con una clave para tableros seleccionados, zl members no muestra correos electrónicos.
zl tasks --assignee me --open lista tus tareas abiertas. Filtra con --board, --column, --tester, --done, --since y --query. --all carga todas las páginas.
zl task show 3f2a9c1e muestra una tarea, nombrada por su ID corto, su ID o su enlace.
Crea una tarea con zl task create --title "Revisar el inicio de sesión" --board BOARD_ID y, si quieres, --description-file notas.md, --assignee me, --tag TAG_ID, --due 2026-12-24 o --priority high. Cámbiala con zl task update, muévela con zl task move 3f2a9c1e --column COLUMN_ID y elimínala con zl task delete 3f2a9c1e --yes.
Pasa una tarea a pruebas con zl test request 3f2a9c1e --instructions-file TESTING.md --tester mia@example.com --move-to COLUMN_ID. zl test status 3f2a9c1e muestra quién prueba, los veredictos y los bugs.
Hay más: zl comment add, zl checklist add, zl checklist check, zl bug report, zl bug status, zl link add y zl attach para archivos de hasta 10 MiB. Como en la app, Zeitlicht toma el tipo de archivo de la extensión; los tipos bloqueados, como .exe o .svg, no se pueden adjuntar. zl task id-from lee el nombre de una rama o el título de un pull request y muestra el ID de la tarea que contiene. zl --help lista todos los comandos.
Añade --json a cualquier comando para obtener una salida que un script pueda leer.
zl auth logout olvida la clave guardada.

El resultado

zl lee y cambia las tareas de los tableros que permite la clave, en tu nombre. Cada solicitud aparece en el registro de accesos de la clave.

Preguntas frecuentes

¿Qué códigos de salida usa zl?

0 hecho, 1 rechazado por la API, 2 uso incorrecto, 3 sin clave o clave rechazada, 4 sin conexión. La línea de error indica el motivo, como key-expired.

¿Puede un script repetir zl task create sin riesgo?

Sí. Añade --idempotency-key con un valor propio, como el ID de ejecución de tu CI (hasta 200 letras, cifras o _.:-). Si el mismo comando con el mismo valor se ejecuta otra vez en 24 horas, Zeitlicht devuelve la primera tarea en lugar de crear otra. Mientras la primera solicitud sigue en curso, una repetición recibe 409 (idempotency-in-progress), como mucho durante 60 segundos. El mismo valor con otros datos recibe 422.

¿Puede zl hablar con un entorno de pruebas?

Sí. ZEITLICHT_API_URL dirige zl a otra dirección. HTTP sin cifrar solo funciona para tu propio ordenador (localhost).

¿Dónde está exactamente mi clave?

En el llavero de macOS, Windows o Linux. Sin llavero, en ~/.config/zeitlicht/credentials.json, que solo tú puedes leer. zl avisa si otras personas pudieran leer ese archivo. ZL_NO_KEYRING=1 omite el llavero.