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 scripting or running it from an AI agent.

Config file hierarchy

The CLI reads configuration from up to three TOML files. When the same setting appears in more than one, the higher-priority file wins:

Priority	File	Purpose
1	.copera.local.toml (current directory)	Per-developer secrets. Add to .gitignore.
2	.copera.toml (current directory)	Shared project defaults. Safe to commit (no tokens).
3	~/.copera.toml	Your personal config, with all profiles.

The environment variable COPERA_CLI_AUTH_TOKEN and the --token flag override all three for the token specifically. See the full token resolution order.

File format

Each file is TOML. A profile groups a token with default resource IDs; an [output] and [cache] section tune behavior:

# 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

Once defaults are configured, commands shrink:

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

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

Profiles

Each [profiles.<name>] block holds its own token, board_id, table_id, row_id, channel_id, and doc_id. Select one per-command or per-shell — when you omit --profile, the CLI uses default (or the default_profile set in your config):

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 with no tokens:

[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"

This split lets a whole team share the same default board and table while each developer supplies their own token locally.

Environment variables

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

Sandbox

Set COPERA_SANDBOX=1 to point the CLI at the Copera development environment instead of production. This switches the API base URL to https://api-dev.copera.ai/public/v1 and points copera auth login at the dev web app (https://dev.copera.ai):

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

Use a separate profile for sandbox credentials so you do not mix them with production tokens.

Update checks

By default the CLI runs a lightweight background check for new versions and tells you when one is available. Disable it when you want fully silent, deterministic runs:

COPERA_NO_UPDATE_CHECK=1 copera boards list

Update checks are also skipped automatically when CI=true, when --json or --quiet is set, and for development builds. Upgrade explicitly at any time with copera update.

Caching

The CLI caches document content on disk to avoid redundant API calls.

• Default location: your system temp directory, under copera-cli/. Override it with cache.dir in your config.
• Default TTL: 1 hour. Change it with cache.ttl (e.g. "30m", "6h").
• Inspect the cache with copera cache status; clear it with copera cache clean.
• Bypass the cache for a single read with copera docs content <id> --no-cache.

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

Machine-readable output

The CLI is built to slot into scripts and agent workflows:

• When stdout is not a TTY (piped, redirected, or 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.
• --no-input (and CI=true) disable interactive prompts.
• Errors are emitted on stderr as structured JSON.

Exit codes

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

Structured errors

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

{
  "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.

Related

• Overview — install and first-time setup.
• Authentication — token types, login flows, and resolution order.
• Commands — the full command reference.