Installation et configuration
Installer le CLI
npm install -g @klarocards/cli
Nécessite Node.js 18 ou supérieur. Une fois installé, la commande klaro est disponible globalement.
Se connecter à votre compte
klaro login
Vous serez invité à saisir votre email et mot de passe. Votre jeton de session est stocké localement dans ~/.klaro/secrets.json, séparément du reste de la configuration.
Pour les environnements non interactifs (pipelines CI, agents IA comme Claude Code), utilisez --env pour lire les identifiants depuis des variables d'environnement au lieu de les demander interactivement :
export KLARO_LOGIN="vous@example.com"
export KLARO_PASSWORD="votre-mot-de-passe"
klaro login --env
C'est l'approche recommandée lorsqu'un agent IA doit s'authentifier en votre nom : définissez les variables dans votre session shell et laissez l'agent exécuter klaro login --env sans invite interactive.
Pour vérifier qui est actuellement connecté :
klaro whoami
Sélectionner un projet
La plupart des commandes nécessitent un contexte de projet. Un projet est identifié par son sous-domaine — la première partie de votre URL Klaro Cards. Par exemple, si votre projet se trouve à https://mon-projet.klaro.cards, le sous-domaine est mon-projet.
Listez les projets auxquels vous avez accès, puis sélectionnez-en un :
klaro ls projects
klaro use mon-projet
À partir de là, toutes les commandes ciblent mon-projet par défaut. Vous pouvez toujours spécifier un autre projet ponctuellement avec -p :
klaro ls -p autre-projet
Si votre projet est hébergé sur une instance dédiée (par ex. https://mon-projet.klaro.votredomaine.com), consultez Cibler une autre instance Klaro pour configurer d'abord l'URL de l'API.
Parcourir votre projet
Lister les cartes
Les cartes sont organisées sur des tableaux de bord. Vous pouvez trouver l'identifiant d'un tableau dans son URL (par ex. https://mon-projet.klaro.cards/boards/{espace}/backlog signifie que le tableau est backlog), ou les lister avec klaro ls boards.
klaro ls -b backlog # lister les cartes du tableau backlog
klaro ls -b backlog -l 50 # afficher plus de résultats
klaro ls -b backlog --dims progress,assignee # ajouter des colonnes de dimensions
klaro ls -b backlog -f status=open # filtrer par valeur de dimension
Si vous travaillez principalement sur le même tableau, définissez-le par défaut pour ne plus avoir à préciser -b dans les commandes suivantes :
klaro config set board backlog
klaro ls # utilise maintenant backlog par défaut
Toutes les commandes dans la suite de ce guide supposent qu'un tableau par défaut a été défini.
Explorer la structure du projet
Listez les tableaux et dimensions disponibles dans votre projet :
klaro ls boards
klaro ls dimensions
Obtenez des détails sur un tableau ou une dimension spécifique :
klaro describe board backlog # voir les filtres du tableau
klaro describe dimension status # voir les valeurs autorisées
Lire et modifier des cartes
Lire une carte
klaro read 42
Cela affiche la carte en markdown avec coloration syntaxique dans votre terminal. Pour inclure les valeurs des dimensions (en frontmatter YAML) :
klaro read 42 --dims progress,assignee
Utilisez --raw pour obtenir du markdown brut sans mise en forme du terminal, utile pour le rediriger :
klaro read 42 --raw
Modifier une carte interactivement
klaro edit 42
Cela ouvre la carte dans votre $EDITOR. Lorsque vous enregistrez et fermez, les modifications sont envoyées à Klaro. Vous pouvez modifier plusieurs cartes à la suite :
klaro edit 10 11 12
Incluez les dimensions pour pouvoir aussi les mettre à jour dans l'éditeur :
klaro edit 42 --dims progress,assignee
Mettre à jour une carte depuis un fichier ou stdin
La commande write met à jour le contenu d'une carte sans ouvrir d'éditeur, ce qui est idéal pour les scripts et les agents IA :
klaro write 42 -f carte.md # depuis un fichier
cat carte.md | klaro write 42 # depuis stdin
Un usage courant consiste à lire une carte, la transformer, puis la réécrire :
klaro read 42 --raw | une-transformation | klaro write 42
Créer et mettre à jour des cartes
Créer une carte
La forme la plus simple prend un titre :
klaro create "Corriger la page de connexion"
Vous pouvez définir les dimensions à la création :
klaro create "Corriger la page de connexion" progress=todo assignee=Alice
Créer depuis un fichier markdown ou depuis stdin :
klaro create @spec.md -b backlog
cat spec.md | klaro create -b backlog
Utilisez --edit pour ouvrir la carte dans votre éditeur juste après la création :
klaro create "Brouillon : nouvelle fonctionnalité" --edit
Dupliquer une carte
Redirigez read vers create :
klaro read 3 --raw | klaro create
klaro read 3 --raw | klaro create assignee=Bob # dupliquer et réassigner
Mettre à jour les dimensions
klaro update 42 progress=done
klaro update 10 11 12 progress=done # mise à jour par lot
Supprimer des cartes
klaro del 42
klaro del 10 11 12
Gérer les pièces jointes
Joindre des fichiers à une carte
klaro attach 42 photo.jpg
klaro attach 42 a.jpg b.pdf # plusieurs fichiers à la fois
klaro attach 42 cover.jpg --cover # définir comme image de couverture
klaro attach 42 doc.pdf -d "Spécification API" # avec une description
Lister et retirer des pièces jointes
klaro ls attachments 42 # lister les pièces jointes d'une carte
klaro detach 42 <uuid> # retirer la pièce jointe et son fichier
klaro detach 42 <uuid> --keep-file # retirer uniquement l'enregistrement
Travailler hors ligne
Le workflow fetch/sync vous permet de télécharger des cartes sous forme de fichiers markdown locaux, de les modifier avec n'importe quel outil, et de renvoyer les changements.
Télécharger des cartes
klaro fetch 1 2 3
klaro fetch 1 --dims progress # inclure les dimensions dans le fichier
Les cartes sont enregistrées sous forme de fichiers markdown dans le répertoire courant.
Modifier localement, puis synchroniser
Modifiez les fichiers téléchargés avec n'importe quel éditeur ou outil, puis renvoyez les changements :
klaro sync # envoyer les modifications et supprimer les fichiers locaux
klaro sync --keep # envoyer les modifications mais garder les fichiers locaux
klaro sync --dry-run # prévisualiser ce qui serait synchronisé
Configuration
Enregistrer des valeurs par défaut
Si vous travaillez toujours avec le même tableau ou les mêmes dimensions, enregistrez-les par défaut pour ne plus avoir à les saisir à chaque fois :
klaro config set board backlog
klaro config set dims progress,assignee
Ou enregistrez des valeurs par défaut à la volée avec --save-defaults :
klaro ls --dims progress --board backlog --save-defaults
Affichez votre configuration actuelle :
klaro config list
Supprimez une valeur par défaut :
klaro config unset board
Cibler une autre instance Klaro
Par défaut, le CLI se connecte à https://api.klaro.cards. Si votre organisation utilise une instance Klaro dédiée sur son propre domaine, configurez l'URL de l'API pour pointer vers elle :
klaro config set api_url https://api.klaro.votredomaine.com
Réinitialiser à la valeur par défaut :
klaro config unset api_url
Configuration locale au projet
Exécutez klaro init . dans un répertoire de projet pour créer un dossier .klaro/ local. Lorsqu'il est présent, le CLI l'utilise à la place de la configuration globale ~/.klaro/. C'est utile pour les dépôts où l'équipe partage un projet ou un tableau par défaut via le contrôle de version (commitez config.json, ajoutez secrets.json au gitignore).
klaro init .
echo "secrets.json" >> .klaro/.gitignore
Référence rapide
Lancez l'aide-mémoire intégré pour un aperçu compact de toutes les commandes :
klaro cheatsheet # format markdown (adapté aux IA)
klaro cheatsheet --table # format tableau (adapté aux humains)
Pour de l'aide détaillée sur n'importe quelle commande :
klaro --help
klaro <command> --help