CLI overview

rafflesia is a headless biological evidence CLI. It parses flags, calls the API, prints a JSON envelope, and exits. There is no local state beyond your credential, and no command interprets results for you.

curl -fsSL https://rafflesia.ai/install.sh | sh

Global flags

Every command accepts these:

Flag	Purpose
`--server <url>`	API base URL. Defaults to the server recorded by `auth login`, else `http://127.0.0.1:8081`.
`--api-key <key>`	API key for this invocation.
`--json`	Print the raw JSON envelope instead of the human rendering.
`--print <path>`	Print one field. Dotted path; numeric segments index arrays, e.g. `data.documents.0.markdown`.
`--output <path>`	Write the response body to a file and print only output metadata.
`--quiet`	Suppress stdout for commands that would otherwise print a response.
`--explain`	Add CLI execution measurements to the envelope.

Human output vs. JSON

By default commands render a compact human view. Anything programmatic should pass --json and read the envelope:

rafflesia proteins confidence summary 1IEP --chain A --json

--print avoids a jq dependency for single values:

rafflesia sequences records fetch P00533 --print data.sequence.length

--output keeps large payloads off your terminal — the file gets the body, and stdout gets the metadata (path, byte count, digest):

rafflesia proteins structures fetch 1IEP --source pdb --output 1iep.json

Environment variables

Variable	Effect
`RAFFLESIA_API_BASE_URL`	API base URL. Wins over the server recorded by `auth login`.
`RAFFLESIA_API_KEY`	API key used when `--api-key` is absent.
`RAFFLESIA_ACCESS_TOKEN`	Pre-minted access token, for CI that already holds one.
`RAFFLESIA_CLI_TIMEOUT`	HTTP timeout as a Go duration (default `30m`, sized for long jobs).

Server resolution order is --server, then RAFFLESIA_API_BASE_URL, then the server recorded by auth login, then the local default.

Exit codes

The exit-code contract is deliberately narrow:

0 — the command succeeded.
1 — anything else: flag validation, transport failure, or a structured envelope error.

Failure detail is carried in the printed envelope and on stderr — the stable error.type, error.code, message, and doc_url — not encoded in distinct exit statuses. Scripts should branch on error.code, not on the exit value.

if ! out=$(rafflesia proteins structures fetch 1IEP --json 2>err.txt); then
  code=$(jq -r '.error.code' <<<"$out" 2>/dev/null || echo unknown)
  echo "failed: $code"
fi

Idempotency

Mutating operations accept an idempotency key so a retry after a timeout cannot create a second job or a second object. Over HTTP that is the Idempotency-Key header; the job-submitting CLI commands manage it for you.

Update notices

The CLI checks for newer releases in the background and prints a one-line notice to stderr after a command completes. It never blocks the command, and it is inert on non-TTY stderr and in CI. Check explicitly with:

rafflesia update

Getting started

CLI

Homology search

Ontology

AI Foundry

Evals

Global flags

Human output vs. JSON

Environment variables

Exit codes

Idempotency

Update notices

​Global flags

​Human output vs. JSON

​Environment variables

​Exit codes

​Idempotency

​Update notices

Global flags

Human output vs. JSON

Environment variables

Exit codes

Idempotency

Update notices