Configuración

La CLI funciona sin configuración alguna después de copera auth login, pero unos pocos ajustes hacen que el uso diario sea mucho más fluido — especialmente cuando estás escribiendo scripts o ejecutándola desde un agente de IA.

Perfiles

Los perfiles agrupan un token junto con IDs de recursos predeterminados (como un board_id y table_id predeterminados). Viven en ~/.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"

Una vez configurados los valores predeterminados, los comandos se acortan:

# Sin valores predeterminados
copera rows list --board 66ghi... --table 66pqr...

# Con valores predeterminados
copera rows list

Cambia de perfil por comando o por shell:

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

Configuración a nivel de proyecto

Para valores predeterminados compartidos del proyecto, haz commit de un .copera.toml en tu repositorio (sin tokens — seguro para hacer commit):

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

Para secretos por desarrollador que no deberían incluirse en el commit, usa .copera.local.toml y añádelo a .gitignore:

[profiles.default]
token = "cp_pat_xxx"

La CLI sube por el árbol de directorios en busca de estos archivos, así que se aplican a cada comando ejecutado dentro del proyecto.

Salida legible por máquina

La CLI está diseñada para funcionar bien en scripts y flujos de trabajo de agentes:

• Cuando stdout no es un TTY (canalizado a otro comando, redirigido a un archivo o ejecutado en CI), la salida predeterminada es JSON.
• --json fuerza la salida en JSON incluso en una terminal.
• --output acepta auto, json, table o plain.
• --quiet / -q suprime los mensajes informativos — útil para scripts que solo quieren el resultado.
• Los errores se emiten en stderr como JSON estructurado.
• --no-input y CI=true deshabilitan los prompts interactivos (sin preguntas de "¿estás seguro?").

Códigos de salida

Los códigos de salida son estables, así que los scripts pueden ramificar sobre ellos con seguridad:

Código	Significado
0	OK
1	Error genérico
2	Error de uso (flags incorrectos, argumentos faltantes)
3	No encontrado
4	Error de autenticación
5	Conflicto (p. ej., una fila que ya existe)
6	Límite de tasa alcanzado

Errores estructurados

Cuando algo falla, la CLI emite un error en JSON en stderr como este:

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

transient: true significa "puedes reintentar" — false significa que el error es permanente y reintentar no servirá de nada.

Variables de entorno

Variable	Descripción
COPERA_CLI_AUTH_TOKEN	Token de API. Anula todos los archivos de configuración.
COPERA_PROFILE	Nombre del perfil de configuración activo (predeterminado: default).
COPERA_NO_UPDATE_CHECK	Establece en 1 para deshabilitar las comprobaciones de versión en segundo plano.
COPERA_SANDBOX	Establece en 1 para usar la API de desarrollo.
CI	Establece en true para deshabilitar los prompts interactivos y las comprobaciones de actualización.
NO_COLOR	Deshabilita la salida con color ANSI.

Relacionado

• Resumen — Instalación y configuración inicial.
• Autenticación — Tipos de token y flujos de inicio de sesión.
• Comandos comunes — Referencia rápida de cada comando.
• Documentación para desarrolladores de Copera — Referencia completa de la API y el SDK.