Kanera CLI
@kanera/cli place Kanera dans votre terminal afin que vous puissiez rechercher des cartes, gérer le travail et automatiser des tâches à partir de scripts shell. Les agents de codage IA capables d'exécuter des commandes shell peuvent également l'utiliser, sans configuration client MCP ni serveur de longue durée.
Installer
Nécessite Node.js 22 ou version ultérieure. Exécutez cette commande dans votre terminal pour installer le kanera commande globalement :
npm install --global @kanera/cli
Le package publié n'a aucune dépendance d'exécution. Confirmez que la commande est disponible :
kanera commands
Pour l'essayer sans installer :
npx @kanera/cli commands
Authentifier
Connectez-vous via votre navigateur :
kanera auth login
auth login utilise le flux de périphérique OAuth, de la même manière que Claude et Codex se connectent. Il imprime un lien et un code court, ouvre le lien dans votre navigateur et se termine tout seul une fois que vous l'approuvez. Vérifiez que le code sur la page correspond à votre terminal avant de choisir Autoriser l'accès. Via SSH ou sur une machine sans tête, ouvrez le lien sur n'importe quel appareil ; passer --no-browser pour éviter d'en lancer un.
La CLI stocke ensuite un jeton d'accès de courte durée et un jeton d'actualisation, et les renouvelle automatiquement. La connexion apparaît sous Paramètres -> Agents IA comme Kanera CLI (le nom de votre ordinateur), et les modifications qu'il apporte sont étiquetées avec ce nom dans l'historique de la carte. Révoquez-le ici, ou exécutez kanera auth logout, ce qui le termine également sur le serveur.
Nommer l'agent
Lorsqu'un agent IA pilote la CLI, nommez-le lors de la connexion afin que son travail soit étiqueté comme celui de cet agent :
kanera auth login --agent "Claude Code"
La connexion apparaît alors comme Claude Code (Kanera CLI sur le nom de votre ordinateur) sur l'écran de consentement, sous Paramètres -> Agents IA, et comme via Claude Code (Kanera CLI sur …) sur chaque commentaire, changement de carte, notification et exécution d'agent qu'il effectue. KANERA_AGENT_NAME définit le même nom à partir de l'environnement. Le nom est fixe pour la durée de vie de la connexion, donnez donc à chaque agent son propre profil avec --profile quand plusieurs partagent une machine. --agent ne s'applique pas aux clés API, car le travail effectué avec une clé personnelle est enregistré sous votre nom.
Utilisez plutôt une clé API
Utilisez une clé API pour les tâches CI, cron et les agents sans surveillance, où personne n'est présent pour approuver une connexion au navigateur, ou lorsque vous souhaitez un identifiant que Kanera applique en lecture seule. Créez-en un dans Paramètres du profil -> Clés API, ou dans Paramètres de l'espace de travail -> API lorsque l'identifiant doit appartenir à un espace de travail plutôt qu'à une personne. Voir API Kanera pour la différence.
kanera auth login --with-api-key
Sur Kanera hébergé, cela ouvre la page de vos clés API à l'adresse https://board.kanera.app/settings/api-keys, demande la clé avec l'écho du terminal supprimé afin qu'elle n'atterrisse jamais dans le défilement de votre shell, la vérifie par rapport à Kanera et la stocke.
Les modifications apportées avec une clé personnelle sont enregistrées comme vous, sans via badge, donc une connexion par navigateur est le meilleur choix lorsque vous souhaitez que le travail d'un agent soit étiqueté. Choisissez un Lecture seule clé personnelle lorsque les informations d'identification concernent un agent sans surveillance. La CLI signale la portée qu'elle détient et refuse la sortie d'écriture avec un code distinct afin qu'un agent puisse s'arrêter plutôt que de réessayer.
kanera whoami # who am I, and what may this credential do?
kanera doctor # diagnose credentials, connectivity, and scope
Dans CI ou dans un bac à sable d'agent, ignorez entièrement le profil stocké et définissez KANERA_API_KEY.
Inspecter un calendrier
kanera schedule "$BOARD_ID" --json
kanera schedule --workspaceId "$WORKSPACE_ID" --json
kanera card update MKT-42 --changes.startDateLocalDate 2026-11-02 --changes.dueDateLocalDate 2026-11-06
Utilisez exactement une seule portée : un argument de position sur le tableau ou --workspaceId. La lecture renvoie le Chronologie les dates prévues du moteur, la durée et la marge de la journée de travail, les cartes critiques, les conflits, la fin prévue et le glissement par rapport à la dernière date d'échéance. La mise à jour modifie les dates enregistrées et nécessite un accès en écriture ; il ne déplace pas automatiquement les successeurs. Relisez le planning après avoir changé les dates.
kanera my-day --json inclut les conflits d'horaire, les travaux critiques et les démarrages planifiés manqués ; kanera portfolio --json renvoie le cumul multi-cartes pris en charge, y compris l'état de planification par carte. Les abonnements aux événements nécessitent un client HTTP MCP hébergé ; ils ne sont pas fournis par le transport stdio de la CLI.
Commandes quotidiennes
kanera my-day # overdue, due this week, idle, and Up next in one view
kanera work # your work across every accessible board
kanera boards # every board you can reach, including guest boards
kanera card MKT-42 # a card, by key, id, or URL
kanera card done MKT-42 # mark it complete
kanera comment MKT-42 "Shipped."
kanera search "renewal"
kanera priorities # an Up next queue
kanera separator create "$BOARD" "$LIST" "This week" --color blue
kanera capture "Renew the venue insurance" # a task in your private Scratchpad Inbox, no board needed
kanera remind MKT-42 "friday 3pm" # a private reminder on a card, up to 8 weeks ahead
kanera remind clear MKT-42
kanera reminders # your pending reminders, soonest first
kanera watch MKT-42 # follow a card's activity; kanera unwatch MKT-42 stops
kanera inbox # your latest notifications; then kanera inbox --since "<cursor>" for only what is new
kanera card upload-link MKT-42 test-run.log # a one-time URL; then curl -fsS -T ./test-run.log "<uploadUrl>"
kanera card attachment MKT-42 "$ATTACHMENT" # an attachment's text, or an image's details
Les arguments de carte acceptent une clé de carte telle que MKT-42, un identifiant de carte ou une URL canonique de carte, afin que vous puissiez coller tout ce que vous avez devant vous. Les arguments de date sont acceptés YYYY-MM-DD ou des expressions telles que "tomorrow 1pm" ou "next friday", lisez dans le fuseau horaire de votre profil : kanera card update MKT-42 --changes.dueDateLocalDate "friday 3pm".
kanera commands répertorie tout ce que la CLI peut faire et fonctionne avant que vous vous connectiez. kanera commands --json est le catalogue lisible par machine qu'un agent utilise pour découvrir le reste.
La surface complète de l'outil
Les commandes nommées ci-dessus sont des raccourcis ergonomiques sur la couche d'outils MCP de Kanera – les mêmes outils qu'un agent IA voit sur MCP. Tout ce qui ne dispose pas d'un raccourci est toujours accessible :
kanera call cards.bulk_move --boardId "$BOARD" --cardIds[] MKT-42 --cardIds[] MKT-43 --listId "$LIST"
kanera help cards.bulk_move
Étant donné que la CLI lit directement la couche d'outils plutôt que de réimplémenter l'API publique, sa surface de commande ne peut pas s'écarter de ce que voient les agents, et un outil nouvellement ajouté peut être appelé depuis le shell le jour de sa livraison.
Séparateurs de tableaux
Créez un séparateur intitulé, éventuellement coloré, et positionnez-le par rapport à une carte ou à un autre séparateur :
kanera separator create "$BOARD" "$LIST" "This week" --color blue \
--anchor.side before --anchor.item.type card --anchor.item.id "$CARD"
kanera separator move "$SEPARATOR" "$LIST" \
--anchor.side after --anchor.item.type separator --anchor.item.id "$OTHER_SEPARATOR"
kanera separator update "$SEPARATOR" --title "Next up" --color green
kanera separator delete "$SEPARATOR"
Pour un bord de liste, passez --anchor.side after --anchor.item null pour le dessus ou --anchor.side before --anchor.item null pour le bas. La suppression du séparateur ne modifie aucune carte. kanera card move accepte la même ancre typée, de sorte que les cartes peuvent être placées immédiatement avant ou après un séparateur.
Relations avec les cartes
Ces commandes se lisent de gauche à droite : la première carte bloque la seconde. Les deux doivent appartenir au même espace de travail.
kanera card block MKT-42 WEB-18 # MKT-42 blocks WEB-18
kanera card unblock MKT-42 WEB-18 # remove that dependency
kanera card relate MKT-42 WEB-18 # connect them without a required order
kanera card WEB-18 # full detail includes relationships
kanera work --filters.blockedOnly true # find waiting work
kanera work --filters.atRiskOnly true # blocker overdue or due after the card
Pour le sens inverse ou plusieurs cibles, utilisez l'outil sous-jacent :
kanera call cards.set_relations --cardId WEB-18 --direction blocked_by \
--otherCardIds[] MKT-42 --otherCardIds[] MKT-43
Passer --remove true pour supprimer les relations sélectionnées. Inspecter failed et notAttemptedCardIds sur un résultat partiel : les ajouts réussis restent sauvegardés lorsqu'une autre cible est refusée. Un résultat avec relationsUnavailable noms écrits avec succès addedCardIds ou removedCardIds lorsque la lecture finale a échoué. Les suppressions réussies sont également signalées à côté des refus par carte. Voir Relations avec les cartes et blocage pour les autorisations, les transferts et les avertissements d’achèvement.
Graphiques de dépendance
Utiliser kanera deps pour lire les prérequis et le travail en aval en un seul appel :
kanera deps MKT-42 # one card's blocking neighbourhood
kanera deps --boardId "$BOARD" # chains touching a board
kanera deps --workspaceId "$WORKSPACE" # chains in a workspace
Passez exactement une portée. Un argument de carte accepte sa clé, son UUID ou son URL canonique. La sortie à l'échelle de la carte ajoute focus avec direct blockedBy / blocks ID, transitifs upstream / downstream ID dans l'ordre le plus proche, relatedTo, et onMap. Les cartes incluent des noms de tableau et de liste lisibles ainsi que le nombre de bloqueurs actifs/hors carte. Le résultat est plafonné à 400 fiches et rapports truncated. Voir la référence du graphique MCP.
Arguments
Les indicateurs sont mappés sur les arguments de l'outil et sont contraints à l'aide du schéma JSON de chaque outil, jamais par l'apparence de la valeur : une clé de carte peut paraître numérique et un identifiant peut paraître booléen.
kanera card update MKT-42 --changes.title "Revised" # dots nest
kanera work --scope.boardIds[] "$A" --scope.boardIds[] "$B" # repeat for arrays
kanera call cards.update --json-args '{"cardId":"MKT-42","changes":{"title":"Revised"}}'
Un argument tableau accepte également un tableau JSON, le moyen le plus simple de transmettre une liste d'objets. Cela crée une liste de contrôle, ses éléments et une sous-liste de contrôle dans un appel, puis complète deux éléments dans un autre :
kanera call checklists.create --cardId MKT-42 --title Launch \
--items '[{"text":"Prepare release","subChecklists":[{"title":"Verification","items":[{"text":"Run smoke tests"}]}]},{"text":"Announce launch"}]'
kanera call checklists.update_items --cardId MKT-42 \
--updates '[{"itemId":"<itemId>","changes":{"completed":true}},{"itemId":"<itemId>","changes":{"completed":true}}]'
Indicateurs inconnus, arguments requis manquants, mal formés --json-args, et les arguments de position excédentaires sont des erreurs d'utilisation. La CLI ne rejette jamais silencieusement un opérande.
Sortie
| Drapeau | Sortie |
|---|---|
| (aucun) | Tableaux et résumés lisibles par l'homme |
--json | Un { ok, tool, data } enveloppe |
--quiet | Le simple résultat, pour le raccordement dans jq |
Les échecs vont toujours à stderr, même dans --json mode, donc la redirection de la sortie standard vers un fichier ne mélange jamais une enveloppe d'erreur dans ce que l'appelant croit être des données de résultat.
Les pannes à débit limité et transitoires incluent retryable et, quand Kanera en fournit un, retryAfter.
Codes de sortie
| Coder | Signification |
|---|---|
0 | Succès |
1 | La demande a échoué |
2 | Mauvaise utilisation |
3 | Aucun titre valide |
4 | Interdit : il s'agit souvent d'un identifiant en lecture seule ou d'aucun rôle d'éditeur au sein du tableau. |
5 | Pas trouvé |
6 | Tarif limité |
4 est délibérément distinct de 1. Un agent détenant une clé de lecture doit dire « Je ne peux pas faire cela » en dehors de « cela n'a pas fonctionné » et s'arrêter plutôt que de réessayer.
Identifiants et profils
Ordre de résolution : --api-key, alors KANERA_API_KEY, puis un profil stocké, qui contient soit une connexion au navigateur, soit une clé API. Une clé explicite l'emporte toujours, de sorte qu'une tâche CI ne passe jamais par la connexion personnelle d'un développeur.
Les profils vivent dans ~/.config/kanera/config.json, écrit avec le mode 600. Les profils nommés permettent à une machine de détenir plusieurs identités :
kanera auth login --profile agent --api-key "kanera_u_live_..."
kanera --profile agent work --json
| Commande | Objectif |
|---|---|
kanera auth login | Connectez-vous via le navigateur (--with-api-key ou --api-key pour une clé) |
kanera auth status | Afficher l'identifiant actif et sa portée |
kanera auth list | Liste des profils stockés |
kanera auth token | Imprimez la clé API active, par exemple KANERA_API_KEY=$(kanera auth token). Les connexions au navigateur n'ont pas de clé à imprimer. |
kanera auth logout | Supprimer un profil stocké et mettre fin à la connexion du navigateur sur le serveur |
Un référentiel peut sélectionner un profil sans détenir de secret, en .kanera/config.json:
{ "profile": "agent" }
Ce fichier ne peut pas définir une origine API. Les origines reçoivent les informations d'identification du porteur, donc un référentiel extrait ne doit pas pouvoir en rediriger un. Utiliser --url, KANERA_PUBLIC_API_URL, ou l'origine enregistrée avec le profil lors auth login. Les origines sans bouclage doivent utiliser HTTPS.
Mises à jour
La CLI vérifie npm pour une version plus récente au maximum une fois par jour. Lorsqu'il en trouve un, il vous demande une fois votre commande terminée :
A new Kanera CLI is available: 1.7.0 → 1.8.0
Update now? [y/N]
Réponse y courir npm install --global @kanera/cli@<version>. Toute autre réponse ignore la mise à jour. La CLI ne demande plus un jour et imprime la commande afin que vous puissiez la mettre à jour plus tard.
La CLI demande uniquement lorsqu'une personne se trouve devant une borne interactive. Il ne vérifie ni ne demande jamais --json ou --quiet mode, lorsque l'entrée ou la sortie n'est pas un terminal (qui couvre les agents, les scripts et les canaux), lorsque CI est défini, ou lorsque vous l'exécutez npx, qui récupère sa propre copie. Ensemble KANERA_NO_UPDATE_CHECK=1 pour désactiver complètement le contrôle.
Kanera auto-hébergé
La connexion au navigateur est liée à l'adresse MCP de votre déploiement. Transmettez-la donc lors de la connexion :
kanera auth login --mcp-url https://your-kanera.example/mcp
Ou définir KANERA_MCP_URL. La CLI lit les métadonnées OAuth du serveur MCP pour trouver votre page de connexion Kanera, donc rien d'autre n'a besoin d'être configuré.
Pour une clé API, pointez plutôt la CLI vers votre API publique, et elle est enregistrée avec le profil :
kanera auth login --with-api-key --url https://api.your-kanera.example
La CLI ne peut pas savoir où se trouve une application Web auto-hébergée à partir de son origine API, donc avec une clé API, elle n'ouvre pas de navigateur. Créez la clé dans votre application Web Kanera sous Paramètres -> Clés API, puis collez-le à l'invite.
Ou définir KANERA_PUBLIC_API_URL par commande. kanera doctor signale le point de terminaison résolu, ce qui constitue généralement le moyen le plus rapide de trouver une origine mal configurée.
Utilisez-le depuis un agent IA
Deux voies, et elles sont complémentaires.
En tant qu'outil shell. Installez la CLI, attribuez à l'agent une clé en lecture seule et laissez-le exécuter des commandes. kanera setup écrit les instructions dont l'agent a besoin :
kanera setup claude # writes .claude/skills/kanera/SKILL.md
kanera setup codex # appends Kanera instructions to AGENTS.md
kanera skill # prints the portable Agent Skill document for any other harness
kanera setup codex est idempotent, donc le réexécuter après une mise à niveau n'empile pas les sections en double dans un fichier que vous modifiez également à la main. Ajouter --global à setup claude à installer pour votre compte plutôt que pour un seul projet.
Lorsque l'agent a déjà connecté les outils Kanera MCP, utilisez-les à la place de la CLI. Dans les deux cas, les lectures et mises à jour de cartes prises en charge ne doivent pas dépendre de l'automatisation du navigateur simplement parce que Kanera dispose également d'une interface Web.
En tant que serveur MCP. kanera mcp sert les mêmes outils sur stdio MCP en utilisant les informations d'identification que vous avez déjà stockées :
{
"mcpServers": {
"kanera": {
"command": "kanera",
"args": ["mcp"]
}
}
}
Cela signifie un kanera auth login couvre à la fois votre terminal et votre client MCP, au lieu d'un deuxième identifiant configuré à un deuxième endroit. Avec une connexion au navigateur, kanera mcp relaie votre serveur Kanera MCP et renouvelle le jeton au fur et à mesure de son exécution. Il parle à la fois du protocole MCP actuel et des révisions antérieures, de sorte que n'importe quel hôte MCP peut le lancer. Abonnements à des événements ne sont pas proposés sur stdio, car un hôte local n'a pas de rappel hébergé vers lequel livrer. Si votre client prend en charge MCP distant avec OAuth lui-même, vous pouvez également le connecter directement ; voir Connectez Kanera à votre agent IA.
Exigences du plan
Les connexions au navigateur et les clés API personnelles fonctionnent sur tous les forfaits hébergés, y compris gratuits, et Kanera auto-hébergé n'a aucune vérification de forfait. Besoin de clés API pour l'espace de travail et le tableau Pro ou l'essai Pro ; si une organisation hébergée passe à Free, elle est révoquée et kanera les commandes utilisant un échec avec le code de sortie 3 ou 4 jusqu'à ce que le plan soit rétabli. Les demandes suivent le Limites de débit de l'API de l'organisation du tableau, et la CLI attend et réessaye lorsqu'elle les survole brièvement.