Ir al contenido
dotby Docs

Usa la CLI

El comando dotby pone tu espacio de trabajo en la terminal. Crea una tarea sin salir de la rama en la que estás, revisa lo que tienes asignado o deja que un script haga cien de esas cosas de una vez.

Es un cliente ligero de la API REST: todo lo que hace, lo hace como tú y con tus permisos. No hay una cuenta aparte para la CLI ni tokens con superpoderes.

Instalación

Section titled “Instalación”

La CLI se distribuye como un paquete de npm que ya incluye el binario de tu plataforma. No tiene script de postinstall, así que también se instala con --ignore-scripts, que es como suelen ejecutarse CI y los entornos aislados de los agentes.

Terminal window
npm i -g dotby-cli

El paquete se llama dotby-cli; el comando que instala es dotby.

Inicia sesión

Section titled “Inicia sesión”

  1. En tu máquina, deja que abra el navegador:

    Terminal window
    dotby auth login
    dotby auth status

    La sesión se renueva sola y las credenciales se guardan en el llavero del sistema, nunca en el repositorio.

  2. En un script, en un job de CI o en un agente no hay navegador. Crea un token de acceso personal en la app, en Configuración → Claves de API, y pásalo por la entrada estándar:

    Terminal window
    printf %s "$DOTBY_PAT" | dotby auth login --with-token

    Definir DOTBY_TOKEN en el entorno también funciona, y tiene prioridad sobre cualquier credencial guardada.

Nunca pases un token como valor de una opción o como argumento: terminaría en el historial del shell y en la lista de procesos de cualquier usuario de la máquina.

Apúntala a un espacio de trabajo

Section titled “Apúntala a un espacio de trabajo”

Todos los comandos necesitan saber con qué espacio de trabajo hablan, y casi todos necesitan un proyecto. Responde eso una vez por repositorio:

Terminal window
dotby init

Escribe un .dotby.toml que versionas, para que todo el equipo herede el mismo contexto:

workspace = "acme"
project = "ENG"

Cuando quieras saber qué está realmente en uso —y de dónde salió cada valor— pregunta:

Terminal window
dotby context

La prioridad es: opción --workspace → DOTBY_WORKSPACE → el .dotby.toml más cercano → tu configuración de usuario. Lo que pasas en la línea de comandos siempre gana.

Comandos del día a día

Section titled “Comandos del día a día”

La gramática tiene dos niveles como máximo: un sustantivo y luego un verbo. --help funciona en cualquiera de ellos.

Terminal window
dotby issue list --state-bucket started
dotby issue view ENG-42 --include description
dotby issue create --title "Arreglar la redirección de login" --priority high
dotby issue move ENG-42 --state <stateId>
dotby issue comment ENG-42 -b "Desplegado en staging"
dotby search "redirección de login"

Una tarea se nombra como la dices en voz alta: ENG-42. Los proyectos van por su clave (ENG) y los espacios de trabajo por su slug. Los ids también sirven en todas partes, tanto para leer como para escribir.

Léela desde un script

Section titled “Léela desde un script”

La salida estándar lleva datos y nada más: el progreso, las sugerencias y los errores van a la salida de error, así que una tubería nunca se traga algo que necesitabas leer.

Terminal window
dotby issue list --json=identifier,title,state   # elige los campos
dotby issue list --json                          # lista los campos disponibles
dotby issue list --jq '.[].identifier'           # filtra sobre la marcha

--jq se ejecuta en el propio proceso, así que no hay que instalar el binario jq antes.

Dentro de CI o de un agente —o siempre que la salida se redirija— la CLI deja de colorear, deja de recortar y nunca pregunta.

Ensaya una escritura

Section titled “Ensaya una escritura”

Toda mutación acepta --dry-run: muestra la petición que enviaría, no cambia nada y sale con 0. No necesita red ni credenciales, así que es segura dentro de una prueba.

Terminal window
dotby issue create --title "Arreglar el login" --priority high --dry-run
dotby issue archive ENG-42 --yes

--yes omite las confirmaciones. Los comandos destructivos lo necesitan en cualquier sesión no interactiva, porque la CLI se niega a preguntar donde nadie puede responder.

Códigos de salida

Section titled “Códigos de salida”
Código Significado
0 Todo bien
1 Algo falló
2 Opciones incorrectas, argumentos que faltan o ningún espacio de trabajo en el contexto
3 La tarea, el proyecto o el espacio de trabajo no existe
4 Sesión no iniciada o token rechazado

Eso es lo que hace que la CLI se pueda programar: “créalo si no existe” es un case, no una comparación de texto.

Terminal window
dotby issue view "$KEY" --json= >/dev/null 2>&1
case $? in
  0) echo "existe" ;;
  3) dotby issue create --title "$TITLE" ;;
  4) echo "hace falta iniciar sesión" >&2; exit 1 ;;
esac

Con --json, un fallo también imprime un sobre legible cuyo hint es exactamente el comando que lo arregla.

Crea muchas de una vez

Section titled “Crea muchas de una vez”

Envía un objeto JSON por línea en la entrada estándar. La CLI las agrupa en lotes y devuelve un resultado por elemento, así que un fallo parcial te dice exactamente qué línea falló.

Terminal window
dotby bulk create --priority medium <<'EOF'
{"title":"Configurar CI"}
{"title":"Arreglar la redirección de login","priority":1}
{"title":"Escribir el documento de onboarding"}
EOF

Todo lo demás

Section titled “Todo lo demás”

Los comandos cubren el camino diario. Para el resto de la API —miembros, registros de tiempo, iniciativas, páginas, sprints— llámala directamente:

Terminal window
dotby api GET /me
dotby api GET '/workspaces/acme/issues/mine?tab=assigned'
echo '{"name":"Lanzamiento del Q3"}' | dotby api POST /workspaces/acme/initiatives

Las rutas parten de /v1. La autenticación, los reintentos y el mapeo de errores siguen aplicándose, así que esto es un atajo, no un downgrade.