Redcee documentation

One precise surface for humans, CI, and agents.

Use the CLI by default. A token selects exactly one config, so there are no organization, project, environment, or config selectors to guess.

Agent guide (Markdown) LLM-optimized text OpenAPI 3.1 Open Redcee

Hard rule: never put an access token or secret value in argv, a URL, source code, logs, or chat output.

01 · Install

Install an immutable Linux binary

Choose an exact version and architecture. There is deliberately no latest download URL. Artifacts are static musl binaries with SHA-256 checksums and Cosign signatures.

REDCEE_VERSION=v0.1.0
REDCEE_ARCH=x86_64-unknown-linux-musl
curl --fail --silent --show-error --location --remote-name \
  "https://downloads.redcee.com/cli/${REDCEE_VERSION}/redcee-${REDCEE_VERSION}-${REDCEE_ARCH}.tar.gz"
curl --fail --silent --show-error --location --remote-name \
  "https://downloads.redcee.com/cli/${REDCEE_VERSION}/redcee-${REDCEE_VERSION}-${REDCEE_ARCH}.tar.gz.sha256"
curl --fail --silent --show-error --location --remote-name \
  "https://downloads.redcee.com/cli/${REDCEE_VERSION}/redcee-${REDCEE_VERSION}-${REDCEE_ARCH}.tar.gz.sig"
curl --fail --silent --show-error --location --remote-name \
  "https://downloads.redcee.com/cli/${REDCEE_VERSION}/release-signing-public-key.pem"
sha256sum --check "redcee-${REDCEE_VERSION}-${REDCEE_ARCH}.tar.gz.sha256"
cosign verify-blob \
  --key release-signing-public-key.pem \
  --signature "redcee-${REDCEE_VERSION}-${REDCEE_ARCH}.tar.gz.sig" \
  "redcee-${REDCEE_VERSION}-${REDCEE_ARCH}.tar.gz"
tar --extract --gzip --file "redcee-${REDCEE_VERSION}-${REDCEE_ARCH}.tar.gz"
install -m 0755 redcee "$HOME/.local/bin/redcee"
redcee --version

On arm64, use aarch64-unknown-linux-musl. Pin the release-key fingerprint through an independently trusted channel before a privileged installation.

02 · Authenticate

Create one short-lived automation token

Open the config in Redcee.
Choose Access tokens.
Create an Automation token for 1, 7, or 30 days.
Copy it immediately. Redcee shows it once.

export REDCEE_TOKEN='rc_at_REDACTED'
redcee config show

Or use --token-file PATH or --token-stdin. REDCEE_URL is optional; production defaults to https://redcee.com.

03 · Read

Retrieve only what the task needs

Inspect the selected config

redcee config show

The response contains config_id, decimal-string config_revision, and protected.

Read, download, or run

redcee secrets get DATABASE_URL
redcee secrets get DATABASE_URL API_TOKEN --format json
redcee secrets download --format json
redcee secrets download --format env --out .env.redcee
redcee run -- ./server --listen 127.0.0.1:8080

Existing process environment variables fail closed unless redcee run --replace-existing -- … is explicit.

04 · Write

Make every mutation explicit and retry-safe

First read the config revision. Then submit one mutation with a UUIDv7 operation ID. Values come only from a file or stdin; the CLI has no --value argument.

Create

REVISION=$(redcee config show | jq -er '.config_revision')
OPERATION_ID=$(uuidgen --time-v7)
printf %s 'the exact secret value' | redcee secrets create API_TOKEN \
  --type opaque \
  --value-stdin \
  --expected-config-revision "$REVISION" \
  --operation-id "$OPERATION_ID"

Replace

REVISION=$(redcee config show | jq -er '.config_revision')
redcee secrets replace API_TOKEN \
  --value-file ./new-api-token.txt \
  --expected-config-revision "$REVISION"

On revision_conflict, stop and inspect current state. Do not retry blindly. If transport failed and the outcome is unknown, retry only the exact request with the same operation ID.

05 · History

Inspect metadata, then append a rollback or restore

redcee secrets versions API_TOKEN --page-size 25

History never returns an old plaintext value. Use rollback for an active secret and restore when its current version is a tombstone.

REVISION=$(redcee config show | jq -er '.config_revision')
redcee secrets rollback API_TOKEN 019c2a50-5678-7abc-8123-0123456789ab \
  --expected-config-revision "$REVISION"
redcee secrets restore API_TOKEN 019c2a50-5678-7abc-8123-0123456789ab \
  --expected-config-revision "$REVISION"

06 · Agent contract

A small state machine, not a bag of commands

Obtain one config-scoped token through an approved secret channel.
Run redcee config show.
Read only the values required for the task.
Before a write, capture the current revision and one UUIDv7 operation ID.
Submit one mutation with value input from a file or stdin.
Unknown transport outcome: retry exact input with the same operation ID.
Revision conflict: stop, inspect, decide, and use a new operation ID.
Never log plaintext or the token. Revoke the token when the task ends.

Metadata and mutation commands emit one compact JSON object on stdout. Diagnostics use stable RC_CLI_… codes on stderr. Any failure exits nonzero.

07 · Raw API

Available when a process cannot run the CLI

The API is canonical, strict JSON. The CLI is the preferred thin client. See the exact schemas and examples in OpenAPI 3.1.

Method	Path	Authority
GET	`/api/v1/config`	Either token
GET	`/api/v1/secrets`	Either token
GET	`/api/v1/secrets/{name}`	Either token
POST	`/api/v1/secrets`	Automation
PUT	`/api/v1/secrets/{name}`	Automation
GET	`/api/v1/secrets/{name}/versions`	Automation
POST	`…/{version_id}/rollback`	Automation
POST	`…/{version_id}/restore`	Automation

No machine endpoint deletes, purges, manages organizations or access, or issues tokens. Those remain human browser operations.