Configuration

La CLI fonctionne sans configuration après copera auth login, mais quelques petits ajouts rendent l'usage quotidien bien plus fluide — surtout pour les scripts ou l'exécution depuis un agent IA.

Hiérarchie des fichiers de configuration

La CLI lit la configuration depuis jusqu'à trois fichiers TOML. Lorsque le même paramètre apparaît dans plusieurs, le fichier de priorité la plus élevée l'emporte :

Priorité	Fichier	Rôle
1	.copera.local.toml (répertoire courant)	Secrets par développeur. À ajouter au .gitignore.
2	.copera.toml (répertoire courant)	Défauts partagés du projet. Peut être versionné (sans tokens).
3	~/.copera.toml	Votre configuration personnelle, avec tous les profils.

La variable d'environnement COPERA_CLI_AUTH_TOKEN et le flag --token remplacent les trois pour le token spécifiquement. Voir l'ordre complet de résolution du token.

Format du fichier

Chaque fichier est en TOML. Un profil regroupe un token avec des IDs de ressources par défaut ; une section [output] et une section [cache] ajustent le comportement :

# Utiliser un profil autre que "default" sans passer --profile à chaque fois.
# Remplacé par COPERA_PROFILE ou --profile.
default_profile = "work"

[profiles.default]
token      = "cp_pat_abc123..."  # ne jamais versionner ceci
board_id   = "66abc123def456789012abcd"  # utilisé lorsque --board est omis
table_id   = "66pqr012stu345678901vwxy"  # utilisé lorsque --table est omis
row_id     = ""                  # utilisé lorsque --row est omis
channel_id = ""                  # utilisé lorsque --channel est omis
doc_id     = ""                  # utilisé lorsque --doc est omis

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

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

[cache]
dir = ""          # défaut : répertoire temporaire système / copera-cli
ttl = "1h"        # durée de mise en cache du contenu des docs

Une fois les défauts configurés, les commandes se simplifient :

# Sans défauts
copera rows list --board 66ghi... --table 66pqr...

# Avec board_id et table_id dans le profil actif
copera rows list

Profils

Chaque bloc [profiles.<name>] contient son propre token, board_id, table_id, row_id, channel_id et doc_id. Sélectionnez-en un par commande ou par shell — lorsque vous omettez --profile, la CLI utilise default (ou le default_profile défini dans votre configuration) :

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

Configuration au niveau projet

Pour des défauts partagés du projet, versionnez un .copera.toml dans votre dépôt sans tokens :

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

Pour des secrets par développeur qui ne doivent pas être versionnés, utilisez .copera.local.toml et ajoutez-le au .gitignore :

[profiles.default]
token = "cp_pat_xxx"

Cette séparation permet à toute une équipe de partager le même board et la même table par défaut, tandis que chaque développeur fournit son propre token en local.

Variables d'environnement

Variable	Description
COPERA_CLI_AUTH_TOKEN	Token d'API. Remplace tous les fichiers de configuration.
COPERA_PROFILE	Nom du profil de configuration actif (défaut : default).
COPERA_SANDBOX	Définir à 1 pour cibler l'API de développement.
COPERA_NO_UPDATE_CHECK	Définir à 1 pour désactiver les vérifications de version en arrière-plan.
CI	Définir à true pour désactiver les invites interactives et les vérifications de mise à jour.
NO_COLOR	Désactive la sortie couleur ANSI.

Sandbox

Définissez COPERA_SANDBOX=1 pour pointer la CLI vers l'environnement de développement Copera au lieu de la production. Cela bascule l'URL de base de l'API vers https://api-dev.copera.ai/public/v1 et oriente copera auth login vers l'app web de dev (https://dev.copera.ai) :

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

Utilisez un profil distinct pour les identifiants sandbox afin de ne pas les mélanger avec les tokens de production.

Vérifications de mise à jour

Par défaut, la CLI exécute une vérification légère en arrière-plan des nouvelles versions et vous prévient lorsqu'une est disponible. Désactivez-la pour des exécutions totalement silencieuses et déterministes :

COPERA_NO_UPDATE_CHECK=1 copera boards list

Les vérifications de mise à jour sont aussi ignorées automatiquement lorsque CI=true, lorsque --json ou --quiet est défini, et pour les builds de développement. Mettez à jour explicitement à tout moment avec copera update.

Cache

La CLI met en cache le contenu des documents sur le disque pour éviter les appels d'API redondants.

• Emplacement par défaut : le répertoire temporaire de votre système, sous copera-cli/. Remplacez-le avec cache.dir dans votre configuration.
• TTL par défaut : 1 heure. Modifiez-le avec cache.ttl (p. ex. "30m", "6h").
• Inspectez le cache avec copera cache status ; videz-le avec copera cache clean.
• Ignorez le cache pour une seule lecture avec copera docs content <id> --no-cache.

copera cache status   # taille, nombre de fichiers et chemin
copera cache clean    # le vider entièrement

Sortie lisible par machine

La CLI est conçue pour s'intégrer aux scripts et workflows d'agents :

• Lorsque stdout n'est pas un TTY (pipé, redirigé ou en CI), la sortie bascule par défaut en JSON.
• --json force la sortie JSON même dans un terminal.
• --output accepte auto, json, table ou plain.
• --quiet / -q supprime les messages informatifs.
• --no-input (et CI=true) désactivent les invites interactives.
• Les erreurs sont émises sur stderr en JSON structuré.

Codes de sortie

Code	Signification
0	OK
1	Erreur générique
2	Erreur d'utilisation (flags incorrects, arguments manquants)
3	Introuvable
4	Erreur d'auth / permission refusée
5	Conflit (p. ex. une ressource qui existe déjà)
6	Limite de débit atteinte

Erreurs structurées

Lorsqu'une opération échoue, la CLI émet une erreur JSON sur stderr :

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

transient: true signifie que vous pouvez réessayer ; false signifie que l'erreur est permanente et qu'un nouvel essai n'aidera pas.

Articles associés

• Vue d'ensemble — installation et configuration initiale.
• Authentification — types de tokens, flux de connexion et ordre de résolution.
• Commandes — la référence complète des commandes.