Vai al contenuto principale

Panoramica della Copera CLI

copera è l'interfaccia a riga di comando ufficiale di Copera. Usala per lavorare con board, tabelle, righe, docs, file del drive, channels, notifiche e dati del workspace — direttamente dal terminale, da uno script o da un agente di coding con IA.

La CLI è pensata per due pubblici:

  • Power user che preferiscono la tastiera all'interfaccia, vogliono automatizzare lavoro ripetitivo o eseguire Copera da una shell remota.
  • Agenti di coding con IA (Claude Code, Cursor, Codex e altri) che eseguono azioni reali e auditabili nel tuo workspace per tuo conto.

Ogni azione viene eseguita come l'utente associato al token — le tue autorizzazioni vengono rispettate e ogni modifica è completamente reversibile nell'app.

informazione

La CLI avvolge la Copera Public API. L'URL di base è https://api.copera.ai/public/v1. Se preferisci chiamare l'API direttamente, o collegare un client IA via MCP, vedi la Panoramica MCP.

Installazione​

macOS / Linux​

Esegui questo nel terminale:

curl -fsSL https://cli.copera.ai/install.sh | bash

Per impostazione predefinita, l'installer scrive il binario copera in /usr/local/bin/copera. Se quella directory richiede permessi elevati, lo script chiede sudo.

Per installare una versione specifica:

VERSION=0.1.0 curl -fsSL https://cli.copera.ai/install.sh | bash

Windows​

Apri PowerShell ed esegui:

irm https://cli.copera.ai/install.ps1 | iex

Non serve eseguire PowerShell come Amministratore — questo installa copera.exe nel profilo utente. Chiudi e riapri PowerShell, poi verifica:

copera version

Per fissare una versione specifica:

$env:VERSION = "0.1.0"; irm https://cli.copera.ai/install.ps1 | iex

Se preferisci installare manualmente: scarica lo zip Windows AMD64 della versione desiderata dalla CDN della Copera CLI, estrai copera.exe, spostalo in una directory nel tuo PATH (ad esempio %LOCALAPPDATA%\Microsoft\WindowsApps), poi apri una nuova finestra di PowerShell ed esegui copera version.

Dal codice sorgente​

Se hai Go installato:

go install github.com/copera/copera-cli/cmd/copera@latest

Aggiornamento​

Aggiorna un'installazione esistente in qualsiasi momento:

copera update                  # update to the latest version
copera update --version 1.2.0  # pin to a specific version
copera update --force          # skip the confirmation prompt

Avvio rapido​

Accedi. Il flusso più semplice apre un browser e stampa un URL che puoi usare ovunque:

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, salta il browser:

copera auth login --token=cp_pat_xxx

Per CI, script e pipeline di agenti, una variabile d'ambiente è la soluzione più pulita:

export COPERA_CLI_AUTH_TOKEN="cp_pat_xxx"

Conferma la sessione:

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

Prova alcuni comandi:

copera boards list
copera docs tree
copera search "onboarding"

Per output leggibile dalle macchine, aggiungi --json:

copera boards list --json

Vedi Autenticazione per i tipi di token e i flussi di login, e Comandi per il riferimento completo ai comandi.

Formati di output​

La CLI è progettata per funzionare bene sia nei terminali interattivi sia nelle pipeline automatizzate.

  • Quando stdout è un TTY, l'output è una tabella colorata e leggibile.
  • Quando stdout non è un TTY (pipato a un altro comando, reindirizzato a un file o eseguito in CI), l'output predefinito è JSON — sicuro per gli agenti di default.
  • --json forza l'output JSON anche in un terminale.
  • --output accetta auto (predefinito), json, table o plain.
  • --quiet / -q sopprime i messaggi informativi.
  • --no-input (e CI=true) disabilitano i prompt interattivi.
copera boards list                 # table in a terminal, JSON when piped
copera boards list --json | jq '.[].name'
copera boards list --output plain  # one value per line, for scripts

Gli errori vengono emessi su stderr come JSON strutturato, così l'output di successo resta pulito:

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

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

Codici di uscita​

I codici di uscita sono stabili, così gli script possono fare branching in modo affidabile:

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

Variabili d'ambiente​

VariableDescription
COPERA_CLI_AUTH_TOKENAPI token. Overrides every config file.
COPERA_PROFILEActive config profile name (default: default).
COPERA_SANDBOXSet to 1 to target the development API (api-dev.copera.ai).
COPERA_NO_UPDATE_CHECKSet to 1 to disable background version checks.
CISet to true to disable interactive prompts and update checks.
NO_COLORDisable ANSI color output.

Vedi Configurazione per l'elenco completo, inclusi profili e opzioni del file di config.

Esplora la documentazione​

Autenticazione

Tipi di token, flussi di login e come la CLI risolve le credenziali.

Comandi

Il riferimento completo ai comandi — boards, rows, docs, drive, channels e altro.

Configurazione

Profili, ID predefiniti, variabili d'ambiente e output leggibile dalle macchine.

MCP Server

Collega client IA alla stessa Public API tramite il Model Context Protocol.

Correlati​