Configuração

A CLI funciona com zero configuração depois de copera auth login, mas alguns pequenos acréscimos tornam o uso diário muito mais fluido — especialmente ao criar scripts ou rodá-la a partir de um agente de IA.

Hierarquia de arquivos de configuração

A CLI lê a configuração de até três arquivos TOML. Quando o mesmo ajuste aparece em mais de um, o arquivo de maior prioridade vence:

Prioridade	Arquivo	Propósito
1	.copera.local.toml (diretório atual)	Segredos por desenvolvedor. Adicione ao .gitignore.
2	.copera.toml (diretório atual)	Padrões compartilhados do projeto. Seguro de versionar (sem tokens).
3	~/.copera.toml	Sua configuração pessoal, com todos os perfis.

A variável de ambiente COPERA_CLI_AUTH_TOKEN e a flag --token sobrepõem os três especificamente para o token. Veja a ordem completa de resolução do token.

Formato do arquivo

Cada arquivo é TOML. Um perfil agrupa um token com IDs de recursos padrão; seções [output] e [cache] ajustam o comportamento:

# Use um perfil diferente de "default" sem passar --profile toda vez.
# Sobreposto por COPERA_PROFILE ou --profile.
default_profile = "work"

[profiles.default]
token      = "cp_pat_abc123..."  # nunca versione isto
board_id   = "66abc123def456789012abcd"  # usado quando --board é omitido
table_id   = "66pqr012stu345678901vwxy"  # usado quando --table é omitido
row_id     = ""                  # usado quando --row é omitido
channel_id = ""                  # usado quando --channel é omitido
doc_id     = ""                  # usado quando --doc é omitido

[profiles.work]
token    = "cp_key_xyz789..."
board_id = "66ghi789jkl012345678mnop"

[output]
format = "auto"   # auto | json | table | plain
color  = "auto"   # auto | always | never (também respeita NO_COLOR)

[cache]
dir = ""          # padrão: diretório temporário do sistema / copera-cli
ttl = "1h"        # por quanto tempo armazenar o conteúdo dos docs em cache

Uma vez que os padrões estão configurados, os comandos encolhem:

# Sem padrões
copera rows list --board 66ghi... --table 66pqr...

# Com board_id e table_id no perfil ativo
copera rows list

Perfis

Cada bloco [profiles.<name>] guarda seus próprios token, board_id, table_id, row_id, channel_id e doc_id. Selecione um por comando ou por shell — quando você omite --profile, a CLI usa default (ou o default_profile definido na sua configuração):

copera boards list --profile work
COPERA_PROFILE=work copera boards list

Configuração no nível do projeto

Para padrões compartilhados do projeto, versione um .copera.toml no seu repositório sem tokens:

[profiles.default]
board_id = "66abc123def456789012abcd"
table_id = "66pqr012stu345678901vwxy"

Para segredos por desenvolvedor que não devem ser versionados, use .copera.local.toml e adicione-o ao .gitignore:

[profiles.default]
token = "cp_pat_xxx"

Essa divisão permite que um time inteiro compartilhe o mesmo board e tabela padrão enquanto cada desenvolvedor fornece seu próprio token localmente.

Variáveis de ambiente

Variável	Descrição
COPERA_CLI_AUTH_TOKEN	Token de API. Sobrepõe todos os arquivos de configuração.
COPERA_PROFILE	Nome do perfil de configuração ativo (padrão: default).
COPERA_SANDBOX	Defina como 1 para apontar para a API de desenvolvimento.
COPERA_NO_UPDATE_CHECK	Defina como 1 para desabilitar verificações de versão em segundo plano.
CI	Defina como true para desabilitar prompts interativos e verificações de atualização.
NO_COLOR	Desabilita a saída colorida ANSI.

Sandbox

Defina COPERA_SANDBOX=1 para apontar a CLI para o ambiente de desenvolvimento da Copera em vez de produção. Isso troca a URL base da API para https://api-dev.copera.ai/public/v1 e aponta o copera auth login para o app web de desenvolvimento (https://dev.copera.ai):

COPERA_SANDBOX=1 copera auth login
COPERA_SANDBOX=1 copera boards list

Use um perfil separado para credenciais de sandbox para não misturá-las com tokens de produção.

Verificações de atualização

Por padrão, a CLI roda uma verificação leve em segundo plano por novas versões e avisa quando há uma disponível. Desabilite-a quando você quiser execuções totalmente silenciosas e determinísticas:

COPERA_NO_UPDATE_CHECK=1 copera boards list

As verificações de atualização também são puladas automaticamente quando CI=true, quando --json ou --quiet está definido, e para builds de desenvolvimento. Atualize explicitamente a qualquer momento com copera update.

Cache

A CLI armazena em cache o conteúdo dos documentos em disco para evitar chamadas de API redundantes.

• Localização padrão: o diretório temporário do seu sistema, em copera-cli/. Sobreponha-a com cache.dir na sua configuração.
• TTL padrão: 1 hora. Altere-o com cache.ttl (ex.: "30m", "6h").
• Inspecione o cache com copera cache status; limpe-o com copera cache clean.
• Ignore o cache em uma única leitura com copera docs content <id> --no-cache.

copera cache status   # tamanho, contagem de arquivos e caminho
copera cache clean    # limpa tudo

Saída legível por máquina

A CLI foi feita para se encaixar em scripts e workflows de agentes:

• Quando o stdout não é um TTY (encadeado, redirecionado ou em CI), a saída assume JSON por padrão.
• --json força a saída em JSON mesmo em um terminal.
• --output aceita auto, json, table ou plain.
• --quiet / -q suprime mensagens informativas.
• --no-input (e CI=true) desabilitam prompts interativos.
• Erros são emitidos no stderr como JSON estruturado.

Códigos de saída

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

Erros estruturados

Quando algo falha, a CLI emite um erro JSON no stderr:

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

transient: true significa que você pode tentar de novo; false significa que o erro é permanente e tentar de novo não vai ajudar.

Relacionados

• Visão Geral — instalação e configuração inicial.
• Autenticação — tipos de token, fluxos de login e ordem de resolução.
• Comandos — a referência completa de comandos.