Pular para o conteúdo principal

Visão Geral da Copera CLI

copera é a interface de linha de comando oficial da Copera. Use-a para trabalhar com boards, tabelas, linhas, docs, arquivos do drive, channels, notificações e dados do workspace — direto do seu terminal, de um script ou de um agente de IA de programação.

A CLI foi feita para dois públicos:

  • Usuários avançados que preferem o teclado à interface, querem automatizar trabalho repetitivo ou rodar a Copera de um shell remoto.
  • Agentes de IA de programação (Claude Code, Cursor, Codex e outros) que executam ações reais e auditáveis no seu workspace em seu nome.

Toda ação roda como o usuário por trás do token — suas permissões são respeitadas, e toda mudança é totalmente reversível no app.

informação

A CLI envolve a Copera Public API. Sua URL base é https://api.copera.ai/public/v1. Se você preferir chamar a API diretamente, ou conectar um cliente de IA via MCP, veja a Visão Geral do MCP.

Instalação​

macOS / Linux​

Rode isto no seu terminal:

curl -fsSL https://cli.copera.ai/install.sh | bash

Por padrão, o instalador grava o binário copera em /usr/local/bin/copera. Se esse diretório exigir permissões elevadas, o script solicita sudo.

Para instalar uma versão específica:

VERSION=0.1.0 curl -fsSL https://cli.copera.ai/install.sh | bash

Windows​

Abra o PowerShell e rode:

irm https://cli.copera.ai/install.ps1 | iex

Você não precisa rodar o PowerShell como Administrador — isso instala o copera.exe no seu perfil de usuário. Feche e reabra o PowerShell, depois verifique:

copera version

Para fixar uma versão específica:

$env:VERSION = "0.1.0"; irm https://cli.copera.ai/install.ps1 | iex

Se preferir instalar manualmente: baixe o zip para Windows AMD64 da versão desejada na CDN da Copera CLI, extraia o copera.exe, mova-o para um diretório no seu PATH (como %LOCALAPPDATA%\Microsoft\WindowsApps), depois abra uma nova janela do PowerShell e rode copera version.

A partir do código-fonte​

Se você tem o Go instalado:

go install github.com/copera/copera-cli/cmd/copera@latest

Atualização​

Atualize uma instalação existente a qualquer momento:

copera update                  # atualiza para a versão mais recente
copera update --version 1.2.0  # fixa em uma versão específica
copera update --force          # pula o prompt de confirmação

Início rápido​

Faça login. O fluxo mais simples abre um navegador e imprime uma URL que você pode usar em qualquer lugar:

copera auth login

A CLI imprime uma URL da Copera, abre-a no seu navegador padrão quando possível e pede que você cole o token gerado de volta no terminal. A URL impressa está sempre disponível, então o mesmo fluxo funciona via SSH, no WSL ou em qualquer terminal onde o navegador talvez não abra automaticamente.

Se você já tem um token, pule o navegador:

copera auth login --token=cp_pat_xxx

Para CI, scripts e pipelines de agentes, uma variável de ambiente é a opção mais limpa:

export COPERA_CLI_AUTH_TOKEN="cp_pat_xxx"

Confirme a sessão:

copera auth status     # perfil ativo + de onde veio o token
copera auth whoami     # a quem o token pertence

Experimente alguns comandos:

copera boards list
copera docs tree
copera search "onboarding"

Para saída legível por máquina, adicione --json:

copera boards list --json

Veja Autenticação para tipos de token e fluxos de login, e Comandos para a referência completa de comandos.

Formatos de saída​

A CLI foi projetada para funcionar bem tanto em terminais interativos quanto em pipelines automatizados.

  • Quando o stdout é um TTY, a saída é uma tabela colorida e legível por humanos.
  • Quando o stdout não é um TTY (encadeado em outro comando, redirecionado para um arquivo ou rodando em CI), a saída assume JSON por padrão — segura para agentes por padrão.
  • --json força a saída em JSON mesmo em um terminal.
  • --output aceita auto (padrão), json, table ou plain.
  • --quiet / -q suprime mensagens informativas.
  • --no-input (e CI=true) desabilitam prompts interativos.
copera boards list                 # tabela em um terminal, JSON quando encadeado
copera boards list --json | jq '.[].name'
copera boards list --output plain  # um valor por linha, para scripts

Erros são emitidos no stderr como JSON estruturado, então a saída de sucesso permanece limpa:

{"error":"resource_not_found","message":"Board 'abc123' not found","suggestion":"Run 'copera boards list' to see accessible boards","transient":false}

transient: true significa que o erro permite nova tentativa; false significa que tentar de novo não vai ajudar.

Códigos de saída​

Os códigos de saída são estáveis, então scripts podem ramificar com base neles com segurança:

CódigoSignificado
0OK
1Erro genérico
2Erro de uso (flags inválidas, argumentos faltando)
3Não encontrado
4Erro de autenticação / permissão negada
5Conflito (ex.: um recurso que já existe)
6Limite de taxa atingido

Variáveis de ambiente​

VariávelDescrição
COPERA_CLI_AUTH_TOKENToken de API. Sobrepõe todos os arquivos de configuração.
COPERA_PROFILENome do perfil de configuração ativo (padrão: default).
COPERA_SANDBOXDefina como 1 para apontar para a API de desenvolvimento (api-dev.copera.ai).
COPERA_NO_UPDATE_CHECKDefina como 1 para desabilitar verificações de versão em segundo plano.
CIDefina como true para desabilitar prompts interativos e verificações de atualização.
NO_COLORDesabilita a saída colorida ANSI.

Veja Configuração para a lista completa, incluindo perfis e opções de arquivo de configuração.

Explore a documentação​

Autenticação

Tipos de token, os fluxos de login e como a CLI resolve as credenciais.

Comandos

A referência completa de comandos — boards, linhas, docs, drive, channels e mais.

Configuração

Perfis, IDs padrão, variáveis de ambiente e saída legível por máquina.

Servidor MCP

Conecte clientes de IA à mesma Public API via Model Context Protocol.

Relacionados​