# Getting started

> Install the CLI, log in with a registry key, install your first patch, run it, and roll it back.

Source: https://retoque.xyz/docs/getting-started
Markdown: https://retoque.xyz/docs/md/getting-started

This walk-through installs a published patch on your own machine, runs it with and without the adapter, and rolls it back. It takes a few minutes plus the time to download the base model.

## Before you start

- Python 3.11 or newer.
- For `retoque run`: torch, transformers and peft, which the `runtime` extra installs, and about 7 GB of free memory for Qwen2.5-1.5B in float32. CPU works but is slow. The base weights take about 3.1 GB of disk.
- A Retoque account. Sign in with your email at [/sign-in](https://retoque.xyz/sign-in). Sign-in uses a one-time link, so there is no password.

## 1. Install the CLI

```sh
pip install retoque                 # verify, install, enable, disable, rollback
pip install 'retoque[runtime]'      # adds torch, transformers, peft and safetensors for `retoque run`
```

The core package depends only on PyNaCl, for signature checks. Check the install with `retoque --version`.

## 2. Point the CLI at the registry

The CLI talks to `http://localhost:3400` unless you tell it otherwise, which is only right for local development. Set the registry URL once in an environment variable or in `~/.config/retoque/config.json`:

```sh
export RETOQUE_API_URL=https://<registry host>
```

The CLI refuses plain `http` for anything except `localhost`, `127.0.0.1` and `::1`. See [Configuration](https://retoque.xyz/docs/cli#configuration) for the config file.

## 3. Create a registry key and log in

In your workspace, open [API keys](https://retoque.xyz/app/keys) and create a key. Keys start with `rtq_` and carry scopes: `registry:read` to check the key, `artifacts:download` to request downloads, and `installs:report` for opt-in install check-ins. The key is shown once, because only a hash of it is stored.

```sh
retoque login          # prompts for the key without echoing it
```

`login` checks the key against `GET /api/v1/me`, prints the account it belongs to, and stores it in `~/.config/retoque/credentials.json` with mode `0600`. The registry key is not a model API key. It is never sent to a model host or to a download link.

## 4. Find a patch and its base model

```sh
retoque models list
retoque patches search ledger
retoque patches inspect <patch>@<version>
```

`models list` prints each supported base as `org/name@<full commit>`. `patches inspect` shows the manifest summary, digests and held-out numbers the registry reports for a version. Registry metadata on its own isn't proof of anything. The signature is checked when you verify or install.

## 5. Get a license

Open the patch page on [Explore](https://retoque.xyz/explore), read the terms for the version, and claim the license. A free license is a click-through: you accept the exact sha256 digest of the terms while signed in. Paid licenses come from an onchain purchase. See [Licenses and entitlements](https://retoque.xyz/docs/licenses).

## 6. Install

> [!fix] **Install a fix.** The model reference must name the exact repository and the full 40-character commit the patch was evaluated on. Anything else is refused unless you pass `--experimental-override`.

```sh
retoque install <patch>@<version> \
  --model 'Qwen/Qwen2.5-1.5B-Instruct@989aa7980e4cf806f80c7fef2b1adb7bc71aa306'
```

Install runs a compatibility preflight, requests a single-use download link, checks the package sha256, extracts only the eight allowed files, verifies the signature and every file hash, and only then moves the files into `~/.retoque/patches/<patch>/<version>/` and writes `./retoque.lock`. Any failure leaves nothing behind. The full sequence is in the [CLI reference](https://retoque.xyz/docs/cli#what-install-does).

## 7. Run it, with and without the patch

Write the input as JSON:

```json
{
  "user": "Today is 2026-03-02 (Monday).\nPay Halcyon Realty $4,200.00 for the office rent, due next Friday."
}
```

```sh
retoque run --patch <patch> --input task.json
retoque run --patch <patch> --input task.json --no-patch
```

`run` loads the pinned base revision with `trust_remote_code=False` and safetensors only, decodes greedily, and prints which adapter sha256 was active, or that none was. The first run downloads the base model into your Hugging Face cache.

## 8. Turn it off or roll back

> [!fix] **Roll back.** Disabling keeps the files and makes `run` use the pure base model. Rolling back switches to another version that is already installed and re-verifies it first.

```sh
retoque disable <patch>
retoque enable <patch>
retoque rollback <patch> --to <older version>
retoque status
```

## Next

- [CLI reference](https://retoque.xyz/docs/cli) for every flag and exit code.
- [Python with PEFT](https://retoque.xyz/docs/python) to load the adapter in your own code.
- [Errors and troubleshooting](https://retoque.xyz/docs/errors) if a step fails.