Kanera CLI
@kanera/cli fügt Kanera in Ihr Terminal ein, sodass Sie Karten finden, Arbeit verwalten und Aufgaben über Shell-Skripte automatisieren können. KI-Coding-Agents, die Shell-Befehle ausführen können, können es auch verwenden, ohne MCP-Client-Konfiguration und ohne Server mit langer Laufzeit.
Installieren
Erfordert Node.js 22 oder neuer. Führen Sie diesen Befehl in Ihrem Terminal aus, um das zu installieren kanera Befehl global:
npm install --global @kanera/cli
Das veröffentlichte Paket weist keine Laufzeitabhängigkeiten auf. Bestätigen Sie, dass der Befehl verfügbar ist:
kanera commands
Um es ohne Installation auszuprobieren:
npx @kanera/cli commands
Authentifizieren
Melden Sie sich über Ihren Browser an:
kanera auth login
auth login verwendet den OAuth-Gerätefluss, genauso wie Claude und Codex eine Verbindung herstellen. Es druckt einen Link und einen Funktionscode, öffnet den Link in Ihrem Browser und wird nach Ihrer Genehmigung automatisch beendet. Überprüfen Sie vor der Auswahl, ob der Code auf der Seite mit Ihrem Terminal übereinstimmt Zugriff erlauben. Öffnen Sie den Link über SSH oder auf einem Headless-Computer auf einem beliebigen Gerät. passieren --no-browser um den Start zu überspringen.
Die CLI speichert dann ein kurzlebiges Zugriffstoken und ein Aktualisierungstoken und erneuert diese automatisch. Die Anmeldung wird unten angezeigt Einstellungen -> KI-Agenten als Kanera CLI (der Name Ihres Computers), und die vorgenommenen Änderungen werden im Kartenverlauf mit diesem Namen gekennzeichnet. Dort widerrufen oder ausführen kanera auth logout, was es auch auf dem Server beendet.
Benennen Sie den Agenten
Wenn ein KI-Agent die CLI steuert, benennen Sie ihn bei der Anmeldung, damit seine Arbeit als die dieses Agenten gekennzeichnet wird:
kanera auth login --agent "Claude Code"
Die Anmeldung erscheint dann als Claude Code (Kanera CLI auf dem Namen Ihres Computers) auf dem Einwilligungsbildschirm unter Einstellungen -> KI-Agenten, und als über Claude Code (Kanera CLI auf …) bei jedem Kommentar, jeder Kartenänderung, jeder Benachrichtigung und jedem Agentenlauf. KANERA_AGENT_NAME legt den gleichen Namen aus der Umgebung fest. Der Name ist für die Dauer der Anmeldung festgelegt. Geben Sie daher jedem Agenten ein eigenes Profil mit --profile wenn sich mehrere eine Maschine teilen. --agent gilt nicht für API-Schlüssel, da mit einem persönlichen Schlüssel ausgeführte Arbeiten als Sie erfasst werden.
Verwenden Sie stattdessen einen API-Schlüssel
Verwenden Sie einen API-Schlüssel für CI, Cron-Jobs und unbeaufsichtigte Agenten, wenn niemand anwesend ist, um eine Browser-Anmeldung zu genehmigen, oder wenn Sie Anmeldeinformationen wünschen, die Kanera als schreibgeschützt erzwingt. Erstellen Sie eins in Profileinstellungen -> API-Schlüssel, oder in Arbeitsbereichseinstellungen -> API wenn der Berechtigungsnachweis zu einem Arbeitsbereich und nicht zu einer Person gehören sollte. Siehe Kanera-API für den Unterschied.
kanera auth login --with-api-key
Bei gehostetem Kanera wird dadurch die Seite mit Ihren API-Schlüsseln geöffnet https://board.kanera.app/settings/api-keys, fordert zur Eingabe des Schlüssels auf, wobei das Terminalecho unterdrückt wird, sodass er nie in Ihrem Shell-Scrollback landet, überprüft ihn anhand von Kanera und speichert ihn.
Änderungen, die Sie mit einem persönlichen Schlüssel vornehmen, werden von Ihnen registriert, ohne dass dies der Fall ist über Daher ist eine Browser-Anmeldung die bessere Wahl, wenn Sie die Arbeit eines Agenten kennzeichnen möchten. Wählen Sie ein Schreibgeschützt Persönlicher Schlüssel, wenn der Berechtigungsnachweis für einen unbeaufsichtigten Agenten bestimmt ist. Die CLI meldet den von ihr gehaltenen Bereich und verweigert das Beenden von Schreibvorgängen mit einem eindeutigen Code, sodass ein Agent anhalten kann, anstatt es erneut zu versuchen.
kanera whoami # who am I, and what may this credential do?
kanera doctor # diagnose credentials, connectivity, and scope
Überspringen Sie in CI oder einer Agenten-Sandbox das gespeicherte Profil vollständig und legen Sie es fest KANERA_API_KEY.
Überprüfen Sie einen Zeitplan
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
Verwenden Sie genau einen Gültigkeitsbereich: ein Board-Positionsargument oder --workspaceId. Der Lesevorgang gibt die zurück Zeitachse Plandaten der Engine, Arbeitstagsdauer und Pufferzeit, kritische Karten, Konflikte, voraussichtliches Ende und Verrechnung mit dem spätesten Fälligkeitsdatum. Das Update ändert gespeicherte Daten und erfordert Schreibzugriff; Nachfolger werden nicht automatisch verschoben. Lesen Sie den Zeitplan erneut, nachdem Sie die Daten geändert haben.
kanera my-day --json umfasst Terminkonflikte, kritische Arbeiten und verpasste geplante Starts; kanera portfolio --json gibt das unterstützte Cross-Board-Rollup zurück, einschließlich des Zeitplanzustands pro Board. Für Ereignisabonnements ist ein gehosteter HTTP-MCP-Client erforderlich. Sie werden nicht vom stdio-Transport der CLI bereitgestellt.
Alltägliche Befehle
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
Kartenargumente akzeptieren einen Kartenschlüssel wie z MKT-42, eine Karten-ID oder eine kanonische Karten-URL, damit Sie alles einfügen können, was Sie gerade vor sich haben. Datumsargumente werden akzeptiert YYYY-MM-DD oder Phrasen wie "tomorrow 1pm" oder "next friday", lesen Sie die Zeitzone Ihres Profils ein: kanera card update MKT-42 --changes.dueDateLocalDate "friday 3pm".
kanera commands listet alles auf, was die CLI tun kann, und funktioniert, bevor Sie sich anmelden. kanera commands --json ist der maschinenlesbare Katalog, den ein Agent verwendet, um den Rest zu entdecken.
Die komplette Werkzeugoberfläche
Die oben genannten Befehle sind ergonomische Verknüpfungen über die MCP-Tool-Ebene von Kanera – dieselben Tools, die ein KI-Agent über MCP sieht. Alles ohne Verknüpfung ist weiterhin erreichbar:
kanera call cards.bulk_move --boardId "$BOARD" --cardIds[] MKT-42 --cardIds[] MKT-43 --listId "$LIST"
kanera help cards.bulk_move
Da die CLI die Tool-Ebene direkt liest, anstatt die öffentliche API erneut zu implementieren, kann ihre Befehlsoberfläche nicht von dem abweichen, was Agenten sehen, und ein neu hinzugefügtes Tool kann am Tag der Auslieferung über die Shell aufgerufen werden.
Bretttrenner
Erstellen Sie eine betitelte, optional farbige Trennlinie und positionieren Sie sie relativ zu einer Karte oder einer anderen Trennlinie:
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"
Für eine Listenkante übergeben Sie --anchor.side after --anchor.item null für die Spitze bzw --anchor.side before --anchor.item null für den Boden. Durch das Löschen des Trennzeichens werden keine Karten verändert. kanera card move akzeptiert den gleichen Ankertyp, sodass Karten unmittelbar vor oder nach einem Trennzeichen platziert werden können.
Kartenbeziehungen
Diese Befehle lesen sich von links nach rechts: Die erste Karte blockiert die zweite. Beide müssen zum selben Arbeitsbereich gehören.
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
Für die umgekehrte Richtung oder mehrere Ziele verwenden Sie das zugrunde liegende Tool:
kanera call cards.set_relations --cardId WEB-18 --direction blocked_by \
--otherCardIds[] MKT-42 --otherCardIds[] MKT-43
Pass --remove true um die ausgewählten Beziehungen zu entfernen. Inspizieren failed und notAttemptedCardIds auf ein Teilergebnis: Erfolgreiche Ergänzungen bleiben gespeichert, wenn ein anderes Ziel abgelehnt wird. Ein Ergebnis mit relationsUnavailable Namen erfolgreich schreibt ein addedCardIds oder removedCardIds als der letzte Lesevorgang fehlschlug. Neben Ablehnungen pro Karte werden auch erfolgreiche Entfernungen gemeldet. Siehe Kartenbeziehungen und Blockierung für Berechtigungen, Übergaben und Abschlusswarnungen.
Abhängigkeitsdiagramme
Benutzen kanera deps um Voraussetzungen und nachgelagerte Arbeiten in einem Aufruf zu lesen:
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
Übergeben Sie genau einen Bereich. Ein Kartenargument akzeptiert seinen Schlüssel, seine UUID oder seine kanonische URL. Kartenbezogene Ausgabe fügt hinzu focus mit direkt blockedBy / blocks IDs, transitiv upstream / downstream IDs in der Reihenfolge „Nächste zuerst“, relatedTo, und onMap. Zu den Karten gehören lesbare Board- und Listennamen sowie die Anzahl der aktiven/Off-Map-Blocker. Das Ergebnis ist auf 400 Karten und Berichte begrenzt truncated. Siehe die MCP-Grafikreferenz.
Argumente
Flags werden Tool-Argumenten zugeordnet und mithilfe des eigenen JSON-Schemas jedes Tools erzwungen, niemals durch das Aussehen des Werts – ein Kartenschlüssel kann numerisch und eine ID boolesch aussehen.
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"}}'
Ein Array-Argument akzeptiert auch ein JSON-Array, die einfachste Möglichkeit, eine Liste von Objekten zu übergeben. Dadurch werden in einem Aufruf eine Checkliste, ihre Elemente und eine Untercheckliste erstellt und in einem anderen Aufruf zwei Elemente vervollständigt:
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}}]'
Unbekannte Flags, fehlende erforderliche Argumente, fehlerhaft --json-argsund überschüssige Positionsargumente sind Verwendungsfehler. Die CLI verwirft niemals stillschweigend einen Operanden.
Ausgabe
| Flagge | Ausgabe |
|---|---|
| (keine) | Für Menschen lesbare Tabellen und Zusammenfassungen |
--json | A { ok, tool, data } Umschlag |
--quiet | Das nackte Ergebnis zum Weiterleiten jq |
Ausfälle gehen immer zu stderr, sogar in --json Modus, daher vermischt die Umleitung von stdout in eine Datei niemals einen Fehlerumschlag mit dem, was der Aufrufer für Ergebnisdaten hält.
Zu den ratenbegrenzten und vorübergehenden Ausfällen gehören retryable und wenn Kanera einen liefert, retryAfter.
Exit-Codes
| Code | Bedeutung |
|---|---|
0 | Erfolg |
1 | Die Anfrage ist fehlgeschlagen |
2 | Schlechte Verwendung |
3 | Kein gültiger Ausweis |
4 | Verboten – häufig eine schreibgeschützte Berechtigung oder keine Editor-Rolle im Forum |
5 | Nicht gefunden |
6 | Preis begrenzt |
4 unterscheidet sich bewusst von 1. Ein Agent, der über einen Schlüssel mit Lesebereich verfügt, muss außer „Das hat nicht funktioniert“ mitteilen, dass dies möglicherweise nicht möglich ist, und anhalten, anstatt es noch einmal zu versuchen.
Anmeldeinformationen und Profile
Auflösungsreihenfolge: --api-key, dann KANERA_API_KEY, dann ein gespeichertes Profil, das entweder eine Browser-Anmeldung oder einen API-Schlüssel enthält. Ein expliziter Schlüssel gewinnt immer, sodass ein CI-Job niemals über die persönliche Anmeldung eines Entwicklers ausgeführt wird.
Profile leben in ~/.config/kanera/config.json, geschrieben mit Modus 600. Mit benannten Profilen kann eine Maschine mehrere Identitäten besitzen:
kanera auth login --profile agent --api-key "kanera_u_live_..."
kanera --profile agent work --json
| Befehl | Zweck |
|---|---|
kanera auth login | Melden Sie sich über den Browser an (--with-api-key oder --api-key für einen Schlüssel) |
kanera auth status | Zeigen Sie die aktiven Anmeldeinformationen und ihren Umfang an |
kanera auth list | Gespeicherte Profile auflisten |
kanera auth token | Drucken Sie den aktiven API-Schlüssel aus, z KANERA_API_KEY=$(kanera auth token). Browser-Anmeldungen haben keinen Schlüssel zum Drucken. |
kanera auth logout | Entfernen Sie ein gespeichertes Profil und beenden Sie eine Browseranmeldung auf dem Server |
Ein Repository kann ein Profil auswählen, ohne ein Geheimnis zu bewahren .kanera/config.json:
{ "profile": "agent" }
Diese Datei kann keinen API-Ursprung festlegen. Origins erhalten die Inhaberanmeldeinformationen, daher darf ein ausgechecktes Repository nicht in der Lage sein, diese umzuleiten. Benutzen --url, KANERA_PUBLIC_API_URL, oder der mit dem Profil während gespeicherte Ursprung auth login. Nicht-Loopback-Ursprünge müssen HTTPS verwenden.
Aktualisierungen
Die CLI überprüft npm höchstens einmal täglich auf eine neuere Version. Wenn es eines findet, fragt es nach Abschluss Ihres Befehls:
A new Kanera CLI is available: 1.7.0 → 1.8.0
Update now? [y/N]
Antwort y laufen npm install --global @kanera/cli@<version>. Bei jeder anderen Antwort wird das Update übersprungen. Die CLI fragt einen Tag lang nicht erneut nach und gibt den Befehl aus, damit Sie später aktualisieren können.
Die CLI fragt nur dann, wenn sich eine Person an einem interaktiven Terminal befindet. Es wird nie eingecheckt oder nachgefragt --json oder --quiet Modus, wenn Eingabe oder Ausgabe kein Terminal ist (was Agenten, Skripte und Pipes abdeckt), wann CI eingestellt ist, oder wenn Sie es durchlaufen lassen npx, das seine eigene Kopie abruft. Set KANERA_NO_UPDATE_CHECK=1 um die Prüfung ganz auszuschalten.
Selbstgehostete Kanera
Eine Browser-Anmeldung ist an die MCP-Adresse Ihrer Bereitstellung gebunden, also übergeben Sie sie bei der Anmeldung:
kanera auth login --mcp-url https://your-kanera.example/mcp
Oder einstellen KANERA_MCP_URL. Die CLI liest die OAuth-Metadaten des MCP-Servers, um Ihre Kanera-Anmeldeseite zu finden, sodass nichts weiter konfiguriert werden muss.
Richten Sie für einen API-Schlüssel die CLI stattdessen auf Ihre öffentliche API und er wird mit dem Profil gespeichert:
kanera auth login --with-api-key --url https://api.your-kanera.example
Die CLI kann anhand ihres API-Ursprungs nicht erkennen, wo sich eine selbstgehostete Web-App befindet, sodass mit einem API-Schlüssel kein Browser geöffnet wird. Erstellen Sie den Schlüssel in Ihrer Kanera-Web-App unten Einstellungen -> API-Schlüssel, und fügen Sie es dann an der Eingabeaufforderung ein.
Oder einstellen KANERA_PUBLIC_API_URL pro Befehl. kanera doctor meldet den Endpunkt, den es aufgelöst hat. Dies ist normalerweise der schnellste Weg, einen falsch konfigurierten Ursprung zu finden.
Verwenden Sie es von einem KI-Agenten
Zwei Möglichkeiten, und sie ergänzen sich.
Als Shell-Tool. Installieren Sie die CLI, geben Sie dem Agenten einen schreibgeschützten Schlüssel und lassen Sie ihn Befehle ausführen. kanera setup schreibt die Anweisungen, die der Agent benötigt:
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 ist idempotent, sodass bei einer erneuten Ausführung nach einem Upgrade keine doppelten Abschnitte in einer Datei gestapelt werden, die Sie auch manuell bearbeiten. Hinzufügen --global zu setup claude für Ihr Konto statt für ein Projekt zu installieren.
Wenn der Agent bereits über verbundene Kanera MCP-Tools verfügt, verwenden Sie diese anstelle der CLI. Bei beiden Transportarten sollten unterstützte Kartenlesevorgänge und -aktualisierungen nicht auf die Browserautomatisierung zurückgreifen, nur weil Kanera auch über eine Webschnittstelle verfügt.
Als MCP-Server. kanera mcp stellt dieselben Tools über stdio MCP bereit und verwendet dabei die Anmeldeinformationen, die Sie bereits gespeichert haben:
{
"mcpServers": {
"kanera": {
"command": "kanera",
"args": ["mcp"]
}
}
}
Das bedeutet eins kanera auth login deckt sowohl Ihr Terminal als auch Ihren MCP-Client ab, anstelle eines zweiten Anmeldeinformationen, der an einer zweiten Stelle konfiguriert wird. Mit einer Browser-Anmeldung, kanera mcp leitet Ihren Kanera MCP-Server weiter und erneuert das Token während der Ausführung. Es spricht sowohl das aktuelle MCP-Protokoll als auch die früheren Versionen, sodass es von jedem MCP-Host gestartet werden kann. Veranstaltungsabonnements werden nicht über stdio angeboten, da ein lokaler Host keinen gehosteten Rückruf hat, an den er zustellen kann. Wenn Ihr Client Remote-MCP mit OAuth selbst unterstützt, können Sie ihn auch direkt verbinden; siehe Verbinden Sie Kanera mit Ihrem KI-Agenten.
Plananforderungen
Browser-Anmeldungen und persönliche API-Schlüssel funktionieren bei jedem gehosteten Plan, einschließlich Free, und beim selbst gehosteten Kanera gibt es keine Planprüfungen. Arbeitsbereichs- und Board-API-Schlüssel erforderlich Pro oder die Pro-Testversion; Wenn eine gehostete Organisation zu Free wechselt, werden sie widerrufen, und kanera Befehle, die einen verwenden, schlagen mit dem Exit-Code fehl 3 oder 4 bis der Plan wiederhergestellt ist. Anfragen folgen dem API-Ratenbegrenzungen der Organisation des Vorstands, und die CLI wartet und versucht es erneut, wenn sie kurz darüber hinweg ist.