Metadata-Version: 2.5
Name: coelevate-cli
Version: 0.8.0
Summary: Command-line client for the Coelevate Context Repository public API: read, search, stage changes, and inspect releases.
Project-URL: Documentation, https://docs.coelevate.ai
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: keyring>=25.6
Description-Content-Type: text/markdown

# coelevate

Command-line client for the Coelevate Context Repository public API. Read and search
your key's context, inspect releases, and **stage** asset changes for review. It proposes asset
changes and has no action that lands one. A **kit** is not an asset: `kit` writes it directly.

Requires Python 3.11 or newer. The dependencies are `httpx` and `keyring` (which keeps a browser sign-in in the operating system's keyring).

## Install

The package is published on PyPI as `coelevate-cli`; the command it installs is
`coelevate`. Pin a version (`0.8.0` below):

```bash
# one-off, no install (recommended: pinned, nothing left behind)
uvx --from coelevate-cli==0.8.0 coelevate --help

# isolated tool install
uv tool install coelevate-cli==0.8.0
# or
pipx install coelevate-cli==0.8.0
```

PyPI lists the SHA-256 of every file it serves under the project's **Download files**; compare a
downloaded wheel or sdist against it before you rely on it (`shasum -a 256 <file>`).

## Sign in with your browser: `coelevate init`

In the folder you work in:

```bash
coelevate init
```

With nothing named it signs in to production, `https://api.coelevate.ai`, and says so; pass `--env staging` or
`--env demo` for another environment, or `--api-url` for any other host (the two exclude each other). The order is
`--env` or `--api-url`, then `COELEVATE_API_URL`, then the default; only `init` and `feedback` use the default, every other command uses the
API stored with the sign-in.

1. It reads the authorization server's description at `<API URL>/.well-known/oauth-authorization-server`.
2. It opens your browser on the sign-in (authorization code with PKCE S256, redirected back to a one-time
   listener on `127.0.0.1` and a random port, with a `state` check). It always prints the address too, and
   `--no-browser` only prints it. When the browser cannot reach this machine's `127.0.0.1` (another machine,
   SSH, a container, a sandboxed browser), it ends on an error page there: paste that page's full address into
   the terminal and init carries on with it. The pasted address must be this sign-in's own redirect address
   (same scheme, host, port and path) and carry its `state`, or init stops and stores nothing. Whichever
   arrives first, the redirect or the paste, is used. The paste is offered only on a terminal and never
   with `--json`, where only the redirect counts.
3. You sign in to the Workspace and choose the project on the consent page, and may untick any scope. It asks
   for `context:read`, `context:assets`, `context:kits` and `context:gaps`; review is never grantable. With
   `--project ID`, the project you choose must be that one, or init fails, revokes the sign-in and stores nothing.
4. It keeps the refresh token in the operating system's keyring (macOS Keychain, Windows Credential Manager,
   Secret Service), one entry per project together with the API it was issued for. It is never written to a
   file, never printed and never sent to another API.
5. It binds the folder: `.coelevate.json` with `project` and `label` (the folder's name), the file the
   `bind-project` skill writes, plus the one Coelevate line in `CLAUDE.md`. An existing binding for the same
   project is kept; one for another project stops init before anything is stored.
6. It installs Coelevate for each coding agent it finds: for Claude Code,
   `claude plugin marketplace add https://plugins.coelevate.ai/marketplace.json` and
   `claude plugin install coelevate@coelevate-plugins` (skipped when the plugin is already installed); for
   Cursor, Codex or Gemini CLI, `npx skills add https://plugins.coelevate.ai/coelevate-skills.zip --global`, for your
   user rather than this folder (to commit skills in a repository, run `npx skills add` there yourself). Each runs from a
   new empty folder with no `COELEVATE_*` variable, so the folder you are in cannot steer it. It shows
   each command and asks first on a terminal; `--yes` runs them without asking, `--no-install` skips them,
   and with no terminal and no `--yes` they are left `pending`.
7. It runs `doctor` and ends with `ready`, or `pending` and the list of what is left (exit 0 or 1).

`--json` prints one document: `status` (`ready` or `pending`), `api_url`, `api_host`, `project_id`,
`scopes`, `credential` (`keyring`), `steps` (each with `name`, `status` of `ok`, `skipped`, `pending` or
`failed`, `detail`, and for an install its `agent` and `commands`), `doctor` (the `doctor --json` document),
`pending` and `notes`. Progress and the sign-in address go to stderr.

Every later command uses the sign-in: it refreshes it into a short-lived access token, stores the rotated
refresh token the server returns, and takes the project from the folder's `.coelevate.json` (or
`--expect-project`). A sign-in that was revoked or expired says to run `coelevate init` again.

