Kanera CLI
@kanera/cli coloca Kanera em seu terminal para que você possa encontrar cartões, gerenciar trabalho e automatizar tarefas a partir de scripts de shell. Agentes de codificação de IA que podem executar comandos shell também podem usá-lo, sem configuração de cliente MCP e sem servidor de longa execução.
Instalar
Requer Node.js 22 ou mais recente. Execute este comando em seu terminal para instalar o kanera comando globalmente:
npm install --global @kanera/cli
O pacote publicado não possui dependências de tempo de execução. Confirme se o comando está disponível:
kanera commands
Para experimentar sem instalar:
npx @kanera/cli commands
Autenticar
Faça login através do seu navegador:
kanera auth login
auth login usa o fluxo do dispositivo OAuth, da mesma forma que Claude e Codex se conectam. Ele imprime um link e um código curto, abre o link no seu navegador e termina sozinho assim que você aprovar. Verifique se o código na página corresponde ao seu terminal antes de escolher Permitir acesso. Por SSH ou em uma máquina headless, abra o link em qualquer dispositivo; passar --no-browser para pular o lançamento de um.
A CLI armazena então um token de acesso de curta duração e um token de atualização e os renova automaticamente. O login aparece em Configurações -> Agentes de IA como Kanera CLI (nome do seu computador), e as alterações feitas são marcadas com esse nome no histórico do cartão. Revogue lá ou execute kanera auth logout, que também termina no servidor.
Nomeie o agente
Quando um agente de IA comanda a CLI, nomeie-o no login para que seu trabalho seja rotulado como daquele agente:
kanera auth login --agent "Claude Code"
O login então aparece como Código Claude (Kanera CLI no nome do seu computador) na tela de consentimento, em Configurações -> Agentes de IA, e como via Código Claude (Kanera CLI em…) em cada comentário, alteração de cartão, notificação e execução do agente. KANERA_AGENT_NAME define o mesmo nome do ambiente. O nome é fixo durante o período de login, portanto, dê a cada agente seu próprio perfil com --profile quando vários compartilham uma máquina. --agent não se aplica a chaves de API, porque o trabalho realizado com uma chave pessoal é registrado como você.
Use uma chave de API
Use uma chave de API para CI, tarefas cron e agentes autônomos, onde ninguém está presente para aprovar o login do navegador ou quando você deseja uma credencial que Kanera impõe como somente leitura. Crie um em Configurações de perfil -> Chaves de API, ou em Configurações do espaço de trabalho -> API quando a credencial deve pertencer a um espaço de trabalho e não a uma pessoa. Veja API Kanera pela diferença.
kanera auth login --with-api-key
No Kanera hospedado, isso abre sua página de chaves de API em https://board.kanera.app/settings/api-keys, solicita a chave com o eco do terminal suprimido para que ela nunca caia na rolagem do shell, verifica-a no Kanera e armazena-a.
As alterações feitas com uma chave pessoal são registradas como você, sem através de crachá, portanto, o login no navegador é a melhor opção quando você deseja que o trabalho de um agente seja rotulado. Escolha um Somente leitura chave pessoal quando a credencial for para um agente autônomo. A CLI relata o escopo que está mantendo e recusa a saída de gravações com um código distinto para que um agente possa parar em vez de tentar novamente.
kanera whoami # who am I, and what may this credential do?
kanera doctor # diagnose credentials, connectivity, and scope
No CI ou em uma sandbox do agente, ignore completamente o perfil armazenado e defina KANERA_API_KEY.
Inspecione uma programação de linha do tempo
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
Use exatamente um escopo: um argumento posicional do quadro ou --workspaceId. A leitura retorna o Linha do tempo datas planejadas do motor, duração e folga do dia útil, cartões críticos, conflitos, término projetado e atraso em relação ao último vencimento. A atualização altera as datas salvas e requer acesso de gravação; ele não move sucessores automaticamente. Releia a programação após alterar as datas.
kanera my-day --json inclui conflitos de cronograma, trabalho crítico e inícios planejados perdidos; kanera portfolio --json retorna o rollup cruzado compatível, incluindo a integridade do cronograma por quadro. As assinaturas de eventos exigem um cliente HTTP MCP hospedado; eles não são fornecidos pelo transporte stdio da CLI.
Comandos diários
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
Argumentos de cartão aceitam uma chave de cartão como MKT-42, um ID de cartão ou um URL canônico de cartão, para que você possa colar o que tiver à sua frente. Argumentos de data aceitos YYYY-MM-DD ou frases como "tomorrow 1pm" ou "next friday", leia no fuso horário do seu perfil: kanera card update MKT-42 --changes.dueDateLocalDate "friday 3pm".
kanera commands lista tudo o que a CLI pode fazer e funciona antes de você efetuar login. kanera commands --json é o catálogo legível por máquina que um agente usa para descobrir o resto.
A superfície completa da ferramenta
Os comandos mencionados acima são atalhos ergonômicos na camada de ferramentas MCP do Kanera – as mesmas ferramentas que um agente de IA vê no MCP. Qualquer coisa sem um atalho ainda estará acessível:
kanera call cards.bulk_move --boardId "$BOARD" --cardIds[] MKT-42 --cardIds[] MKT-43 --listId "$LIST"
kanera help cards.bulk_move
Como a CLI lê a camada de ferramentas diretamente, em vez de reimplementar a API pública, sua superfície de comando não pode se desviar do que os agentes veem, e uma ferramenta recém-adicionada pode ser chamada a partir do shell no dia em que for enviada.
Separadores de quadro
Crie um divisor com título opcionalmente colorido e posicione-o em relação a um cartão ou outro separador:
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"
Para uma borda de lista, passe --anchor.side after --anchor.item null para o topo ou --anchor.side before --anchor.item null para o fundo. A exclusão do separador não altera nenhum cartão. kanera card move aceita a mesma âncora digitada, portanto os cartões podem ser colocados imediatamente antes ou depois de um separador.
Relacionamentos de cartão
Esses comandos são lidos da esquerda para a direita: o primeiro cartão bloqueia o segundo. Ambos devem pertencer ao mesmo espaço de trabalho.
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
Para a direção inversa ou vários alvos, use a ferramenta subjacente:
kanera call cards.set_relations --cardId WEB-18 --direction blocked_by \
--otherCardIds[] MKT-42 --otherCardIds[] MKT-43
Passe --remove true para remover os relacionamentos selecionados. Inspecionar failed e notAttemptedCardIds em um resultado parcial: as adições bem-sucedidas permanecem salvas quando outro alvo é recusado. Um resultado com relationsUnavailable nomes bem sucedidos escrevem em addedCardIds ou removedCardIds quando a leitura final falhou. As remoções bem-sucedidas também são relatadas junto com as recusas por cartão. Veja Relacionamentos e bloqueios de cartões para permissões, transferências e avisos de conclusão.
Gráficos de dependência
Usar kanera deps para ler os pré-requisitos e o trabalho posterior em uma chamada:
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
Passe exatamente um escopo. Um argumento de cartão aceita sua chave, UUID ou URL canônico. A saída no escopo do cartão adiciona focus com direto blockedBy / blocks IDs, transitivos upstream / downstream IDs na primeira ordem mais próxima, relatedToe onMap. Os cartões incluem nomes legíveis de quadros e listas e contagens de bloqueadores ativos/fora do mapa. O resultado é limitado a 400 cartões e relatórios truncated. Veja a referência do gráfico MCP.
Argumentos
Os sinalizadores são mapeados nos argumentos da ferramenta e são forçados usando o próprio esquema JSON de cada ferramenta, nunca pela aparência do valor - uma chave de cartão pode parecer numérica e um ID pode parecer booleano.
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"}}'
Um argumento de array também aceita um array JSON, a maneira mais simples de passar uma lista de objetos. Isso cria uma lista de verificação, seus itens e uma sublista de verificação em uma chamada e, em seguida, completa dois itens em outra:
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}}]'
Sinalizadores desconhecidos, argumentos obrigatórios ausentes, mal formados --json-argse argumentos posicionais excedentes são erros de uso. A CLI nunca descarta silenciosamente um operando.
Saída
| Bandeira | Saída |
|---|---|
| (nenhum) | Tabelas e resumos legíveis por humanos |
--json | Um { ok, tool, data } envelope |
--quiet | O resultado básico, para canalizar para jq |
As falhas sempre vão para stderr, mesmo em --json modo, portanto, redirecionar stdout para um arquivo nunca mistura um envelope de erro com o que o chamador acredita serem dados de resultado.
Falhas com taxa limitada e transitórias incluem retryable e, quando Kanera fornece um, retryAfter.
Códigos de saída
| Código | Significado |
|---|---|
0 | Sucesso |
1 | A solicitação falhou |
2 | Mau uso |
3 | Nenhuma credencial válida |
4 | Proibido — geralmente uma credencial somente leitura ou nenhuma função de editor no quadro |
5 | Não encontrado |
6 | Taxa limitada |
4 é deliberadamente distinto de 1. Um agente que possui uma chave com escopo de leitura precisa dizer "Não posso fazer isso" além de "isso não funcionou" e parar em vez de tentar novamente.
Credenciais e perfis
Ordem de resolução: --api-key, então KANERA_API_KEYe, em seguida, um perfil armazenado, que contém um login do navegador ou uma chave de API. Uma chave explícita sempre vence, portanto, um trabalho de CI nunca passa pelo login pessoal do desenvolvedor.
Perfis residem em ~/.config/kanera/config.json, escrito com modo 600. Perfis nomeados permitem que uma máquina mantenha diversas identidades:
kanera auth login --profile agent --api-key "kanera_u_live_..."
kanera --profile agent work --json
| Comando | Objetivo |
|---|---|
kanera auth login | Faça login pelo navegador (--with-api-key ou --api-key para uma chave) |
kanera auth status | Mostrar a credencial ativa e seu escopo |
kanera auth list | Listar perfis armazenados |
kanera auth token | Imprima a chave API ativa, para KANERA_API_KEY=$(kanera auth token). Os logins do navegador não têm chave para imprimir. |
kanera auth logout | Remover um perfil armazenado e encerrar o login do navegador no servidor |
Um repositório pode selecionar um perfil sem manter um segredo, em .kanera/config.json:
{ "profile": "agent" }
Esse arquivo não pode definir uma origem de API. As origens recebem a credencial do portador, portanto, um repositório com check-out não deve ser capaz de redirecioná-lo. Usar --url, KANERA_PUBLIC_API_URL, ou a origem salva com o perfil durante auth login. As origens sem loopback devem usar HTTPS.
Atualizações
A CLI verifica o npm em busca de uma versão mais recente no máximo uma vez por dia. Quando encontra um, ele pergunta após o término do seu comando:
A new Kanera CLI is available: 1.7.0 → 1.8.0
Update now? [y/N]
Resposta y correr npm install --global @kanera/cli@<version>. Qualquer outra resposta ignora a atualização. A CLI não solicita novamente um dia e imprime o comando para que você possa atualizar mais tarde.
A CLI só pergunta quando uma pessoa está em um terminal interativo. Ele nunca verifica ou pergunta --json ou --quiet modo, quando a entrada ou saída não é um terminal (que abrange agentes, scripts e pipes), quando CI está definido ou quando você o executa npx, que busca sua própria cópia. Definir KANERA_NO_UPDATE_CHECK=1 para desligar totalmente a verificação.
Kanera auto-hospedada
O login do navegador está vinculado ao endereço MCP da sua implantação, portanto, transmita-o durante o login:
kanera auth login --mcp-url https://your-kanera.example/mcp
Ou definir KANERA_MCP_URL. A CLI lê os metadados OAuth do servidor MCP para encontrar sua página de login do Kanera, portanto, nada mais precisa ser configurado.
Para uma chave de API, aponte a CLI para sua API pública e ela será salva com o perfil:
kanera auth login --with-api-key --url https://api.your-kanera.example
A CLI não consegue dizer onde reside um aplicativo Web auto-hospedado a partir de sua origem de API, portanto, com uma chave de API, ele não abre um navegador. Crie a chave em seu aplicativo da web Kanera em Configurações -> Chaves APIe cole-o no prompt.
Ou definir KANERA_PUBLIC_API_URL por comando. kanera doctor relata o endpoint resolvido, que geralmente é a maneira mais rápida de encontrar uma origem mal configurada.
Use-o de um agente de IA
Duas maneiras, e elas são complementares.
Como uma ferramenta de shell. Instale a CLI, forneça ao agente uma chave somente leitura e deixe-o executar comandos. kanera setup escreve as instruções que o agente precisa:
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 é idempotente, portanto, executá-lo novamente após uma atualização não empilha seções duplicadas em um arquivo que você também edita manualmente. Adicionar --global para setup claude para instalar para sua conta em vez de um projeto.
Quando o agente já tiver conectado as ferramentas Kanera MCP, use-as em vez da CLI. Em qualquer um dos transportes, as leituras e atualizações de cartões suportadas não devem depender da automação do navegador apenas porque o Kanera também possui uma interface web.
Como um servidor MCP. kanera mcp serve as mesmas ferramentas no stdio MCP usando a credencial que você já armazenou:
{
"mcpServers": {
"kanera": {
"command": "kanera",
"args": ["mcp"]
}
}
}
Isto significa um kanera auth login abrange seu terminal e seu cliente MCP, em vez de uma segunda credencial configurada em segundo lugar. Com um login no navegador, kanera mcp retransmite seu servidor Kanera MCP e renova o token à medida que ele é executado. Ele fala tanto o protocolo MCP atual quanto as revisões anteriores, portanto qualquer host MCP pode iniciá-lo. Assinaturas de eventos não são oferecidos por stdio, pois um host local não possui retorno de chamada hospedado para entrega. Se o seu cliente suportar MCP remoto com o próprio OAuth, você também poderá conectá-lo diretamente; veja Conecte Kanera ao seu agente de IA.
Requisitos do plano
Os logins do navegador e as chaves de API pessoais funcionam em todos os planos hospedados, incluindo o Gratuito, e o Kanera auto-hospedado não tem verificações de plano. As chaves de API do espaço de trabalho e da quadro precisam Pro ou o teste Pro; se uma organização hospedada mudar para Gratuita, ela será revogada e kanera comandos usando uma falha com código de saída 3 ou 4 até que o plano seja restaurado. As solicitações seguem o Limites de taxa de API da organização do quadro, e a CLI espera e tenta novamente quando passa brevemente por cima deles.