--- title: Quick Replies via CLI (read, create, move, delete, export and import the library from an AI agent) --- # Quick Replies via CLI (read, create, move, delete, export and import the library from an AI agent) ## What it is Omniscio ships a **Quick Replies library** — the user's personal collection of pre-written messages they can paste into a running Claude session with a single click. Each row in the library is one of three shapes: - **snippet** — an actual reply with a `label` and a body `text` (e.g. label `"Hi"`, text `"Hello — thanks for the message."`). An optional `autoSubmit: true` flag means clicking the snippet inserts AND sends the message in one step. - **divider** — a visual section break with a `label` only (no body). Renders as a horizontal rule with its label in the picker. - **folder** — a container that can hold snippets, dividers, or sub-folders. Has a `label`, no body, and can nest arbitrarily. Every row has an optional `parentId` (the string id of its enclosing folder, or `null` for top-level rows) and a `displayOrder` integer used to sort siblings within the same parent. The full structure is therefore a tree — top-level rows have `parentId: null`, everything else points at a folder row's id. The in-app picker walks that tree depth-first sorted by `displayOrder` at every level. The in-app companion page is [quick-replies.md](quick-replies.md); this page covers the **ten CLI routes** that expose the same library over the `127.0.0.1:19519` localhost HTTP server so an external AI agent (Claude Code in another project, ChatGPT with the [omniscio-control skill](/.claude/skills/omniscio-control/SKILL.md), a curl script) holding the Omniscio bearer token can read, create, edit, reparent, reorder, delete, export and import entries. The gating model is **uniform across all ten routes — and deliberately permissive compared to the rest of the CLI surface**: - **Every mutation is apply-immediately.** There is no inbox approval round-trip. `POST /quick-replies/create`, `POST /quick-replies/move`, `PATCH /quick-replies/:id`, `DELETE /quick-replies/:id`, `POST /quick-replies/reorder`, `POST /quick-replies/restore`, and `POST /quick-replies/import` all execute inline and return `200`/`201` the moment the change has landed. Quick Replies are personal text templates — no session spawn, no cost, fully reversible by re-creating or moving — so the inbox round-trip every approval-gated surface uses (cron, automations, settings, tag-library, recipes, sessions) would just add latency without any new safety. Open Omniscio clients refresh via the `QUICK_REPLIES_CHANGED` push. - **No idempotency dedup.** Unlike the cli-tags / cli-cron / cli-automations surfaces, which honor `X-Client-Request-Id` to fold a network-hiccup retry into the same pending row, the Quick Replies create body accepts a `clientRequestId` field for backward compatibility but the routes **do not consult it**. A blind retry on `POST /quick-replies/create` will produce two rows. Treat each mutation as one-shot; if you need to know whether a row landed, call `GET /quick-replies/list` — that is the source of truth. - **Reads are bearer-gated but NOT read-budgeted.** `GET /quick-replies/list` (flat), `GET /quick-replies/tree` (nested), and `GET /quick-replies/export` (the whole library as a bundle) require the bearer token in `Authorization: Bearer ` and return `401` when it is missing or invalid. They do **not** share the 60-reads-per-minute-per-token-hash budget that gates the rest of the auth-gated GET routes on this server — `/list` predates that budget, and `/tree` and `/export` were deliberately given the same plain-bearer tier so that diverging gates between read shapes of the same data would not surprise. - **Mutations share the global 10-mutations-per-minute bucket** with every other write route on this server, and return `401` when the bearer is missing or invalid. Every route on this surface — reads and mutations alike — answers a missing/invalid bearer with `401 unauthorized`; `403` is reserved server-wide for an authenticated-but-denied request, and this surface has no such case (L05-F10). The route family was renamed from `/snippet/*` to `/quick-replies/*` in schema v228 — anything you may have seen referring to `/snippet/list` or `/snippet/create` belongs to a prior surface and no longer exists. ## Where to find it Day to day the library is used from inside the app — the Quick Replies picker, where snippets, dividers and folders appear as a tree you can click, drag and edit. This page is about the other end of the same library: an AI agent reads and changes those rows from outside Omniscio, so the picker and the agent always see one set of entries. There is no separate screen to open for the agent side — it reaches the library over the same local control server the rest of Omniscio's automation is driven from, and needs the same access token. ## How it behaves Quick Replies is one of the few surfaces an AI can change with no approval step: every change is applied the instant it is made, and every open window is told to refresh itself, because these rows are personal text with nothing expensive or hard to undo behind them. The trade is that each request stands alone — repeating one that already half-succeeded makes a second copy rather than folding into the first — so the dependable way to find out what actually happened is to read the library back. Everything the agent can reach is also visible to you in the picker, and anything it gets wrong can be undone there in a couple of clicks. ## For agents ### How to use it The ten routes: | Method | Path | Tier | Status | Purpose | | -------- | ------------------------ | -------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GET` | `/quick-replies/list` | read (bearer → `401` on missing) | `200 OK` | Flat `QuickReply[]` — every row, regardless of `parentId`. Each row carries its own `parentId` so callers can rebuild the tree themselves. | | `GET` | `/quick-replies/tree` | read (bearer → `401` on missing) | `200 OK` | Nested `QuickReplyTreeNode[]` — top-level array, each node `{ item, children }`, recursively. Children at every level are sorted by `displayOrder` ascending. **The endpoint to call when an AI needs to "see what's inside what".** | | `POST` | `/quick-replies/create` | mutation (`gateAuthMutation`) | `201 Created` | Create a snippet, divider, or folder. Body discriminates on `type`; `parentId` optional on every variant. Returns the created row. | | `PATCH` | `/quick-replies/:id` | mutation | `200 OK` / `404` | Partial update — any subset of the editable fields: `label`, `text`, `autoSubmit`, the auto-title group (`autoTitleEnabled`, `autoTitleText`, `autoTitleAppendCount`, `autoTitleAppendTimestamp`), the `latestOverride*` pair, `prepend`/`appendQuickReplyIds`, and the engine/model pin (`pinnedProvider`, `pinnedModel`, `pinnedThinkingLevel`). **`.strict()` — rejects `parentId`, `displayOrder`, `type`, `id`.** Reparent via `move`. | | `POST` | `/quick-replies/move` | mutation | `200 OK` / `404` / `409` | Reparent and/or reorder. Body `{ id, parentId, beforeId? }`. | | `DELETE` | `/quick-replies/:id` | mutation | `200 OK` / `400` | Delete a snippet or divider (idempotent silent SQL — missing id still returns `200`), OR delete a folder (requires explicit `?mode=cascade` or `?mode=promote`). | | `POST` | `/quick-replies/reorder` | mutation | `200 OK` | Bulk reorder via `{ orderedIds: string[] }` (≤500 entries). | | `POST` | `/quick-replies/restore` | mutation | `201 Created` / `409` | Undo a CLI delete: recreate a soft-deleted row from a **full snapshot** body (`{ id, type, … }` — the complete row, not a patch). `409` when a live row already holds that id: restore is fail-closed rather than overwriting a row that came back on its own. | | `GET` | `/quick-replies/export` | read (bearer → `401` on missing) | `200 OK` | The whole library as ONE portable `QuickReplyExportBundle` (`{ kind, version, exportedAt, appVersion, items }`) — the identical structure the in-app **Export** writes to a file, so an agent can carry a library to another machine with no UI. Per-machine usage stats (`useCount`/`lastUsedAt`) are deliberately absent. | | `POST` | `/quick-replies/import` | mutation | `200 OK` / `400` / `413` | Merge a bundle back. Body `{ bundle }` (what `/export` returned) or `{ text }` (that JSON as a string), plus an optional `sourceLabel`. **Add-only** — never deletes, replaces or edits an existing row — and runs the SAME shared merge the in-app Import button uses. Returns the counts: `added`, `skipped`, `renamed`, `tagsCreated`, `keysDropped`. No preview round-trip (nobody is watching a CLI call). | All ten require the bearer token in `Authorization: Bearer ` (or `?token=`). The mutating seven share the global **10-mutations-per-minute** rate limit. The three GETs are bearer-checked but not read-budgeted — see the gating-model paragraph above. ### Workflow 1. **Discover what's already there with `GET /quick-replies/tree`** before proposing new folders. The tree shape mirrors the in-app picker, so the response shows you what folders exist, what is inside each one, and the sibling order. Use `/list` instead if you want a flat array (e.g. to grep all snippet bodies for a phrase without walking the tree). 2. **Create a row with `POST /quick-replies/create`.** The body's `type` field discriminates the variant — `snippet` (with `text` + optional `autoSubmit`), `divider` (label only), or `folder` (label only). Each variant accepts an optional `parentId` — omit (or send `null`) to land at the top level; pass a folder's `id` to drop the new row inside it. Returns `201` with the full new row including its server-assigned `id`. The change is **immediately live** in every open Omniscio client (push fires on success). 3. **Edit an existing row with `PATCH /quick-replies/:id`.** Partial body — send any subset of the editable fields: `label`, `text`, `autoSubmit`, the auto-title group (`autoTitleEnabled` / `autoTitleText` / `autoTitleAppendCount` / `autoTitleAppendTimestamp`), `latestOverrideEnabled`/`latestOverrideText`, `prepend`/`appendQuickReplyIds`, and the engine/model pin (`pinnedProvider` / `pinnedModel` / `pinnedThinkingLevel` — the same pin the `snippet` create body accepts). The schema is `.strict()` — sending `parentId`, `displayOrder`, `type`, or `id` returns `400`. To reparent or reorder, use `POST /quick-replies/move` instead. To convert a snippet into a folder, you cannot — delete and re-create. 4. **Reparent or reorder with `POST /quick-replies/move`.** Body `{ id, parentId, beforeId? }`. `parentId: null` moves the row to the top level; `parentId: ""` moves it inside that folder. `beforeId` (optional, defaults to `null`) controls position within the destination — `null` appends at the end; a sibling id inserts directly before that sibling. The sibling must already live inside the destination folder. Cycles (moving a folder into one of its own descendants) return `409`; an unknown `id` returns `404`. 5. **Delete a snippet or divider with `DELETE /quick-replies/:id`.** No body, no query string. The legacy path is idempotent — a missing id still returns `200`. `?mode=` is ignored on non-folder rows. 6. **Delete a folder with `DELETE /quick-replies/:id?mode=cascade` or `?mode=promote`.** Folders are the **one** case on this surface where the route refuses an unqualified delete — to avoid silently orphaning everything inside: - **`?mode=cascade`** — delete the folder AND every snippet, divider, and sub-folder inside it, recursively. One-shot wipe. Returns `200`. - **`?mode=promote`** — move every direct child up one level (into the deleted folder's parent), preserving sibling order, then delete the now-empty folder. Use this when the user wants to "ungroup" a folder without losing its contents. Returns `200`. - **Omitting `?mode=`** on a folder delete returns `400` with the error string `Deleting a folder requires ?mode=cascade … or ?mode=promote …`. - **A missing id** (no row exists with that id) falls through to the legacy idempotent path and returns `200`, not `404`. This matters: do not assume a `200` from a folder-delete means the folder existed — it means "after this call, no row with that id exists." If you need that distinction, `GET /quick-replies/list` first. 7. **Bulk reorder with `POST /quick-replies/reorder`.** Body `{ orderedIds: ["id1", "id2", ...] }` (≤500 entries). The ids are not required to share a parent — the route assigns each id a sequential `displayOrder` matching its position in the array. Use this when you have a known desired order across the whole library; use `POST /quick-replies/move` with `beforeId` when you only need to slot one row into place. 8. **Export the whole library with `GET /quick-replies/export`.** No body; returns `200` with the bundle (`{ kind, version, exportedAt, appVersion, items }`). Plain JSON — save it, or pipe it straight into `POST /quick-replies/import` on another Omniscio machine. `items` is a flat array; each row names its own `parentId` and its prepend/append refs in the FILE's id space, so the tree round-trips. `useCount`/`lastUsedAt` are absent by design. 9. **Merge a bundle with `POST /quick-replies/import`.** Body `{ bundle: }` or `{ text: "" }`, plus an optional `sourceLabel` (defaults to `"command line"`). The merge is **add-only and repeatable**: an incoming row whose `type` AND `label` AND `text` already match a row here is skipped, so re-importing the same file adds nothing; a snippet label taken by different text arrives renamed `"