> For the complete documentation index, see [llms.txt](https://docs.gocipher.gg/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gocipher.gg/cipher-pro/cipher-cli.md).

# Cipher CLI

<mark style="color:$info;">The</mark> <mark style="color:$info;"></mark><mark style="color:$info;">**Cipher CLI**</mark> <mark style="color:$info;"></mark><mark style="color:$info;">(</mark><mark style="color:$info;">`cipher`</mark><mark style="color:$info;">) connects your games on</mark> [<mark style="color:$primary;">**gocipher.gg**</mark>](https://gocipher.gg) <mark style="color:$info;">to an AI coding agent on your computer — Claude Code, Codex, Antigravity, Cursor or any other agent that can run terminal commands. The agent downloads a game, changes it, checks it, uploads it back and prepares its store page. You talk to the agent; the agent runs the CLI.</mark>

{% hint style="info" %}
👋 **You will find 2 sections below:**<br>

People: \
open **For people** — one prompt to paste and examples of what to ask.

\
AI agents: \
open **For AI agents** — commands, JSON output, rules and endpoints.
{% endhint %}

***

### For People

#### <mark style="color:$primary;">**How it works**</mark>&#x20;

Open your AI agent, paste the Cipher prompt, say what you want

<div data-with-frame="true"><figure><img src="https://3759408310-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5mjWmmBKwMg33kiyBSn0%2Fuploads%2FzKarybp6KSBPF6bIPfIP%2Fimage.png?alt=media&amp;token=cfc76c99-2023-4cb6-8b28-4d97ad16e67e" alt=""><figcaption></figcaption></figure></div>

#### <mark style="color:$primary;">What you need</mark>

* A Cipher account on [gocipher.gg](https://gocipher.gg).
* An AI coding agent: [Claude Code](https://claude.com/claude-code), [Codex](https://openai.com/codex), [Antigravity](https://antigravity.google), Cursor or similar.
* [Node.js 24 or later](https://nodejs.org). The agent will tell you if it is missing.

You don't need to install anything else yourself — the prompt below makes the agent do it.

<details>

<summary><mark style="color:$primary;"><strong>STEP 1: PASTE THIS INTO  YOUR AI AGENT</strong></mark></summary>

Open your agent in an empty folder (for example `cipher-games` in your home folder) and paste the following:

```
You will build and edit my games on Cipher (gocipher.gg) with the Cipher CLI.

1. Run `cipher --help`. If the command is missing, install it:
   - macOS / Linux: curl -fsSL https://gocipher.gg/api/cli/install.sh | bash
   - Windows (PowerShell): irm https://gocipher.gg/api/cli/install.ps1 | iex
   It needs Node.js 24 or later; tell me if Node.js is missing.
2. Read ~/.agents/skills/cipher-project-sync/SKILL.md (Windows:
   %USERPROFILE%\.agents\skills\cipher-project-sync\SKILL.md) and follow it for every step.
3. Run `cipher login`. It opens my browser; wait until I say I have signed in.
4. Run `cipher games --json` and show me my games as a short list.

Then ask me what I want to do. Rules: run `cipher check` before every push, never publish
for me (I press Publish on the site), never put other people's names, characters or art
in my games, and never print or share the file ~/.config/cipher/*/credentials.json.
```

</details>

<details>

<summary><mark style="color:$primary;"><strong>STEP 2: TELL IT WHAT YOU WANT</strong></mark></summary>

Talk to the agent in your own words. It finds the game, downloads it, makes the change, checks it, plays it and uploads it back:

<figure><img src="https://3759408310-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5mjWmmBKwMg33kiyBSn0%2Fuploads%2FislEc6JgmQ74NPAeLrxa%2Fimage.png?alt=media&amp;token=f420a4cb-81b9-4884-8a81-3a1b3acefe0f" alt=""><figcaption></figcaption></figure>

*An example session: improving a game and preparing a store update*

</details>

<details>

<summary><mark style="color:$primary;"><strong>THINGS YOU CAN ASK</strong></mark></summary>

* **Improve one of your games:** \
  "Download my game *Ramen Rush* and make the jump feel snappier, then push it."<br>

* **Find a game:** \
  "Which of my games are published? Download the space one."<br>

* **Fix something:** \
  "In *Neon Tail* the snake goes through walls on level 3. Find out why and fix it."<br>

* **Add content:** \
  "Add five new levels to *Pocket Coil*, each with one new obstacle, and a boss on level 10."

* **Make a new game:** \
  "Create a new portrait game: a cozy puzzle about watering plants. Make a playable first level."

* **Make a 3D game:** \
  "Create a new landscape 3D game: a low-poly endless runner. Make a playable first run."

* **Prepare publishing:** \
  "Use cover.png, banner.png and the three screenshots in ./shots to prepare the store page for *Garden Grid*."

* **Update a published game:** \
  "I published *Ramen Rush*. Upload the new version, add these screenshots and write what's new."

* **Make sounds and music:** \
  "Add a coin pickup sound and a calm background loop to *Tiny Rails*."

* **Make art and characters:** \
  "Draw a treasure chest with open and closed states, and a knight that can walk and attack."

* **Change existing art:** \
  "Make three gold versions of the chest and show me them; I'll pick one."

* **Let it work without asking:** \
  "You can spend up to 50 keys on sounds today without asking me each time."

</details>

<details>

<summary><mark style="color:$primary;"><strong>WHAT ONLY YOU DO</strong></mark></summary>

* **Sign in** once in the browser when the agent runs `cipher login`.<br>
* **Approve spending keys.** \
  Sounds, images, characters and 3D models cost keys. The agent shows the price first and gives you a link: open it, check what will be made and press **Confirm** (or **Reject**). \
  \
  Usually the page opens by itself; if it doesn't, look for **ACTION NEEDED** in the output and open the link by hand. If the agent seems to wait with nothing on screen, ask it for the approval link. Nothing is charged until you confirm. The link works for 10 minutes; after Confirm you can close the page and the game opens on its own.<br>
* **Or set a limit once.** \
  When the agent asks for an allowance, you open a link and press **Allow**: for example up to 50 keys for 8 hours, only for this game, at most 10 per asset. Generations inside the limit then run without asking.\
  \
  When the limit runs out, the agent gives you a link to raise it or approve one request. See and revoke your limits in **Settings → CLI Allowances** on [gocipher.gg](http://gocipher.gg).<br>
* **Press Publish on the site.** \
  The agent prepares the store page or the update and opens it; you review it, accept the terms and press Publish. Updates go to review, and the live version stays until the review passes.<br>
* **Keep a backup.** \
  Ask the agent to save the game folder with git after each step.

</details>

<details>

<summary><mark style="color:$primary;"><strong>GOOD TO KNOW</strong></mark></summary>

* Both **2D games** (Phaser) and **3D games** (Three.js) can be downloaded and created (CLI 0.8.0+).<br>
* The game's **orientation** (portrait or landscape) and **2D or 3D** are chosen when the game is created and can't change later.<br>
* After the agent uploads a change, **reload the game** in the Cipher editor to see it.<br>
* On another computer, paste the same prompt — the agent installs the CLI there too.<br>
* **Generated assets stay on Cipher.** \
  They are made on the server and saved in your game's asset catalog, so you see them in the Cipher editor too; the agent only downloads a copy. New drafts of existing art are not in the game until you pick one.<br>
* Asset generation needs **CLI 0.11.0+** (`cipher update`). It is live on dev now and comes to [gocipher.gg](http://gocipher.gg) with the next release (week of Nov 2, 2026); until then `cipher update` on production still installs 0.9.0.

</details>

***

### For AI Agents

Everything here is also in cipher --help and in the bundled skill \~/.agents/skills/cipher-project-sync/SKILL.md, installed by the installer or by cipher setup-codex. Read the skill before the first command.

#### <mark style="color:$primary;">**Install and Sign in**</mark>

```
command -v cipher || curl -fsSL https://gocipher.gg/api/cli/install.sh | bash
# Windows (PowerShell): irm https://gocipher.gg/api/cli/install.ps1 | iex
cipher --help                     # first line: "Cipher project sync <version>"
cipher login                      # opens the browser; a human must finish sign-in
cipher login --no-browser         # headless: prints a URL for the human to open
cipher update                     # check for a newer CLI now (also checked daily)
```

* Requires Node.js 24+. The installer puts `cipher` in `~/.local/bin` (Windows: `%LOCALAPPDATA%\Cipher`), adds it to `PATH` and installs the skill.
* A cloned folder stays bound to its project; run project commands inside it or pass `--directory PATH`.
* Credentials live in `~/.config/cipher/` with user-only permissions. Never print, copy or commit them.
* Every command supports `--json`; stdout then holds exactly one JSON value. `push` and `operation` write progress to stderr; `--progress=json` makes it NDJSON.

#### <mark style="color:$primary;">**Workflow**</mark>

```
cipher games --search "ramen" --json        # 1. find the game → projectId
cipher clone <projectId>                    # 2. folder named after the game
cd ramen-rush && bun install                # 3. dependencies (bun only; npm and pnpm are refused)
cipher status --json                        # 4. before editing: in sync?
#    … edit game-owned files …
cipher check --json                         # 5. TypeScript, lint, tests, build — must pass
cipher preview --json                       # 6. local build; play it at the returned url
cipher push --json                          # 7. upload and wait for the server build
cipher pull --rebase                        # 8. fetch files the server generated
git add -A && git commit -m "…"             # 9. local backup
```

* New game: `cipher create ./my-game --name "My Game" --orientation portrait --description "One-line pitch"` (2D, Phaser). Add `--template 3d` for a 3D game (Three.js). Orientation and template can't change later; ask the user first.
* Both sides changed: `cipher pull --rebase`; on conflicting paths use `cipher pull --into ../remote-copy` and merge by hand.
* Interrupted push or `BUILD_TRACKING_UNAVAILABLE`: the source was accepted; run `cipher operation`.

#### <mark style="color:$primary;">**Publishing**</mark>

Publishing needs a successful push build. The CLI prepares everything; the human submits it in the browser.

```
cipher listing --json                                        # current listing (or update draft)
cipher publish --title "My Game" --description "…" --genres "Puzzle,Cozy" --free \
  --cover cover.png --banner banner.png --preview p1.png --preview p2.png \
  --video gameplay.mp4 --dry-run --no-browser --json          # validate first
cipher publish …same options…                                # upload, save the draft, open the sheet
```

| Media    | Format                             | Size                                         |
| -------- | ---------------------------------- | -------------------------------------------- |
| Cover    | PNG / JPEG / WebP ≤ 10 MB          | 3:4, min 900×1200 (center-cropped)           |
| Banner   | PNG / JPEG / WebP ≤ 10 MB          | 21:9, min 1680×720                           |
| Previews | PNG / JPEG / WebP ≤ 10 MB, up to 8 | 16:9, min 1280×720; `--preview` replaces all |
| Videos   | MP4 / MOV / WebM ≤ 20 MB, up to 2  | 16:9 recommended; `--video` replaces all     |

Title ≤ 80 and description ≤ 500 characters, up to 3 genres from Cipher's list, `--free` or `--price KEYS` (at least 50), `--language NAME`.

**Published game:** the same commands fill the update draft (`status: "update_ready"`).

* Description, genres, language and media can change; **title and price can't** (`NAME_LOCKED`, `PRICING_LOCKED`).
* "What's new" notes are drafted automatically from the changes since the live version (`notesSource: "cipher"`); show them to the user. Use `--note "…"` (repeatable, up to 200 characters) when the user wants their own wording.
* Version: minor by default (v1.1); `--major` (v2.0) only when the user asks.
* `update.inReview: true` means an earlier update is still waiting for review.

Result fields: `status`, `url` (open it for the human), `step`, `ready`, `hasBuild`, `listing` or `update`, `next`.

#### <mark style="color:$primary;">**Assets (sounds, images, characters, 3D models)**</mark>

Generation costs keys and runs on the server. The CLI never spends on its own: every request is approved by the human in the browser, or fits an allowance the human approved. Needs CLI 0.11.0+.

```
cipher asset estimate --kind audio --label "Coin pickup" --prompt "Bright short chime" \
  --audio-kind sfx --duration 2 --json                        # free price; nothing is charged
cipher asset generate --kind audio --label "Coin pickup" --prompt "Bright short chime" \
  --audio-kind sfx --duration 2 --json                        # approval link → wait → pull the files
cipher asset generate --spec assets.json --json               # up to 20 assets, one approval
cipher asset character --label Knight --prompt "…" --directions s,e,n,w \
  --animation walk:"walk cycle":loop --animation attack:"sword swing"
cipher asset variant <asset-id> --prompt "make it gold" --count 3 --json   # drafts of an existing asset
cipher asset variant <asset-id> --prompt "add a crack" --reference ref.png  # edit an image into one draft
cipher asset animate <character-id> --animation jump:"jump" --json        # one new clip
cipher asset apply <variant-id> --json                        # put a chosen draft into the game (free)
cipher asset wait <spend-request-id> --json                   # resume waiting after Ctrl+C or --no-wait
```

* Kinds: `audio` (`--audio-kind sfx/music/ambient/voice`, `--duration`, `--loop`), `image` (`--style`, `--view`, `--background`, `--size`, `--state id:"prompt"`), `character` (`--projection`, `--directions`, `--animation`). Add `--estimate` to `variant` / `animate` to price them first.
* **Approval:** without an allowance, `--json` prints an `awaiting_approval` line with `approvalUrl` (`/approve/{id}`, valid 10 minutes) and `browserOpened`; the link is also on stderr. Tell the human a payment confirmation is next. The CLI opens the page unless `--no-browser` and waits. `--no-wait` returns at once; resume with `cipher asset wait`.
* **With `--no-browser`** the CLI prints `! ACTION NEEDED: … open this link by hand`. The human can't see it while your command is still waiting, so run `--no-wait`, show the link, then `cipher asset wait ID`. Never wait silently.
* **Allowance:** `cipher asset allow --budget 50 --for 8h [--per day/week/month] [--project ID / --all-projects] [--max-per-asset 10]` asks the human for one browser consent (`/approve/allowance/{id}`). Inside it, generations run without the browser. `cipher asset allow --status` shows what is left; `--revoke [--allowance ID]` ends it. The human can also revoke in Settings → CLI Allowances.
* **Over the limit:** the CLI prints why (`reason`: `allowance_limit`, `per_asset_cap`, `expired`, `out_of_scope`, with `neededKeys`, `leftKeys`, `suggestedBudgetKeys`) and an approval link where the human approves once or raises the limit.
* **Final status** (last JSON line): `completed` (exit 0: every asset or draft is ready and the files are pulled; `assets[].assetId`, `files`, `clips`), `rejected`, `expired`, `canceled`, `insufficient_keys`, `failed`. From CLI 0.11.1 also `partial` (some failed or are missing) and `generating` (a draft is still being drawn; run `cipher asset wait` later), with `counts` and a state per item; every status but `completed` exits 1.
* **Drafts** from `variant` / `animate` are listed in `variants[]` (`id`, `status`, `previewUrl`) and are not in the game. Show the previews; apply only a `ready` draft the human picked. `apply` refuses a missing, failed or unfinished draft (`status: not_applied`).
* Generated files land in `assets/generated/` and the catalog on the server; the CLI pulls them. Sounds are added to `src/generated/catalog-audio-preload.generated.ts`; if the CLI says "Push to keep it", push. `cipher asset preload` rebuilds that module by hand.

#### <mark style="color:$primary;">**What You May Edit**</mark>

| Edit                                                                            | Never edit (platform-owned or generated)                                |
| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `src/game/**` — game code                                                       | `src/engine/**`                                                         |
| `src/config/game.js`, `controls.js`, `game-me-manifest.js` — pure data literals | `.cge/**`, `.cursor/**`, `AGENTS.md`, `.gitignore`                      |
| `assets/images/local/**` — images                                               | `src/entry.ts`, `src/catalog-audio-preload.ts`, schemas                 |
| `docs/**`                                                                       | `.oxlintrc.json`, `.oxfmtrc.json`, `eslint.config.js`, `src/content/**` |

* Read `AGENTS.md` and `.cipher-sync/AGENTS.md` in the project first.
* Import engine APIs only from `src/engine/public/index.ts`.
* After changing the manifest, run `.cge/bin/cge-export-map-editor`.
* Never delete images that were already pushed; prefabs may still reference them.
* Before saying a change works, play it in `cipher preview`: load, controls, a loss or ending, restart, a phone-sized viewport and a clean console. Report what you couldn't verify.
* Push skips `.env*` and key files but uploads everything under `src/`, `assets/` and `docs/`. Keep secrets out of the project.

#### <mark style="color:$primary;">**Commands**</mark>

| Command                                                                                                | What it does                                                                                                       |
| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `cipher login [--no-browser]` / `cipher logout`                                                        | sign in through the browser / remove credentials                                                                   |
| `cipher update` · `cipher setup-codex`                                                                 | update the CLI · install the skill                                                                                 |
| `cipher games [--search TEXT]`                                                                         | list the user's games: `projectId`, `name`, `template`, `orientation`, `published`, `syncable`, `updatedAt`, `url` |
| `cipher clone ID_OR_URL [DIR]`                                                                         | download a game (folder named after the game when DIR is omitted)                                                  |
| `cipher create DIR --name … [--template 2d / 3d] [--orientation] [--description]`                      | create a 2D (Phaser, default) or 3D (Three.js) game and clone it                                                   |
| `cipher status` · `cipher pull [--rebase] [--into DIR]`                                                | sync state · fetch remote changes                                                                                  |
| `cipher diff [--local / --remote] [--patch]`                                                           | show changes                                                                                                       |
| `cipher check` · `cipher preview`                                                                      | typecheck, lint, tests, build · local build and server                                                             |
| `cipher push [--no-wait]` · `cipher operation [--no-wait]`                                             | upload and wait for the build · resume or follow it                                                                |
| `cipher thread builds` · `cipher thread import FILE.json [--dry-run]`                                  | list ready builds · import an outside conversation as a Cipher chat                                                |
| `cipher listing […]`                                                                                   | show or save listing fields                                                                                        |
| `cipher publish […] [--note TEXT]… [--major] [--dry-run] [--no-browser]`                               | upload media, save the draft or update, open the publish sheet                                                     |
| `cipher asset estimate …` · `cipher asset generate … [--spec FILE] [--no-browser] [--no-wait]`         | free price · generate after approval and pull the files                                                            |
| `cipher asset character …` · `cipher asset animate ID --animation …`                                   | new character · new clip for a character                                                                           |
| `cipher asset variant ID --prompt … [--count 1-6 / --reference IMG]` · `cipher asset apply VARIANT_ID` | drafts of an existing asset · put a draft into the game                                                            |
| `cipher asset wait ID` · `cipher asset preload`                                                        | resume a request · rebuild the audio preload module                                                                |
| `cipher asset allow --budget N (--for 8h / --until DATE) […]` · `--status` · `--revoke`                | ask for an allowance · show it · end it                                                                            |

#### <mark style="color:$primary;">**Errors**</mark>

| Code or symptom                              | Meaning and fix                                                                                                |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `LOGIN_REQUIRED`                             | run `cipher login` and wait for the human                                                                      |
| `command not found: cipher`                  | `~/.local/bin` is not on `PATH`; open a new terminal or rerun the installer                                    |
| `Invalid or duplicate file` on clone or pull | the CLI is older than the project template → `cipher update`                                                   |
| `BUILD_TRACKING_UNAVAILABLE`                 | the source was accepted; run `cipher operation`                                                                |
| conflicts on `pull --rebase`                 | `cipher pull --into ../remote-copy` and merge by hand                                                          |
| `publish` refuses                            | push a successful build first; check sizes with `--dry-run`                                                    |
| `NAME_LOCKED` / `PRICING_LOCKED`             | published game: leave out `--title` / `--price`                                                                |
| `UPDATE_DRAFT_FAILED`                        | the update draft was refused; the message says why                                                             |
| `syncable: false`                            | the game can't be synced by this CLI version → `cipher update` (0.8.0+ syncs 3D games too)                     |
| `rejected` / `expired`                       | the human rejected the request or let the 10-minute link run out; nothing was charged. Ask before trying again |
| `insufficient_keys`                          | the human needs more keys; stop and tell them                                                                  |
| `SPEND_REQUEST_PRICE_CHANGED`                | the price changed before approval; the page shows the new total and the human confirms again                   |
| `SPEND_REQUEST_TOO_EXPENSIVE`                | one request is above the per-request limit; split it                                                           |
| `partial` / `generating` (0.11.1+)           | some assets or drafts failed or are still being made; use the ready ones, `cipher asset wait ID` for the rest  |

#### <mark style="color:$primary;">**HTTP Endpoints**</mark>

The CLI is a client of these endpoints on `https://gocipher.gg`; use the CLI rather than calling them directly. Authenticated calls send `Authorization: Bearer <token>` from the credentials file.

| Endpoint                                                                                                                                               | Used for                                                                                       |
| ------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| `GET /api/cli/install.sh`, `GET /api/cli/install.ps1`                                                                                                  | one-line installers (public)                                                                   |
| `GET /api/cli/releases/latest`, `GET /api/cli/releases/{sha256}`                                                                                       | release manifest and CLI file (public; install and self-update)                                |
| `GET /api/auth/desktop/config`, `POST /api/auth/desktop/token`, `POST /api/auth/desktop/refresh`                                                       | browser sign-in and token refresh                                                              |
| `GET /api/projects`, `POST /api/projects`, `GET /api/projects/{id}`                                                                                    | `games`, `create`, folder name for `clone`                                                     |
| `GET /api/projects/{id}/sync/status`, `GET /api/projects/{id}/sync/snapshot`                                                                           | `status`, `clone` and `pull`                                                                   |
| `/api/projects/{id}/sync/transfers/{transferId}` (+ `/chunks/{offset}`, `/complete`)                                                                   | chunked, resumable uploads and downloads                                                       |
| `POST /api/projects/{id}/sync/push`, `GET /api/projects/{id}/sync/operations/{operationId}`                                                            | `push` and `operation`                                                                         |
| `GET /api/projects/{id}/sync/thread-builds`, `POST /api/projects/{id}/sync/thread-import`                                                              | `thread builds` and `thread import`                                                            |
| `GET` / `PUT /api/projects/{id}/publication-draft`, `POST /api/projects/{id}/publication-assets`                                                       | listing draft and media for a new game                                                         |
| `POST /api/projects/{id}/publication-change-notes`                                                                                                     | drafted "what's new" notes for an update                                                       |
| `POST /api/projects/{id}/asset-quotes`                                                                                                                 | `asset estimate`, `--estimate` (free)                                                          |
| `POST /api/projects/{id}/spend-requests`, `GET /api/spend-requests/{id}`                                                                               | create a request (approved in the browser at `/approve/{id}` or by an allowance) and follow it |
| `GET` / `POST /api/spend-allowances`, `GET /api/spend-allowances/{id}`, `POST /api/spend-allowances/{id}/revoke`                                       | `asset allow`, `--status`, `--revoke` (consent at `/approve/allowance/{id}`)                   |
| `GET /api/projects/{id}/asset-studio/{assetId}/variants`, `POST /api/projects/{id}/asset-studio/apply`, `POST /api/projects/{id}/asset-manager/upload` | drafts of `variant` / `animate`, `apply`, `--reference` upload                                 |

### <mark style="color:$primary;">**Rules**</mark>

* `status` before editing, `check` before every push.
* Never publish or submit for review; open the returned `url` for the human.
* Never edit platform-owned files.
* Ask about orientation and 2D / 3D before `create`.
* Commit to local git after each successful step.
* Never push third-party names, characters or art; uploads are covered by the Cipher Terms of Service.
* Never print or share credentials.
* Never approve a spend yourself or open approval links in an automated browser; the human clicks Confirm or Allow. Estimate first when the user did not name a budget.
* Never retry a rejected, expired or failed request in a loop; report it and wait for the user.

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.gocipher.gg/cipher-pro/cipher-cli.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
