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 only dependency is httpx.

Install

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

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

# isolated tool install
uv tool install coelevate-cli==0.2.0
# or
pipx install coelevate-cli==0.2.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>).

Authentication

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.

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. The CLI never prompts.

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).

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.

One example each:

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 tag --name stable
coelevate release --number 3
coelevate release --limit 10 --offset 0

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.

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

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

# 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.

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).

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.

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:

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:

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

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

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).