Configurazione

La CLI funziona senza configurazione dopo copera auth login, ma alcune piccole aggiunte rendono l'uso quotidiano molto più fluido — soprattutto in scripting o quando la usi da un agente IA.

Gerarchia dei file di config

La CLI legge la configurazione da fino a tre file TOML. Quando la stessa impostazione compare in più di uno, vince il file con priorità più alta:

Priority	File	Purpose
1	.copera.local.toml (current directory)	Per-developer secrets. Add to .gitignore.
2	.copera.toml (current directory)	Shared project defaults. Safe to commit (no tokens).
3	~/.copera.toml	Your personal config, with all profiles.

La variabile d'ambiente COPERA_CLI_AUTH_TOKEN e il flag --token sovrascrivono tutti e tre specificamente per il token. Vedi l'ordine completo di risoluzione del token.

Formato del file

Ogni file è TOML. Un profilo raggruppa un token con ID di risorse predefiniti; le sezioni [output] e [cache] regolano il comportamento:

# Use a non-"default" profile without passing --profile every time.
# Overridden by COPERA_PROFILE or --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 volta configurati i default, i comandi si accorciano:

# Without defaults
copera rows list --board 66ghi... --table 66pqr...

# With board_id and table_id in the active profile
copera rows list

Profili

Ogni blocco [profiles.<name>] contiene il proprio token, board_id, table_id, row_id, channel_id e doc_id. Selezionane uno per comando o per shell — quando ometti --profile, la CLI usa default (o il default_profile impostato nella config):

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

Config a livello di progetto

Per i default di progetto condivisi, committa un .copera.toml nel repo senza token:

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

Per i secret per-sviluppatore che non devono essere committati, usa .copera.local.toml e aggiungilo a .gitignore:

[profiles.default]
token = "cp_pat_xxx"

Questa separazione consente a un intero team di condividere la stessa board e table predefinite mentre ogni sviluppatore fornisce il proprio token in locale.

Variabili d'ambiente

Variable	Description
COPERA_CLI_AUTH_TOKEN	API token. Overrides every config file.
COPERA_PROFILE	Active config profile name (default: default).
COPERA_SANDBOX	Set to 1 to target the development API.
COPERA_NO_UPDATE_CHECK	Set to 1 to disable background version checks.
CI	Set to true to disable interactive prompts and update checks.
NO_COLOR	Disable ANSI color output.

Sandbox

Imposta COPERA_SANDBOX=1 per puntare la CLI all'ambiente di sviluppo di Copera invece che alla produzione. Questo cambia l'URL di base dell'API in https://api-dev.copera.ai/public/v1 e punta copera auth login all'app web di dev (https://dev.copera.ai):

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

Usa un profilo separato per le credenziali sandbox così non le mescoli con i token di produzione.

Controlli di aggiornamento

Per impostazione predefinita la CLI esegue un controllo leggero in background per nuove versioni e ti avvisa quando ne è disponibile una. Disabilitalo quando vuoi esecuzioni completamente silenziose e deterministiche:

COPERA_NO_UPDATE_CHECK=1 copera boards list

I controlli di aggiornamento vengono anche saltati automaticamente quando CI=true, quando sono impostati --json o --quiet, e per le build di sviluppo. Aggiorna esplicitamente in qualsiasi momento con copera update.

Caching

La CLI mette in cache il contenuto dei documenti su disco per evitare chiamate API ridondanti.

• Posizione predefinita: la directory temp di sistema, sotto copera-cli/. Sovrascrivila con cache.dir nella config.
• TTL predefinito: 1 ora. Cambialo con cache.ttl (ad es. "30m", "6h").
• Ispeziona la cache con copera cache status; svuotala con copera cache clean.
• Ignora la cache per una singola lettura con copera docs content <id> --no-cache.

copera cache status   # size, file count, and path
copera cache clean    # clear it entirely

Output leggibile dalle macchine

La CLI è pensata per inserirsi in script e workflow di agenti:

• Quando stdout non è un TTY (pipato, reindirizzato o in CI), l'output predefinito è JSON.
• --json forza l'output JSON anche in un terminale.
• --output accetta auto, json, table o plain.
• --quiet / -q sopprime i messaggi informativi.
• --no-input (e CI=true) disabilitano i prompt interattivi.
• Gli errori vengono emessi su stderr come JSON strutturato.

Codici di uscita

Code	Meaning
0	OK
1	Generic error
2	Usage error (bad flags, missing arguments)
3	Not found
4	Auth error / permission denied
5	Conflict (e.g. a resource that already exists)
6	Rate limited

Errori strutturati

Quando qualcosa fallisce, la CLI emette un errore JSON su stderr:

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

transient: true significa che puoi ritentare; false significa che l'errore è permanente e ritentare non aiuterà.

Correlati

• Panoramica — installazione e setup iniziale.
• Autenticazione — tipi di token, flussi di login e ordine di risoluzione.
• Comandi — il riferimento completo ai comandi.