> ## Documentation Index
> Fetch the complete documentation index at: https://docs.textql.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Module 0 · Install & Authenticate

> Goal: a working refinery on your PATH, authenticated to the right workspace, and the habit of reading refinery info before assuming anything. (~15 min)

**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:

```text Prompt theme={null}
curl -fsSL https://cli.textql.com/cli/install.sh | sh
```

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](https://docs.textql.com/core/admin/cli).

<Note>
  **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.
</Note>

## 0.2 · Authenticate

```text Prompt theme={null}
refinery auth login
```

<Check>
  **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`.
</Check>

<Warning>
  **⚠️ 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
</Warning>

## 0.3 · Orient with refinery info — always first

```text Prompt theme={null}
refinery info
```

<Check>
  **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.
</Check>

**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