Configuração

A CLI funciona sem nenhuma configuração depois do copera auth login, mas algumas pequenas adições tornam o dia a dia bem mais fluido — especialmente quando você está automatizando coisas ou rodando ela a partir de um agente de IA.

Perfis

Perfis agrupam um token junto com IDs padrão de recursos (como um board_id e table_id padrão). Eles ficam em ~/.copera.toml:

default_profile = "work"

[profiles.default]
token    = "cp_pat_abc123..."
board_id = "66abc123def456789012abcd"

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

[output]
format = "auto"   # auto | json | table | plain

[cache]
ttl = "1h"

Uma vez configurados, os comandos encurtam:

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

# Com padrões
copera rows list

Troque de perfil por comando ou por shell:

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

Configuração por projeto

Para padrões compartilhados do projeto, commite um .copera.toml no repositório (sem tokens — seguro para commitar):

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

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

[profiles.default]
token = "cp_pat_xxx"

A CLI sobe pela árvore de diretórios procurando esses arquivos, então eles valem para todo comando rodado dentro do projeto.

Saída legível por máquina

A CLI foi desenhada para funcionar bem em scripts e fluxos de agentes:

• Quando stdout não é um TTY (redirecionado para outro comando, para um arquivo, ou rodando em CI), a saída padrão é JSON.
• --json força saída JSON mesmo no terminal.
• --output aceita auto, json, table ou plain.
• --quiet / -q suprime mensagens informativas — útil para scripts que só querem o resultado.
• Erros são emitidos em stderr como JSON estruturado.
• --no-input e CI=true desligam prompts interativos (sem perguntas "tem certeza?").

Códigos de saída

Os exit codes são estáveis, então scripts podem ramificar com segurança:

Código	Significado
0	OK
1	Erro genérico
2	Erro de uso (flags erradas, argumentos faltando)
3	Não encontrado
4	Erro de autenticação
5	Conflito (ex. uma linha que já existe)
6	Rate limit

Erros estruturados

Quando algo falha, a CLI emite um JSON de erro em stderr assim:

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

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

Variáveis de ambiente

Variável	Descrição
COPERA_CLI_AUTH_TOKEN	Token da API. Sobrescreve todos os arquivos de configuração.
COPERA_PROFILE	Nome do perfil de configuração ativo (padrão: default).
COPERA_NO_UPDATE_CHECK	Defina 1 para desligar checagens de versão em segundo plano.
COPERA_SANDBOX	Defina 1 para usar a API de desenvolvimento.
CI	Defina true para desligar prompts interativos e checagens de atualização.
NO_COLOR	Desliga saída ANSI colorida.

Relacionado

• Visão Geral — Instalação e primeira configuração.
• Autenticação — Tipos de token e fluxos de login.
• Comandos Comuns — Referência rápida de todos os comandos.
• Docs do Desenvolvedor Copera — Referência completa da API e SDK.