Metadata-Version: 2.5
Name: coelevate-cli
Version: 0.2.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
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 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):

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

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

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

| 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`) and client id this key resolves to (never the secret) |
| `doctor` | check configuration, token, project pin, scopes and one read, and say what is wrong (exit 0 / 1 / 2) |
| `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` |

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

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

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

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