coelevate-cli 0.2.0__tar.gz

coelevate_cli-0.2.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+dist/
+build/
+.venv/
+*.egg-info/

coelevate_cli-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,7 @@
+# Contributing
+
+We do not accept pull requests or external contributions at this time.
+
+Run the tests with `uv run pytest -q`.
+
+Issues are disabled. To report a security problem, email **security@coelevate.ai** (this file also ships in the sdist, so it names the address rather than linking a file outside the package).

coelevate_cli-0.2.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

coelevate_cli-0.2.0/PKG-INFO

@@ -0,0 +1,291 @@
+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`).