Omniscio

Bookmarks (part 2)

The reference half of the Bookmarks page: the localhost CLI routes with their kill switch, curl examples and response shapes, plus the implementation map of the queries, launcher, favicons, IPC channels and renderer state.

On this page

What it is

This is part 2 of the Bookmarks page. It carries the reference material: the localhost CLI routes with their kill switch, curl examples and response shapes, and the implementation map of the queries, launcher, favicon service, IPC channels and renderer state behind the popover.

Where to find it

Bookmarks are reached from the bookmark icon in the toolbar pill, which opens the popover holding the search box, the Add button and the hierarchical tree; Bookmarks walks that surface end to end, including the eight kinds, the cmd confirmation gate, reordering and the Settings toggle. The material on this page is reached either from the local CLI control server on 127.0.0.1:19519 or by reading the code paths named below.

How it behaves

CLI control

Bookmarks are exposed through Omniscio's CLI control server on 127.0.0.1:19519 (override with AMC_CLI_PORT). All routes require a bearer token in the Authorization: Bearer <token> header — see the cli-control.md doc for how the token is delivered and how to fetch it from the DPAPI vault. Six endpoints are provided:

  • GET /bookmarks — list every bookmark in display order.
  • POST /bookmarks — create one (Folder / URL / Path / Exe / Cmd, plus the session / project / virtual navigation kinds). Exe bookmarks are creatable; it is launching one that the CLI refuses.
  • PATCH /bookmarks/:id — update name, value, parent, or kind.
  • DELETE /bookmarks/:id — delete (cascades to descendants for folders).
  • POST /bookmarks/reorder — reorder all rows under one parent in a single all-or-nothing transaction.
  • POST /bookmarks/:id/launch — launch a URL, Path, or Cmd bookmark. Exe is rejected.

Kill switch

Every bookmarks route is gated by the bookmarksCliEnabled setting (default true, toggle at Settings → CLI Control → Enable bookmarks CLI). When the user flips it off, every route returns 403 { ok: false, error: 'Bookmarks CLI disabled in Settings → CLI Control', disabled: true } before any auth/parse/business work runs. This is the panic-button switch — flip it off and external callers cannot read or mutate bookmarks at all, even with a valid bearer token. The setting is checked on every request, so the switch takes effect immediately without an app restart. This flag is independent from showBookmarksInToolbar — the in-app popover keeps working when this is off, and the CLI keeps working when showBookmarksInToolbar is off (see "Settings" above).

Mutations apply immediately (NOT approval-gated)