`coelevate logout` revokes the sign-in at the server and deletes it from the keyring (`--project ID`
when the folder has no binding). Running it again is not an error. You can also disconnect the Coelevate
CLI under Connected apps in the Workspace.

Where there is no keyring (a server, a container, CI), init stops before opening the browser and points
at a project API key instead.

## Update: `coelevate update`

Run it in your own shell. It upgrades the client to the current release on PyPI, the way it was installed (with `uv` or `pipx`; run through `uvx` it follows the plugin or the skills, and installed any other way it names the command for you), then refreshes the Claude Code plugin and any skills installed for your user. It shows the commands and asks first (`--yes` answers for you). If one part fails it names what succeeded and exits non-zero; running it again is safe. A client chosen through `COELEVATE_CLI` is left alone. It reads no credential, no `.env` and no keyring, and what it starts runs from a new empty folder with no `COELEVATE_*` variable. Skills kept inside the current folder are not refreshed, because running `npx` there lets the folder choose what runs: it says so and gives the command.

`coelevate doctor --updates [--plugin-version <version>] [--json]` only checks. At most once a day it fetches `https://pypi.org/pypi/coelevate-cli/json` and `https://plugins.coelevate.ai/marketplace.json`, plain requests with no identifier of yours, about two seconds at most, cached under your user cache folder, silent on any failure, always exit 0. `COELEVATE_NO_UPDATE_CHECK=1` turns it off.

## Authentication with a project API key

`coelevate init` is the recommended route. A key stays supported for debugging, CI and servers.

For CI and servers. Credentials and endpoints come from the environment, or from a `.env` file in the
folder you run the command in (below). A secret is never accepted as a flag. A complete key (id,
secret and API URL, the URL from the environment or `--api-url`) is used and a browser sign-in is not. An
incomplete one does not hide a sign-in: the command uses the sign-in and names, on stderr and in `doctor`'s
`credential` check, the variables the key lacked.

| Variable | Meaning |
|---|---|
| `COELEVATE_API_URL` | the public API origin (or `--api-url`) |
| `COELEVATE_CLIENT_ID` | the API key id |
| `COELEVATE_CLIENT_SECRET` | the API key secret |
| `COELEVATE_TOKEN_URL` | optional token endpoint (or `--token-url`); defaults to `<API URL>/oauth/token` |
| `COELEVATE_PROJECT_ID` | optional pin: the project you expect the key to resolve to (or `--expect-project`) |
| `COELEVATE_WORKSPACE_URL` | optional Workspace origin for the review link (default: the API host without its `api.` label) |
| `COELEVATE_ENVIRONMENT` | optional label `whoami` reports (default: derived from the API host) |

These are the same variables every Coelevate client reads, so one key and one env file work for every Coelevate API.

The key needs the `context:read` scope to read and search, `context:assets` to stage, `context:kits` to write a kit (a `kit` write asks only for `context:kits`; `kit journal` only reads, so it asks for `context:read`) and `context:gaps` to write a gap (a `gap` write asks only for `context:gaps`; `gap list`, `get` and `journal` only read, so they ask for `context:read`).
There is no default for the API URL or key; a missing one fails immediately and names the variable.
No action prompts except `init`, which asks on a terminal before it runs each install command.

