Skip to main content

Copera CLI Overview

copera is the official command-line interface for Copera. Use it to work with boards, tables, rows, docs, drive files, channels, notifications, and workspace data — straight from your terminal, a script, or an AI coding agent.

The CLI is built for two audiences:

  • Power users who prefer the keyboard over the UI, want to script repetitive work, or run Copera from a remote shell.
  • AI coding agents (Claude Code, Cursor, Codex, and others) that take real, auditable actions in your workspace on your behalf.

Every action runs as the user behind the token — your permissions are respected, and every change is fully reversible in the app.

info

The CLI wraps the Copera Public API. Its base URL is https://api.copera.ai/public/v1. If you would rather call the API directly, or connect an AI client over MCP, see MCP Overview.

Install​

macOS / Linux​

Run this in your terminal:

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

By default, the installer writes the copera binary to /usr/local/bin/copera. If that directory requires elevated permissions, the script asks for sudo.

To install a specific version:

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

Windows​

Open PowerShell and run:

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

You do not need to run PowerShell as Administrator — this installs copera.exe into your user profile. Close and reopen PowerShell, then verify:

copera version

To pin a specific version:

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

If you prefer to install manually: download the Windows AMD64 zip for the version you want from the Copera CLI CDN, extract copera.exe, move it into a directory on your PATH (such as %LOCALAPPDATA%\Microsoft\WindowsApps), then open a new PowerShell window and run copera version.

From source​

If you have Go installed:

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

Update​

Upgrade an existing install at any time:

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

Quick start​

Sign in. The simplest flow opens a browser and prints a URL you can use anywhere:

copera auth login

The CLI prints a Copera URL, opens it in your default browser when possible, and asks you to paste the generated token back into the terminal. The printed URL is always available, so the same flow works over SSH, in WSL, or in any terminal where the browser may not open automatically.

If you already have a token, skip the browser:

copera auth login --token=cp_pat_xxx

For CI, scripts, and agent pipelines, an environment variable is cleanest:

export COPERA_CLI_AUTH_TOKEN="cp_pat_xxx"

Confirm the session:

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

Try a few commands:

copera boards list
copera docs tree
copera search "onboarding"

For machine-readable output, add --json:

copera boards list --json

See Authentication for token types and login flows, and Commands for the full command reference.

Output formats​

The CLI is designed to work well in both interactive terminals and automated pipelines.

  • When stdout is a TTY, output is a colored, human-readable table.
  • When stdout is not a TTY (piped to another command, redirected to a file, or run in CI), output defaults to JSON — agent-safe by default.
  • --json forces JSON output even in a terminal.
  • --output accepts auto (default), json, table, or plain.
  • --quiet / -q suppresses informational messages.
  • --no-input (and CI=true) disable interactive prompts.
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

Errors are emitted on stderr as structured JSON, so success output stays clean:

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

transient: true means the error is retryable; false means retrying will not help.

Exit codes​

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

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

Environment variables​

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.

See Configuration for the full list, including profiles and config-file options.

Explore the docs​

Authentication

Token types, the login flows, and how the CLI resolves credentials.

Commands

The full command reference — boards, rows, docs, drive, channels, and more.

Configuration

Profiles, default IDs, environment variables, and machine-readable output.

MCP Server

Connect AI clients to the same Public API over the Model Context Protocol.