Bookmark mutations (POST / PATCH / DELETE / reorder) apply immediately, the same way /keybindings/* does — they are personal launcher entries with no destructive cascade and the user-in-the-loop gate doesn't add value. Each successful mutation emits a bookmarks:changed push so any open Omniscio popover reloads. The shared rate-limit pool covers them at 10 mutations / minute / token.

This contrasts with /cron/*, /automation/*, and most /email-summarizer/* mutations, which land as pending rows in cli_pending_actions and require user approval in the inbox before any side effect.

Read budget on GET

GET /bookmarks is bearer-gated AND read-budgeted at 60 requests / minute per token-hash. Past the budget, the server returns 429 { ok: false, error: 'read budget exceeded', retryAfter: <seconds> }. The point is to make cheap polling expensive enough that a leaked token cannot be used as a bookmark exfiltration drip.

Security: exe is rejected, cmd first-run is still gated

Three distinct hardening rules apply to launch:

  1. exe kind is rejected at the CLI surface. A POST /bookmarks/:id/launch against an Exe bookmark returns 403 { ok: false, error: 'exe-kind bookmarks cannot be launched via CLI; launch from the Omniscio UI instead' } (no kind field). The CLI cannot launch arbitrary executables — full stop. The in-app popover can still launch Exe bookmarks because that path goes through the IPC handler, which sees a real Electron renderer and a user click.

  2. cmd launches always require user confirmation in the Omniscio popover. The IPC launch input carries a confirmed field, but the launcher does not trust it: confirmed: true only advances to a fresh, main-drawn native confirmation dialog the renderer cannot forge, and anything less short-circuits to requiresConfirm. The CLI launch schema is z.object({}).strict() — no fields at all, with .strict() so additionalProperties are rejected, not silently stripped. A CLI caller cannot send confirmed to bypass the gate. When a CLI caller asks to launch a cmd row, the server returns 200 { ok: true, data: { ok: false, requiresConfirm: true } } — every cmd launch, not just a first one, because the route always sends confirmed: false; "go confirm it in the Omniscio UI, then come back" never turns into a spawn from the CLI. Note the two-level ok envelope: the outer ok: true only signals "the HTTP route handled the request"; the inner data.ok: false is the launcher's verdict. A CLI caller checking only the outer flag will misclassify a cmd launch as success — always check response.data.ok AND response.data.requiresConfirm. This is load-bearing security control — never relax the schema to accept additional fields.

  3. An Omniscio-link URL bookmark only navigates. A url bookmark whose value is an omniscio:// (or agentmc://) link is accepted by POST and PATCH only when the link is a navigation link (an action in NAV_ONLY_DEEP_LINK_ACTIONS); a link that would start a session, fork a share or send anything is refused with a 400 and a bookmarks: error. Launching one dispatches it inside the app and brings the window forward exactly like a session / project / virtual bookmark (subject to the same agent-foreground guard, which answers focusSuppressed: true when it declines). The launcher re-checks the link, so a row written straight into the database still cannot start a session.

Why the strict schema matters: a bearer token leak combined with a permissive launch schema would equal full RCE — any leaked token could fire arbitrary cmd.exe /c ... payloads. The .strict({}) schema is what keeps a leaked token bounded to "things the user has already pre-confirmed in the UI".

Working curl examples

These go through the amc-api.mjs helper, which reads the bearer token Omniscio writes at every launch in its own process and sends it for you.

# 1. List all bookmarks
node "$HOME/.claude/skill-content/omniscio-control/amc-api.mjs" GET bookmarks

# 2. Create a URL bookmark at the root
node "$HOME/.claude/skill-content/omniscio-control/amc-api.mjs" POST bookmarks \
  '{"kind":"url","name":"Anthropic","value":"https://www.anthropic.com"}'

# 3. Create a folder
node "$HOME/.claude/skill-content/omniscio-control/amc-api.mjs" POST bookmarks \
  '{"kind":"folder","name":"Work"}'

# 4. Move a bookmark into a folder (PATCH parent)
node "$HOME/.claude/skill-content/omniscio-control/amc-api.mjs" PATCH "bookmarks/<bookmark-id>" \
  '{"parentId":"<folder-id>"}'

# 5. Reorder all rows under one parent (all-or-nothing)
node "$HOME/.claude/skill-content/omniscio-control/amc-api.mjs" POST bookmarks/reorder \
  '{"parentId":null,"orderedIds":["id-a","id-b","id-c"]}'

# 6. Launch a URL bookmark
node "$HOME/.claude/skill-content/omniscio-control/amc-api.mjs" POST "bookmarks/<bookmark-id>/launch" '{}'

# 7. Delete a bookmark (cascades for folders)
node "$HOME/.claude/skill-content/omniscio-control/amc-api.mjs" DELETE "bookmarks/<bookmark-id>"

Reorder is all-or-nothing

POST /bookmarks/reorder takes the full list of every row under one parent as orderedIds, in the desired final order. The server validates that:

  • Every id in orderedIds exists in the database.
  • Every id in orderedIds currently has the requested parentId (or null for root).
  • Every existing sibling under that parentId appears in orderedIds exactly once.

If any of those checks fails, the entire reorder is rejected with 400 and no rows are mutated. There is no partial application — you cannot reorder three rows out of five and have the other two end up at random positions. This matches the behaviour the in-app drag handler relies on, so a CLI-driven reorder is indistinguishable from a drag.

Response shapes summary

All bookmarks routes wrap their result in the standard { ok, data } envelope; the inner data shape is what previous versions of this doc showed at the top level.

Endpoint Success Common failures
GET /bookmarks 200 { ok: true, data: { bookmarks: BookmarkRow[] } } 401 unauthorized (missing/invalid token), 403 forbidden (feature disabled), 429 read budget exceeded
POST /bookmarks 201 { ok: true, data: { id: string } } 400 (validation, depth cap, cycle), 401 unauthorized (missing/invalid token), 403 forbidden (feature disabled), 429 (rate limit)
PATCH /bookmarks/:id 200 { ok: true } 400 (validation, cycle, depth), 404 not found, 401 unauthorized (missing/invalid token), 403 forbidden (feature disabled), 429
DELETE /bookmarks/:id 200 { ok: true, data: { deletedCount: number } } 404 not found, 401 unauthorized (missing/invalid token), 403 forbidden (feature disabled), 429
POST /bookmarks/reorder 200 { ok: true } 400 (orderedIds mismatch), 401 unauthorized (missing/invalid token), 403 forbidden (feature disabled), 429
POST /bookmarks/:id/launch (url/path/cmd/session/project/virtual) 200 { ok: true, data: { ok: true } } 200 { ok: true, data: { ok: false, requiresConfirm: true } } (cmd — the CLI always sends confirmed: false, so every cmd launch answers this; outer ok is true but inner is false), 200 { ok: true, data: { ok: false, error: '<kind> not found' } } (nav kind whose target was deleted), 400 (folder), 403 (exe rejected, with error 'exe-kind bookmarks cannot be launched via CLI; launch from the Omniscio UI instead'), 404 not found, 401 unauthorized (missing/invalid token), 403 forbidden (feature disabled)

Every successful mutation emits bookmarks:changed so the open Omniscio UI re-renders without polling.

This page is the companion to Bookmarks, which covers the feature itself: what bookmarks are, where to find the popover, and how to add, reorder and rename them. cli-control.md describes the CLI control server those routes live on, keyboard-shortcuts.md holds the global shortcuts table the tree navigates within, and tray-and-window.md covers the Electron shell and child-process rules the launcher uses.

Last verified 2026-10-29