**The key decides the project.** The key's token names it, and every request goes to
`<API URL>/context/v1/...` with nothing project-specific in the path; there is no `--project-id`.
To make sure a session is talking to the project you think it is, pin it: set
`COELEVATE_PROJECT_ID` (or pass `--expect-project`). If the key resolves to any other
project, every action refuses with exit code 2 and names both ids, before it reads or
stages anything. A pin the token cannot confirm is refused the same way.

### A `.env` file

If the folder you run the CLI in has a `.env` file, the CLI reads it first. Only `COELEVATE_*`
variables are taken from it (the rest of the file is ignored), a variable already set in the
real environment wins over the file, and the format is the usual `KEY=value` with an optional
`export`, optional quotes and `#` comments. Keep the file out of version control.

One rule protects your key from a `.env` you did not write: the file's `COELEVATE_TOKEN_URL` and
`COELEVATE_API_URL` are used only when the same file also sets the client id and secret and your
real environment sets neither. Otherwise they are ignored, and the CLI says so on stderr (naming
the keys, never a value).

```bash
export COELEVATE_CLIENT_ID=<key id>
read -rs COELEVATE_CLIENT_SECRET; export COELEVATE_CLIENT_SECRET
```

## Usage

Every action takes `--api-url`, `--token-url` and `--json`, except `init` (`--env`, `--api-url`, `--project`, `--yes`, `--no-install`, `--no-browser`, `--json`) and `logout` (`--project`, `--json`).

| Action | What it does |
|---|---|
| `read --kit-id K` / `read --asset-id A` | read one kit or asset (`--version N`, `--links` for assets) |
| `search --query Q` | search your key's context (lexical only, never calls a model; `--asset-type T` repeatable, `--max-results N`) |
| `whoami` | which project, API host, environment, the default token's scopes (`default token scopes`), the scopes this key can obtain (`permits`: any of `context:read`, `context:assets`, `context:kits`, `context:gaps`, `agents:run`, `agents:read`, `agents:manage`, `ingestion:push`; never `context:review`) and client id this key resolves to (never the secret), and `credential`: `keyring` or `environment` |
| `doctor` | check configuration, which credential is in use (`keyring` or `environment`), token, project pin, scopes and one read, and say what is wrong (exit 0 / 1 / 2) |
| `init` | sign in with your browser, bind the folder and install for your agents (see above) |
| `logout` | revoke the browser sign-in and delete it from the keyring |
| `assets` | list assets from the index: id, type, label (`--asset-type T` repeatable, `--label L`, `--limit N`, `--offset N`) |
| `kit VERB` | create or change a kit directly (`create`, `add-members`, `patch`, `remove-member`, `revert`, `retire`, `journal`; see Kits below) |
| `gap VERB` | list, read, record, edit, close or revert a gap directly (`list`, `get`, `journal`, `create`, `patch`, `retire`, `revert`; see Gaps below) |
| `kits` | list the kits your key can see: id, title and version (use an id with `read --kit-id`) |
| `asset-types` | list the asset types your key's context accepts |
| `changeset` | the open changeset: `revision`, `base_release`, `changeset` |
| `stage` | stage ops (below) |
| `tag --name T` | the release currently holding tag `T` |
| `release` | list releases, or one by `--number` or `--tag` |
| `feedback --body-file F` | show (default) or, with `--yes`, send a feedback report to Coelevate support; needs no key (see Feedback below) |

One example each:

```bash
coelevate whoami
coelevate doctor
coelevate assets --asset-type rule
coelevate kits
coelevate read --asset-id ast_123 --links
coelevate read --kit-id kit_123 --version 2
coelevate search --query "onboarding" --asset-type knowledge_page --max-results 5
coelevate asset-types
coelevate changeset
coelevate stage --op-file op.json
coelevate stage --remove-op op_123          # un-stage one op
coelevate stage --remove-op op_1,op_2      # un-stage several (the flag also repeats)
coelevate stage --remove-batch-file out.json  # un-stage every op a saved `stage --json` answer minted
coelevate tag --name stable
coelevate release --number 3
coelevate release --limit 10 --offset 0
```

