Configuración

La CLI funciona sin ninguna configuración tras copera auth login, pero algunas pequeñas adiciones hacen que el uso diario sea mucho más fluido, especialmente al crear scripts o ejecutarla desde un agente de IA.

Jerarquía de archivos de configuración

La CLI lee la configuración de hasta tres archivos TOML. Cuando la misma opción aparece en más de uno, gana el archivo de mayor prioridad:

Prioridad	Archivo	Propósito
1	.copera.local.toml (directorio actual)	Secretos por desarrollador. Agrégalo a .gitignore.
2	.copera.toml (directorio actual)	Valores predeterminados compartidos del proyecto. Seguro de confirmar (sin tokens).
3	~/.copera.toml	Tu configuración personal, con todos los perfiles.

La variable de entorno COPERA_CLI_AUTH_TOKEN y el flag --token anulan los tres específicamente para el token. Consulta el orden completo de resolución del token.

Formato de archivo

Cada archivo es TOML. Un perfil agrupa un token con IDs de recursos predeterminados; una sección [output] y [cache] ajustan el comportamiento:

# Usa un perfil distinto de "default" sin pasar --profile cada vez.
# Anulado por COPERA_PROFILE o --profile.
default_profile = "work"

[profiles.default]
token      = "cp_pat_abc123..."  # never commit this
board_id   = "66abc123def456789012abcd"  # used when --board is omitted
table_id   = "66pqr012stu345678901vwxy"  # used when --table is omitted
row_id     = ""                  # used when --row is omitted
channel_id = ""                  # used when --channel is omitted
doc_id     = ""                  # used when --doc is omitted

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

[output]
format = "auto"   # auto | json | table | plain
color  = "auto"   # auto | always | never (also respects NO_COLOR)

[cache]
dir = ""          # default: system temp directory / copera-cli
ttl = "1h"        # how long to cache doc content

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

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

# Con board_id y table_id en el perfil activo
copera rows list

Perfiles

Cada bloque [profiles.<name>] contiene su propio token, board_id, table_id, row_id, channel_id y doc_id. Selecciona uno por comando o por shell: cuando omites --profile, la CLI usa default (o el default_profile establecido en tu configuración):

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

Configuración a nivel de proyecto

Para valores predeterminados compartidos del proyecto, confirma un .copera.toml en tu repositorio sin tokens:

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

Para secretos por desarrollador que no deberían confirmarse, usa .copera.local.toml y agrégalo a .gitignore:

[profiles.default]
token = "cp_pat_xxx"

Esta separación permite que todo un equipo comparta el mismo board y table predeterminados mientras cada desarrollador proporciona su propio token localmente.

Variables de entorno

Variable	Descripción
COPERA_CLI_AUTH_TOKEN	Token de API. Anula todo archivo de configuración.
COPERA_PROFILE	Nombre del perfil de configuración activo (predeterminado: default).
COPERA_SANDBOX	Establece en 1 para apuntar a la API de desarrollo.
COPERA_NO_UPDATE_CHECK	Establece en 1 para desactivar las comprobaciones de versión en segundo plano.
CI	Establece en true para desactivar los avisos interactivos y las comprobaciones de actualización.
NO_COLOR	Desactiva la salida de color ANSI.

Sandbox

Establece COPERA_SANDBOX=1 para apuntar la CLI al entorno de desarrollo de Copera en lugar de a producción. Esto cambia la URL base de la API a https://api-dev.copera.ai/public/v1 y apunta copera auth login a la aplicación web de desarrollo (https://dev.copera.ai):

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

Usa un perfil separado para las credenciales de sandbox para no mezclarlas con los tokens de producción.

Comprobaciones de actualización

De forma predeterminada, la CLI ejecuta una comprobación ligera en segundo plano de nuevas versiones y te avisa cuando hay una disponible. Desactívala cuando quieras ejecuciones totalmente silenciosas y deterministas:

COPERA_NO_UPDATE_CHECK=1 copera boards list

Las comprobaciones de actualización también se omiten automáticamente cuando CI=true, cuando --json o --quiet están establecidos, y para builds de desarrollo. Actualiza explícitamente en cualquier momento con copera update.

Caché

La CLI almacena en caché el contenido de los documentos en disco para evitar llamadas redundantes a la API.

• Ubicación predeterminada: tu directorio temporal del sistema, bajo copera-cli/. Anúlala con cache.dir en tu configuración.
• TTL predeterminado: 1 hora. Cámbialo con cache.ttl (p. ej. "30m", "6h").
• Inspecciona la caché con copera cache status; límpiala con copera cache clean.
• Omite la caché en una sola lectura con copera docs content <id> --no-cache.

copera cache status   # tamaño, recuento de archivos y ruta
copera cache clean    # limpiarla por completo

Salida legible por máquina

La CLI está pensada para integrarse en scripts y flujos de trabajo de agentes:

• Cuando stdout no es un TTY (canalizado, redirigido o en CI), la salida es JSON de forma predeterminada.
• --json fuerza la salida JSON incluso en una terminal.
• --output acepta auto, json, table o plain.
• --quiet / -q suprime los mensajes informativos.
• --no-input (y CI=true) desactivan los avisos interactivos.
• Los errores se emiten en stderr como JSON estructurado.

Códigos de salida

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 / permiso denegado
5	Conflicto (p. ej. un recurso que ya existe)
6	Límite de tasa alcanzado

Errores estructurados

Cuando algo falla, la CLI emite un error JSON en 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 puedes reintentar; false significa que el error es permanente y reintentar no ayudará.

Relacionado

• Visión general: instalación y configuración inicial.
• Autenticación: tipos de token, flujos de inicio de sesión y orden de resolución.
• Comandos: la referencia completa de comandos.