Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.copera.ai/llms.txt

Use this file to discover all available pages before exploring further.

Once installed, the Copera CLI skill is loadable by any agent that supports the Agent Skills standard. How you invoke it depends on the agent.

​
Invocation by agent

AgentInvocation
Claude Code/copera:cli (explicit) or any prompt mentioning Copera (auto-trigger).
Cursor/copera-cli (explicit) or describe what you want — the skill is description-matched.
OpenCodeDiscovery is automatic via the skill tool; just ask for a Copera task.
Codex / Windsurf / Cline / Aider / ContinueAmbient — the skill content is loaded as part of the agent’s context. Just describe the task.
You almost never need to invoke the skill explicitly. Just describe what you want done in Copera, and the agent will load the right reference and run.

​
First-run conventions

The skill enforces a few rules that make agent runs predictable. Knowing them helps you understand why agents pause or ask before acting.

​
Discovery before writes

Before creating or updating anything in a board the agent has not seen this session, it will run: 
copera boards list --json
copera tables list --board <boardId> --json
copera tables get  --board <boardId> <tableId> --json
This is not the agent being chatty — column types and option labels are not guessable. Skipping the schema read is the most common cause of silently-rejected row writes. The skill makes this rule mandatory.

​
Confirmation when it matters

The agent uses judgment about when to pause and ask. The default is not “confirm every write” — that’s confirmation theater. Instead:
  • Reads — run silently and summarize.
  • Routine writes (rows create, rows update, internal comments and messages, docs update, drive upload to a fresh path) — when your request is unambiguous, the agent just runs them and reports what changed. No restatement.
  • The agent pauses and asks when:
    1. It had to infer a value you didn’t specify (e.g. severity not given, must guess).
    2. The operation reaches outside the workspace (external-visibility comments, customer-facing channels, mass uploads).
    3. You explicitly said “ask me before each step” in the conversation.
  • Destructive operations (rows delete, docs delete, force-delete, mass overwrite) — always confirm, even if you pre-authorized.
For workflow skills (see Workflow Skills), the confirmation posture is decided at skill-build time per script — recorded as a Confirm column in the skill’s Scripts table. The agent honors that without re-asking. Destructive scripts are locked to always-confirm; non-destructive ones default to “just run”.

​
JSON-first

When the agent needs to act on Copera output, it always passes --json. Human-formatted CLI output is for you, not for the agent’s parser.

​
Example sessions

​
Listing boards

You: What boards do I have in Copera? Agent: (runs copera boards list --json) You have three boards: Engineering (66ab…), CRM (66cd…), Marketing (66ef…). Want me to drill into any of them?

​
Creating a row (with discovery)

You: Create a bug in the Bugs table titled “Login button broken on Safari”, severity P1. Agent: (runs copera tables list --board 66ab… --json) I see two tables in Engineering: Bugs (66bg…) and Releases (66rl…). Using Bugs. (runs copera tables get --board 66ab… 66bg… --json) Schema has Status, Severity, Title, Description. (runs copera rows create --board 66ab… --table 66bg… --data '{…}' --json) Created row #142 (66r1…) — title “Login button broken on Safari”, severity P1, status Triage.
The agent doesn’t restate the call before running it — your request was unambiguous and the create is non-destructive. If you’d specified an inferred-by-the-agent value (e.g. “create some bug for me”), or if this were a rows delete, the agent would pause and confirm.

​
Capturing a workflow

You: Every time I send you a Sentry link, file a triage row in Bugs and post a notification to #alerts. Agent: That sounds like a workflow you’ll repeat. Want me to save it as a reusable workflow skill so any future session can run it identically? (continues with the build-workflow-skill interview)

​
Profiles cut out repetition

If you’re going to ask the agent to operate on the same board+table repeatedly, configure a Copera profile so the IDs are pre-resolved: 
# ~/.copera.toml
default_profile = "bugs"

[profiles.bugs]
token    = "cp_pat_…"
board_id = "66ab…"
table_id = "66bg…"
Then the agent can run copera rows create --data '{…}' without --board / --table flags. See CLI Configuration for the full profile schema, and Workflow Skills for how the agent helps you set this up automatically.

​
What to expect when the schema changes

Workspace admins changing a column or option label can break workflow skills that hardcoded the schema. Detection is reactive, not pre-flight — the skill doesn’t fetch the schema on every run (that would burn rate-limit budget unnecessarily). Instead:
  1. The agent invokes a workflow’s bundled script. The script returns a copera error (e.g. invalid option ID).
  2. The agent loads the workflow’s fingerprint.md (only now, not before), classifies the error as schema-flavored, and pauses.
  3. It tells you the schema for <table> may have changed and asks whether to fetch the current schema and update the skill.
  4. On your OK, it diffs against the saved snapshot, rewrites the affected sections, bumps the snapshot date, and re-runs the failing call.
  5. On “no”, it exits cleanly — never silently retries against a schema it suspects is stale.
You can also force a refresh at any time: “refresh the schema for <workflow-name>”. See Workflow Skills → Schema drift for the full mechanism.

​
Limitations

  • The skill teaches CLI usage; it does not replace the CLI binary. Install the copera CLI on the same machine.
  • Docs commands require a Personal Access Token (cp_pat_…). Integration keys (cp_key_…) work for boards/drive/channels but return 401 on docs endpoints.
  • LINK column targets are not in the schema — the agent has to ask you which table is on the other end. Workflow skills that use LINK columns capture this from the interview.