### Output shapes

`--json` prints the service's answer with a few keys added, never removed or renamed, so one parser reads every action:

| Action | Added keys |
|---|---|
| `search`, `assets`, `kits` | each entry gets `id`, `type`, `title`, `summary` (taken from `asset_id`, `card`, `label` or `description`; `summary` is null when the service sends none) |
| `changeset` | `changeset_id` and `op_count` at the top level, next to `revision` and `base_release` (the open changeset stays under `changeset`, its ops in `changeset.ops[]`, each op's body under `op`) |
| `stage` | `staged_op_ids` (the ops this request minted, from `batch_ops`), `changeset_id`, `op_count`, `expected_revision`, `expected_release` |
| `stage --remove-op` | `removed_op_ids` |

### Staging

Ops are JSON passed through unchanged; the server validates them and answers 422 for a bad one.
Which fields an asset type requires comes from `coelevate asset-types --json` and from
the server's 422 text, not from this README. Every `upsert_asset` declares `base_version`
(`0` for a create). Authoring metadata (`last_updated`, `last_updated_by`) goes in the op's
`metadata`; `content` holds the asset's own fields.

```json
{
  "op": "upsert_asset",
  "asset_type": "knowledge_page",
  "base_version": 0,
  "metadata": {"last_updated": "2026-10-10T18:00:00Z", "last_updated_by": "ai"},
  "content": {"title": "Onboarding", "body": "How we onboard a client.", "owner": "ops"}
}
```

Provenance is a JSON object; each source is an object, not a string:

```json
{"rationale": "onboarding", "sources": [{"kind": "external", "title": "handbook.pdf"}]}
```

```bash
# one op
coelevate stage --op-file op.json

# a batch: a JSON array of up to 100 ops, in ONE request
coelevate stage --ops-file ops.json \
  --provenance '{"rationale":"onboarding","sources":[{"kind":"external","title":"handbook.pdf"}]}' \
  --idempotency-key import-1
```

Each batch declares the changeset revision and base release it was written against. By
default the CLI reads them from the changeset just before staging; override with
`--expected-revision` and `--expected-release` (when both are given, no read happens and
only `context:assets` is requested; both are required with `--idempotency-key`). The `stage --json` result reports the `expected_revision`
and `expected_release` the request actually sent.

After staging, `stage` and `changeset` print a `workspace_url` where a person reviews the open
changeset in the Workspace (`<workspace>/projects/<project id>/context/changes/<changeset id>`).
The Workspace origin is derived from the API host, or taken from `COELEVATE_WORKSPACE_URL`; the
field is absent when there is no open changeset or the host gives no Workspace to point at.

### Kits

A kit is a versioned selection of assets, written directly: no changeset, no review, no release
(a release never changes a kit). Publish the assets first, then create or update the kits that
hold them, naming the published ids; a kit can only hold assets that already exist. Every write
but `create` names the kit version it read (`base_version`), and a kit that has moved since is
refused with 409 `kit_moved`: re-read it and send the write again.

```bash
coelevate kit create --body '{"title": "Booking", "description": "Use it when a client books or cancels", "members": [{"asset_id": "<id>"}]}'
coelevate kit add-members --kit-id <kit id> --body '{"base_version": 3, "members": [{"asset_id": "<id>"}]}'
coelevate kit patch --kit-id <kit id> --body '{"base_version": 4, "description": "..."}'
coelevate kit remove-member --kit-id <kit id> --asset-id <id> --base-version 4
coelevate kit revert --kit-id <kit id> --body '{"base_version": 5, "to_version": 3}'
coelevate kit retire --kit-id <kit id> --base-version 5
coelevate kit journal --kit-id <kit id>
```

`--body-file` takes the same request from a JSON file. A kit write is never retried by the client.

### Gaps

A gap is project-wide context debt, not an asset: it is written directly (no changeset, no review,
no release) and names no kit. Putting a gap into a kit is `kit add-members`, which needs
`context:kits`; a `gap create` body that carries `kit_ids` is refused with exit 2 before any request.
Reads (`list`, `get`, `journal`) need `context:read`; writes (`create`, `patch`, `retire`, `revert`)
need only `context:gaps`. Every write but `create` names the gap version it read (`base_version`),
and a gap that has moved since is refused with 409 `gap_moved`: re-read it and send the write again.
Other refusals the service types: 409 `duplicate_key` (names the gap that already holds the key),
409 `release_moved`, 422 `gap_is_not_an_asset` (a staged op named a gap).

```bash
coelevate gap list --state open --kind missing_knowledge --opened-release 2
coelevate gap get --gap-id <gap id> --version 2
coelevate gap journal --gap-id <gap id>
coelevate gap create --body '{"kind": "missing_knowledge", "detail": "Nothing says who signs off a refund.", "evidence": "seen in three sessions"}'
coelevate gap patch --gap-id <gap id> --body '{"base_version": 3, "evidence": "..."}'
coelevate gap retire --gap-id <gap id> --body '{"base_version": 3, "covered_by": ["<asset id>"], "rationale": "The refund page now says it."}'
coelevate gap revert --gap-id <gap id> --body '{"base_version": 4, "to_version": 2}'
```

`--state` is `open` (default), `retired` or `all`; `--closed-release` filters closed gaps.
`covered_by` is optional on `retire`. A gap write is never retried by the client.

### Feedback

`feedback` sends a report (an incident, a bug, friction or a suggestion) to Coelevate support
through the public `POST <API URL>/context/v1/feedback` route. It needs no key and no configuration. It goes to the first of: `--api-url`, `COELEVATE_API_URL`, the
API stored with this folder's sign-in (a sign-in that cannot be read
is skipped silently), and `https://api.coelevate.ai`. A `./.env` that cannot be read does not stop it: it goes on without that file's
values and says so on stderr. A report can hold confidential detail, so the command sends nothing unless `--yes` is given; without it, it prints the destination and
the exact JSON it would send, and says that nothing was sent.

