Command line

Preview. The command-line client is in preview and may change. It has not had a public release yet.

coelevate-context is a command-line client for your project's context. It reads and searches the context your key can see, inspects releases, stages proposed changes to assets, and writes kits and gaps directly. It has no action that publishes a change: a person does that in the Workspace. Any agent that can run shell commands can use it, and so can you.

The CLI Reference lists every command and option. It is generated from the command itself, so it cannot drift from what the installed client accepts. This page covers what the reference deliberately leaves out: install, authentication and how an agent should use the client.

Install

You need Python 3.11 or newer; uv installs the client and takes care of that. The repositories are private, so the install uses your own GitHub sign-in (gh auth login, then gh auth setup-git).

uv tool install --from "git+https://github.com/GravityBreak-AI/coelevate-cli" coelevate-context-cli
coelevate-context --version

To pin a version, add @<commit> after the repository address. If uv warns that its tool folder is not on your PATH, run uv tool update-shell and open a new shell. Once a release is published, the repository's README gives a pinned release address to install from instead.

Authenticate

Credentials and addresses come from the environment, or from a .env file in the folder you run the command in. A secret is never accepted as a flag.

When you create a key in the Workspace, its last screen gives you these values as a ready-made .env block. See Credentials and scopes for the permissions a key needs.

Only COELEVATE_* variables are taken from a .env, and a variable already set in your environment wins. One protection against a .env you did not write: its token and API addresses are used only when the same file also sets the client id and secret and your environment sets neither. Otherwise they are ignored, and the client says so on stderr, naming the variables and never a value. Keep the file out of version control.

Set the secret without putting it in your shell history:

read -rs COELEVATE_CLIENT_SECRET; export COELEVATE_CLIENT_SECRET

Check it

coelevate-context doctor
coelevate-context whoami

doctor checks the configuration, the token, the project pin, the scopes and one read, and says which step is wrong. whoami prints the project, the API host, the permissions the key can obtain and the client id, never the secret.

Using it from an agent

• Add --json and branch on the exit code. 0 is success; 1 means the request ran and failed (refused, or the service was unreachable); 2 means the command could not run (bad usage, missing configuration, an unreadable input file, or a key that reaches a different project than the pin). With --json, a failure is a JSON object on stderr: {"error": "...", "exit_code": 1}.
• Confirm the project first. Run whoami at the start and confirm the project with the human. Set COELEVATE_PROJECT_ID, so a wrong key refuses instead of acting.
• Stage, do not publish. Asset changes go into the project's open change request. After staging, the client prints a review link where a person approves and merges them.
• Keep the secret out of the conversation. Never put it 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 changes.
• Reads retry once on their own. The service starts on demand, so the first call after a quiet spell can be slow. The client retries a timed-out read once; running a read again is safe. A stage is never retried by the client.

Troubleshooting