Skip to main content
Goal: a working refinery on your PATH, authenticated to the right workspace, and the habit of reading refinery info before assuming anything.

​
0.1 · Install

On TextQL cloud:
Prompt
On single-tenant / VPC deployments, downloads are authenticated: fetch the archive from Settings → Desktop & CLI in the web app and put refinery on your PATH. Full instructions (including a section written for coding agents): docs.textql.com/core/admin/cli.
The CLI always matches its deployment — refinery self-updates from the deployment it points at — it can never be newer than your server, and it changes version only when your deployment upgrades. refinery update --check reports without changing anything.

​
0.2 · Authenticate

Prompt
You’ll see: a device-flow URL + code (approve in the browser), or use refinery auth login --api-key KEY with a workspace API key for headless setups. Then check who you are: refinery auth status.
⚠️ Multi-workspace users: isolate your credentials — The approval page defaults to the workspace you last used in the web app — it’s easy to authorize the wrong one, and the CLI won’t warn you. For any work targeting a specific workspace, give it its own config dir and verify:REFINERY_CONFIG_DIR=/.config/refinery/acme refinery auth login —api-key KEY REFINERY_CONFIG_DIR=/.config/refinery/acme refinery info

​
0.3 · Orient with refinery info — always first

Prompt
You’ll see: the deployment you’re pointed at, your identity and roles, the grant’s scopes, which execution tools the org allows (python/bash/sql), and your existing sandboxes. Check it before assuming a capability exists — a tool that exits 4 is disabled for the org, not broken.
Exit codes are the contract: 0 success · 1 remote error · 2 usage error · 3 auth (re-login or refinery auth upgrade when the hint says insufficient_scope) · 4 tool unavailable. Every command prints exactly one JSON document on stdout — pipe it, parse it, script it. Use --pretty only for human eyes.

​
✅ Checkpoint

  • refinery info shows the workspace you intended, and you can name your enabled tools
  • You know what exit codes 3 and 4 mean and which one auth upgrade can fix