```bash
coelevate feedback --body-file report.json --json        # preview: {"preview": true, "sent": false, "would_send_to": ..., "would_authenticate": true, "payload": ...}
coelevate feedback --body-file report.json --yes --json  # send: {"feedback_id": "fb_...", "status": "received", "authenticated": true}
```

With `--yes`, a report proves who sent it when it can: the client attaches the token of the credential it already holds, a complete project API key in the
environment or this folder's sign-in, so the server can verify the project and organization. `--anonymous` sends no credential even when there is one.

- **Only to that credential's own API.** The token goes along only when the report's origin is exactly the credential's: `COELEVATE_API_URL` for a key (never `--api-url`, so a flag pointing
  elsewhere gets neither the token nor the key's secret), the API stored with the sign-in for a sign-in. Anywhere else the report goes without one.
- **Best effort, and silent.** No credential, a revoked key, a failed refresh, a keyring error, a token endpoint that is down or slow: the report goes without a token, with the same exit codes.
  It waits at most `COELEVATE_FEEDBACK_TOKEN_WAIT` seconds in all for the keyring and the token (default 5), so a keyring waiting on its unlock dialog cannot hold a report back; if the destination depended on that keyring, it counts as a sign-in that cannot be read. A sign-in's refresh that has not started by then never starts. One already running finishes after the report has left, up to three times `COELEVATE_HTTP_TIMEOUT`, so its rotated token is not lost.
- **The preview checks presence only.** `would_authenticate` is `true` when a credential for that origin is present and `--anonymous` was not given. It touches no network, so a credential that turns out to be dead shows up only in the answer.
- **The answer is the server's word.** `authenticated` is `true` only when the server verified the token. A bad token is not refused: the report is stored as not authenticated. A server that does not say counts as `false`.

The body is checked before anything goes over the wire, with the server's own limits:

