Konfiguration

Die CLI funktioniert nach copera auth login ohne weitere Konfiguration, aber ein paar kleine Ergänzungen machen den Alltag deutlich flüssiger — besonders beim Skripten oder beim Einsatz mit einem KI-Agenten.

Hierarchie der Konfigurationsdateien

Die CLI liest die Konfiguration aus bis zu drei TOML-Dateien. Wenn dieselbe Einstellung mehrfach vorkommt, gewinnt die Datei mit höherer Priorität:

Priorität	Datei	Zweck
1	.copera.local.toml (aktuelles Verzeichnis)	Entwicklerspezifische Secrets. In .gitignore aufnehmen.
2	.copera.toml (aktuelles Verzeichnis)	Gemeinsame Projekt-Standards. Sicher zum Committen (keine Tokens).
3	~/.copera.toml	Ihre persönliche Konfiguration mit allen Profilen.

Die Umgebungsvariable COPERA_CLI_AUTH_TOKEN und das Flag --token überschreiben alle drei speziell für das Token. Siehe die vollständige Reihenfolge der Token-Auflösung.

Dateiformat

Jede Datei ist TOML. Ein Profil bündelt ein Token mit Standard-Ressourcen-IDs; die Abschnitte [output] und [cache] steuern das Verhalten:

# 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

Sobald Standards konfiguriert sind, werden die Befehle kürzer:

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

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

Profile

Jeder Block [profiles.<name>] enthält eigene Werte für token, board_id, table_id, row_id, channel_id und doc_id. Wählen Sie eines pro Befehl oder pro Shell — wenn Sie --profile weglassen, verwendet die CLI default (oder das in der Konfiguration gesetzte default_profile):

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

Projektweite Konfiguration

Für gemeinsame Projekt-Standards committen Sie eine .copera.toml ohne Tokens:

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

Für entwicklerspezifische Secrets, die nicht committed werden sollen, verwenden Sie .copera.local.toml und nehmen Sie sie in .gitignore auf:

[profiles.default]
token = "cp_pat_xxx"

So teilt das ganze Team dieselben Standard-Boards und -Tabellen, während jeder Entwickler lokal sein eigenes Token liefert.

Umgebungsvariablen

Variable	Beschreibung
COPERA_CLI_AUTH_TOKEN	API-Token. Überschreibt jede Konfigurationsdatei.
COPERA_PROFILE	Name des aktiven Konfigurationsprofils (Standard: default).
COPERA_SANDBOX	Auf 1 setzen, um die Entwicklungs-API anzusprechen.
COPERA_NO_UPDATE_CHECK	Auf 1 setzen, um Hintergrund-Versionsprüfungen zu deaktivieren.
CI	Auf true setzen, um interaktive Prompts und Update-Prüfungen zu deaktivieren.
NO_COLOR	ANSI-Farbausgabe deaktivieren.

Sandbox

Setzen Sie COPERA_SANDBOX=1, um die CLI auf die Copera-Entwicklungsumgebung statt auf die Produktion zu richten. Dadurch wechselt die API-Basis-URL zu https://api-dev.copera.ai/public/v1 und copera auth login zeigt auf die Dev-Web-App (https://dev.copera.ai):

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

Verwenden Sie ein separates Profil für Sandbox-Credentials, damit sie nicht mit Produktions-Tokens vermischt werden.

Update-Prüfungen

Standardmäßig führt die CLI im Hintergrund eine leichte Prüfung auf neue Versionen aus und meldet, wenn eine verfügbar ist. Deaktivieren Sie sie für vollständig stille, deterministische Läufe:

COPERA_NO_UPDATE_CHECK=1 copera boards list

Update-Prüfungen werden auch automatisch übersprungen, wenn CI=true gesetzt ist, wenn --json oder --quiet verwendet wird und bei Entwicklungs-Builds. Aktualisieren Sie jederzeit explizit mit copera update.

Caching

Die CLI speichert Dokumentinhalte lokal auf der Festplatte, um überflüssige API-Aufrufe zu vermeiden.

• Standardort: System-Temp-Verzeichnis unter copera-cli/. Überschreiben mit cache.dir in der Konfiguration.
• Standard-TTL: 1 Stunde. Ändern mit cache.ttl (z. B. "30m", "6h").
• Cache prüfen mit copera cache status; leeren mit copera cache clean.
• Cache für einen einzelnen Lesevorgang umgehen mit copera docs content <id> --no-cache.

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

Maschinenlesbare Ausgabe

Die CLI ist für Skripte und Agenten-Workflows gebaut:

• Wenn stdout kein TTY ist (Pipe, Umleitung oder CI), ist die Standardausgabe JSON.
• --json erzwingt JSON-Ausgabe auch im Terminal.
• --output akzeptiert auto, json, table oder plain.
• --quiet / -q unterdrückt Info-Meldungen.
• --no-input (und CI=true) deaktiviert interaktive Prompts.
• Fehler werden auf stderr als strukturiertes JSON ausgegeben.

Exit-Codes

Code	Bedeutung
0	OK
1	Allgemeiner Fehler
2	Nutzungsfehler (falsche Flags, fehlende Argumente)
3	Nicht gefunden
4	Auth-Fehler / keine Berechtigung
5	Konflikt (z. B. Ressource existiert bereits)
6	Rate-Limit erreicht

Strukturierte Fehler

Bei Fehlern gibt die CLI einen JSON-Fehler auf stderr aus:

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

transient: true bedeutet, dass Sie erneut versuchen können; false bedeutet, dass der Fehler dauerhaft ist und erneutes Versuchen nicht hilft.

Verwandte Themen

• Übersicht — Installation und Ersteinrichtung.
• Authentifizierung — Token-Typen, Login-Abläufe und Auflösungsreihenfolge.
• Befehle — die vollständige Befehlsreferenz.