Aller au contenu
dotby Docs

Utiliser la CLI

La commande dotby amène votre espace de travail dans le terminal. Créez une tâche sans quitter la branche en cours, regardez ce qui vous est assigné, ou laissez un script en faire cent d’un coup.

C’est un client léger de l’API REST : tout ce qu’il fait, il le fait en votre nom et avec vos permissions. Il n’y a ni compte séparé pour la CLI, ni jeton tout-puissant.

Installation

Section titled “Installation”

La CLI est publiée comme un paquet npm qui embarque le binaire de votre plateforme. Il n’y a pas de script postinstall, donc elle s’installe aussi avec --ignore-scripts, ce que font les CI verrouillées et les bacs à sable d’agents.

Terminal window
npm i -g dotby-cli

Le paquet s’appelle dotby-cli ; la commande installée est dotby.

Connexion

Section titled “Connexion”

  1. Sur votre machine, laissez-la ouvrir le navigateur :

    Terminal window
    dotby auth login
    dotby auth status

    La session se renouvelle toute seule et les identifiants vont dans le trousseau du système — jamais dans le dépôt.

  2. Dans un script, un job de CI ou un agent, il n’y a pas de navigateur. Créez un jeton d’accès personnel dans l’app, sous Paramètres → Clés d’API, puis passez-le sur l’entrée standard :

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

    Définir DOTBY_TOKEN dans l’environnement fonctionne aussi, et prime sur tout identifiant enregistré.

Ne passez jamais un jeton comme valeur d’option ou comme argument : il finirait dans l’historique du shell et dans la liste des processus de tous les utilisateurs de la machine.

Pointer vers un espace de travail

Section titled “Pointer vers un espace de travail”

Chaque commande doit savoir à quel espace de travail elle parle, et la plupart ont besoin d’un projet. Répondez à cette question une fois par dépôt :

Terminal window
dotby init

Cela écrit un .dotby.toml que vous versionnez, pour que toute l’équipe hérite du même contexte :

workspace = "acme"
project = "ENG"

Quand vous voulez savoir ce qui s’applique vraiment — et d’où vient chaque valeur — demandez :

Terminal window
dotby context

L’ordre de priorité : l’option --workspace → DOTBY_WORKSPACE → le .dotby.toml le plus proche → votre configuration utilisateur. Ce que vous passez en ligne de commande l’emporte toujours.

Les commandes du quotidien

Section titled “Les commandes du quotidien”

La grammaire tient en deux niveaux au maximum : un nom, puis un verbe. --help fonctionne sur chacun d’eux.

Terminal window
dotby issue list --state-bucket started
dotby issue view ENG-42 --include description
dotby issue create --title "Corriger la redirection de connexion" --priority high
dotby issue move ENG-42 --state <stateId>
dotby issue comment ENG-42 -b "Déployé en staging"
dotby search "redirection de connexion"

Une tâche s’adresse comme on la dit à l’oral : ENG-42. Les projets passent par leur clé (ENG), les espaces de travail par leur slug. Les ids fonctionnent partout aussi, en lecture comme en écriture.

La lire depuis un script

Section titled “La lire depuis un script”

La sortie standard ne transporte que des données — la progression, les conseils et les erreurs vont sur la sortie d’erreur, donc un pipe n’avale jamais ce que vous vouliez lire.

Terminal window
dotby issue list --json=identifier,title,state   # choisissez les champs
dotby issue list --json                          # liste les champs disponibles
dotby issue list --jq '.[].identifier'           # filtre à la volée

--jq s’exécute dans le processus : aucun binaire jq à installer d’abord.

Dans une CI ou dans un agent — ou dès que la sortie est redirigée — la CLI n’utilise plus de couleurs, ne tronque plus rien et ne pose aucune question.

Répéter une écriture

Section titled “Répéter une écriture”

Chaque mutation accepte --dry-run : elle affiche la requête qu’elle enverrait, ne change rien et sort avec 0. Ni réseau ni identifiants nécessaires, ce qui la rend sûre dans un test.

Terminal window
dotby issue create --title "Corriger la connexion" --priority high --dry-run
dotby issue archive ENG-42 --yes

--yes saute les confirmations. Les commandes destructrices en ont besoin dans toute session non interactive, car la CLI refuse de poser une question là où personne ne peut répondre.

Codes de sortie

Section titled “Codes de sortie”
Code Signification
0 Succès
1 Quelque chose a échoué
2 Mauvaises options, arguments manquants ou aucun espace de travail dans le contexte
3 La tâche, le projet ou l’espace de travail n’existe pas
4 Non connecté, ou jeton refusé

C’est ce qui rend la CLI scriptable : « crée-la si elle n’existe pas » devient un case, pas une comparaison de texte.

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

Avec --json, un échec affiche aussi une enveloppe lisible dont le hint est exactement la commande qui corrige le problème.

En créer beaucoup d’un coup

Section titled “En créer beaucoup d’un coup”

Envoyez un objet JSON par ligne sur l’entrée standard. La CLI les regroupe par lots et renvoie un résultat par élément, donc un échec partiel vous dit exactement quelle ligne a échoué.

Terminal window
dotby bulk create --priority medium <<'EOF'
{"title":"Mettre en place la CI"}
{"title":"Corriger la redirection de connexion","priority":1}
{"title":"Rédiger le document d'onboarding"}
EOF

Tout le reste

Section titled “Tout le reste”

Les commandes couvrent le chemin quotidien. Pour le reste de l’API — membres, temps passé, initiatives, pages, sprints — appelez-la directement :

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

Les chemins partent de /v1. L’authentification, les nouvelles tentatives et la gestion des erreurs s’appliquent toujours : c’est un raccourci, pas une version au rabais.