| Field | Rule |
|---|---|
| `kind` | `incident`, `bug`, `friction` or `suggestion`. Not `security`: email a vulnerability to **security@coelevate.ai** |
| `subject` | 1 to 200 characters |
| `summary` | 1 to 2,000 characters |
| `details` | 0 to 20,000 characters |
| `environment` | an object of at most 30 string pairs: keys up to 64 characters, values up to 200 (versions, OS, API host) |
| `reporter_name` | optional, one line of 1 to 200 characters, no control characters |
| `organization` | optional, one line of 1 to 200 characters, no control characters |
| `project` | optional, one line of 1 to 200 characters, no control characters: a project id or name; self-reported, the server does not verify it |
| `reply_to` | optional, an email address of at most 254 characters |

Those four fields are self-reported, whatever the credential. A report with none of them is allowed. Any other field is refused. The report is sent once and never retried by the client, whatever
the answer. A failure is a JSON object on stderr that also carries `error_kind` (and
`retry_after` for `rate_limited`, `detail` for `validation`), with its own exit code:

| Exit code | `error_kind` | Meaning |
|---|---|---|
| `0` | | sent (the answer carries `feedback_id`), or a preview |
| `1` | `refused` | any other HTTP status, for example 404 from a server that does not offer the route yet |
| `2` | `invalid` / `usage` | the body broke a rule above, or (`usage`) bad arguments, an API origin that is not https (http only on this machine) or an invalid `COELEVATE_HTTP_TIMEOUT`; nothing was sent |
| `3` | `validation` | the server refused the body (HTTP 422) |
| `4` | `too_large` | the body is too large (HTTP 413) |
| `5` | `rate_limited` | too many reports, or the daily cap is reached (HTTP 429) |
| `6` | `server_error` | HTTP 5xx, or a success without a `feedback_id`: do not treat the report as received |
| `7` | `network` | could not connect (nothing arrived) or timed out (it may have arrived; it was not sent again) |

### Retrying safely

`--idempotency-key` makes a retry deduplicate, but only if the retry is the *same* request,
so a key requires `--expected-revision` and `--expected-release` too (without them the CLI
exits with code 2 and sends nothing). Read the values first, then stage with the pins and the
key; on a retry, pass the same three values and the same ops:

```bash
coelevate changeset --json          # note revision and base_release
coelevate stage --ops-file ops.json --idempotency-key import-1 \
  --expected-revision 7 --expected-release 3
```

## JSON output

Without `--json` the result is indented JSON on stdout, except for `kits`, which prints one
tab-separated line per kit (id, title, version), or `no kits` when there are none
(exit 0). With `--json` every action, `kits` included, prints one compact JSON document on
stdout (keys sorted). The JSON of `kits`, `read`, `changeset`, `stage`, `release` and `assets` also carries a top-level `project_id`, the project the key resolves to. A `kits` reply without a `kits` list is an error (exit 1), never `no kits`. A failure is a JSON object on stderr, including usage errors:

```json
{"error": "<message>", "exit_code": 1}
```

Without `--json`, a failure is `error: <message>` on stderr. `stage` results also report the
`expected_revision` and `expected_release` the request actually sent.

## Exit codes

| Exit code | Meaning |
|---|---|
| `0` | success |
| `1` | the request ran and failed: refused by the service or the token endpoint, or unreachable |
| `2` | the command could not run: bad usage, missing configuration, an unreadable or invalid input file, or a key that resolves to a different project than the pin |

`feedback` adds codes 3 to 7 for the ways a submission can fail; see Feedback above.

## Using it from a coding agent

- **Finding a kit id.** `kits` lists the kits; pass an id from it to `read --kit-id`.
- **Know the project first.** Run `whoami` (or `doctor`) at the start of a session and confirm the
  project id with the human; set `COELEVATE_PROJECT_ID` so a wrong key refuses instead of acting.
- **Rules are not in a kit.** List them with `assets --asset-type rule`.
- **Stage only, for assets.** The CLI proposes asset changes into the open changeset for a human
  to review; it has no action that publishes or lands one. An agent must not look for a way around
  that. Kits are the one thing written directly (`kit`), after the assets they hold are published.
