Autenticazione

La Copera CLI ti fa accedere una sola volta e poi esegue ogni comando come te. Questa pagina copre i tipi di token, i flussi di login, i profili e come la CLI decide quale credenziale usare quando ne sono disponibili diverse.

Tipi di token

Copera emette due tipi di token:

• Personal Access Token (cp_pat_...) — legato al tuo account utente. Copre l'intera superficie della CLI ed è obbligatorio per i comandi docs, drive, notifications, search e workspace. In caso di dubbio, usa un PAT.
• Integration API Key (cp_key_...) — legata a un'integrazione anziché a un utente. Funziona solo per boards e channels.

suggerimento

Le operazioni su docs e drive richiedono sempre un Personal Access Token con le autorizzazioni workspace appropriate. Se vedi un errore di autenticazione su copera docs ... o copera drive ..., verifica di star usando un token cp_pat_....

Surface	cp_pat_ (Personal Access Token)	cp_key_ (Integration API Key)
Boards / tables / rows	Yes	Yes
Channels	Yes	Yes
Docs	Yes	No
Drive	Yes	No
Workspace / search / notifications	Yes	No

Flussi di login

Il modo più veloce per autenticarsi è il flusso guidato nel browser:

copera auth login

La CLI stampa un URL Copera, lo apre nel browser predefinito quando possibile e ti chiede di incollare il token generato nel terminale. L'URL stampato è sempre disponibile, quindi lo stesso flusso funziona su SSH, in WSL o in qualsiasi terminale in cui il browser potrebbe non aprirsi automaticamente.

Se hai già un token, puoi salvarlo direttamente:

Command	When to use it
copera auth login	You want the guided browser flow.
copera auth login --token=<value>	You already have a token and want to save it directly, without opening a browser.
copera auth login --token	You already have a token and want a masked paste prompt — no browser, and the token never lands in your shell history.

Una volta effettuato l'accesso, il token viene salvato in ~/.copera.toml e riutilizzato per ogni comando successivo.

Usare un token senza fare login

Per CI, script e agenti IA, preferisci una variabile d'ambiente — ha priorità su ogni file di config e non viene mai persistita su disco:

export COPERA_CLI_AUTH_TOKEN="cp_pat_xxx"

Su Windows PowerShell:

$env:COPERA_CLI_AUTH_TOKEN = "cp_pat_xxx"

Puoi anche passare un token per comando con --token, che batte ogni file di config ma ha priorità inferiore alla variabile d'ambiente:

copera boards list --token cp_pat_xxx

Ispezionare la sessione corrente

copera auth status     # active profile + where the token came from
copera auth whoami     # who the token belongs to

copera auth status è particolarmente utile quando qualcosa si comporta in modo imprevisto — segnala se la CLI ha preso un token dall'ambiente, da un file di config del progetto o dalla home directory:

{
  "profile": "default",
  "token_source": "environment variable COPERA_CLI_AUTH_TOKEN",
  "token": "cp_***...***xY2z",
  "configured": true
}

Esci

copera auth logout

Questo rimuove la credenziale salvata. Esegui di nuovo copera auth login in qualsiasi momento.

Ordine di risoluzione del token

Quando esegui un comando, la CLI cerca un token in questo ordine — vince il primo che trova:

Priority	Source	Example
1	Environment variable	COPERA_CLI_AUTH_TOKEN=cp_pat_xxx
2	--token flag on the command	copera boards list --token cp_pat_xxx
3	.copera.local.toml in the current directory	Project-local, git-ignored token
4	.copera.toml in the current directory	Shared project defaults
5	~/.copera.toml	User-level fallback

Questo è intenzionale:

• CI e agenti possono sovrascrivere tutto il resto impostando COPERA_CLI_AUTH_TOKEN.
• Token per progetto vivono in .copera.local.toml, che va aggiunto a .gitignore.
• Default di progetto condivisi (come un board_id e table_id predefiniti, senza token) vivono in .copera.toml, che è sicuro da committare.
• Il tuo token personale resta in ~/.copera.toml per tutto il resto.

Vedi Configurazione per il formato completo del file di config e come si inseriscono i profili.

Profili

Un profilo raggruppa un token insieme a ID di risorse predefiniti così non devi ripetere flag come --board e --table. I profili vivono nei file di config sotto [profiles.<name>]:

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

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

Seleziona un profilo per comando o per shell. Se ometti --profile, la CLI usa default (o il default_profile impostato nella config):

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

Sandbox

Per puntare all'ambiente di sviluppo di Copera invece che alla produzione, imposta COPERA_SANDBOX=1. 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:

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

Dove ottengo un token?

Genera un token dall'app web di Copera:

1. Apri il workspace a cui vuoi accedere.
2. Vai su Settings → Personal Access Tokens (per cp_pat_...) o Settings → Integrations (per cp_key_...).
3. Crea un token, copialo e incollalo nel prompt della CLI oppure impostalo come COPERA_CLI_AUTH_TOKEN.

Per saperne di più su cosa può fare ogni tipo di token, vedi la guida Autenticazione API.