Configuration

The CLI works with zero configuration after copera auth login, but a few small additions make day-to-day use much smoother — especially when you're scripting or running it from an AI agent.

Profiles

Profiles bundle a token together with default resource IDs (like a default board_id and table_id). They live in ~/.copera.toml:

default_profile = "work"

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

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

[output]
format = "auto"   # auto | json | table | plain

[cache]
ttl = "1h"

Once defaults are configured, commands shrink:

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

# With defaults
copera rows list

Switch profiles per-command or per-shell:

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

Project-level config

For shared project defaults, commit a .copera.toml to your repo (no tokens — safe to commit):

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

For per-developer secrets that should not be committed, use .copera.local.toml and add it to .gitignore:

[profiles.default]
token = "cp_pat_xxx"

The CLI walks up the directory tree looking for these files, so they apply to every command run inside the project.

Machine-readable output

The CLI is designed to work well in scripts and agent workflows:

• When stdout is not a TTY (piped to another command, redirected to a file, or run in CI), output defaults to JSON.
• --json forces JSON output even in a terminal.
• --output accepts auto, json, table, or plain.
• --quiet / -q suppresses informational messages — useful for scripts that only want the result.
• Errors are emitted on stderr as structured JSON.
• --no-input and CI=true disable interactive prompts (no "are you sure?" questions).

Exit codes

Exit codes are stable, so scripts can branch on them safely:

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

Structured errors

When something fails, the CLI emits a JSON error on stderr like:

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

transient: true means "you can retry" — false means the error is permanent and retrying will not help.

Environment variables

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

Related

• Overview — Install and first-time setup.
• Authentication — Token types and login flows.
• Common Commands — Quick reference for every command.
• Copera Developer Docs — Full API and SDK reference.