- **Credentials from the environment only.** Never put the secret in a command line or a prompt.
- **Retry with pinned values.** Read `changeset --json` first. Stage with `--expected-revision`,
  `--expected-release` and an `--idempotency-key`, and on any retry send exactly the same three
  values and the same ops. If the server answers 409 `idempotency_key_reused`, the key was
  already used for a different request: reuse the first attempt's reported values, or pick a new key.
- Use `--json` and branch on the exit code (`0` ok, `1` the service refused or was unreachable,
  `2` fix the command or configuration).

## Troubleshooting

| Message (from the CLI) | What to do |
|---|---|
| `missing configuration: <names>. Credentials are read from the environment only, never from a flag.` | set every variable named; the secret has no flag |
| `project mismatch: this key resolves to project '<a>' but '<b>' is expected` | the key belongs to another project than `COELEVATE_PROJECT_ID` / `--expect-project`; use the right key or fix the pin (exit code 2, nothing was sent) |
| anything unclear about setup | run `coelevate doctor`: it checks each step and says which one fails |
| `--idempotency-key requires --expected-revision and --expected-release: ...` | pin both values (see Retrying safely); nothing was sent |
| `... refused (HTTP 409): ... idempotency_key_reused` + a `hint:` | the key belongs to a different request; pass the first attempt's expected values with the same key, or use a new key |
| `<token url> refused client '<id>' (HTTP <status>): <error>` | the key id, secret or scope was refused by the token endpoint |
| `could not reach the token endpoint: ...` / `... failed to connect: ...` | check `COELEVATE_API_URL` / `COELEVATE_TOKEN_URL` and the network (exit code 1) |
| `... failed to connect: The read operation timed out` (or `timed out`) | the service scales to zero, so the first call after a quiet spell can outlast the client's 30 s timeout while it starts. Reads (`read`, `search`, `kits`, `assets`, `asset-types`, `changeset`, `tag`, `release`) are retried once automatically after a short pause; this message means the retry timed out too (exit code 1). Running a read again is safe. `stage` is never retried by the client: check `changeset --json` before staging again, or reuse an idempotency key (see Retrying safely) |
| `... refused (HTTP 404)` on every call | `COELEVATE_API_URL` must be the bare API origin: the CLI adds `/context/v1/...` itself, so do not end the URL with a path (one ending in `/context` requests `/context/context/v1/...`). Check the URL, and that the deployment serves the `/context` routes, before suspecting the key. No project id belongs anywhere; the key's token names it |
| `--ops-file must hold a non-empty JSON array of ops` / `holds N ops; one request takes at most 100` | fix or split the file (exit code 2) |
| `--op is not valid JSON` / `--provenance must be a JSON object` / `cannot read --ops-file '<path>': ...` | fix the input (exit code 2) |
| `... refused (HTTP 422): ...` | the server rejected an op; read the detail, and see `asset-types --json` for required fields |

Timing can be tuned from the environment: `COELEVATE_HTTP_TIMEOUT` (default 30) and `COELEVATE_RETRY_BACKOFF` (the pause before the one read retry, default 1 second). The timeout applies to each phase of a request (connect, write, read), not to the request as a whole, and every run first exchanges the key for a token, which is attempted once and never retried. A read that times out is then attempted twice, so a caller with its own deadline must leave room for the token exchange, two attempts and the pause: roughly 3 x timeout + pause when the token exchange is slow once, and more when a request spends time in several phases. As a conservative rule, set `timeout <= (deadline - pause - margin) / 3`. There is no hard upper bound on a run's duration.

## Security

Do not put credentials in command lines, shell history or logs. To report a vulnerability,
email **security@coelevate.ai**.

## License

Copyright 2026 Gravity Break. Licensed under Apache-2.0 (see `LICENSE`). Use of the Coelevate API is governed by your Coelevate agreement and Terms of Service, not by this licence; this licence grants no API access, data rights or service level.

The CLI is developed in the `cli/` directory of a private repository. External contributions are not accepted at this time (see `CONTRIBUTING.md`).
