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:
exekind is rejected at the CLI surface. APOST /bookmarks/:id/launchagainst an Exe bookmark returns403 { ok: false, error: 'exe-kind bookmarks cannot be launched via CLI; launch from the Omniscio UI instead' }(nokindfield). 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.cmdlaunches always require user confirmation in the Omniscio popover. The IPC launch input carries aconfirmedfield, but the launcher does not trust it:confirmed: trueonly advances to a fresh, main-drawn native confirmation dialog the renderer cannot forge, and anything less short-circuits torequiresConfirm. The CLI launch schema isz.object({}).strict()— no fields at all, with.strict()soadditionalPropertiesare rejected, not silently stripped. A CLI caller cannot sendconfirmedto bypass the gate. When a CLI caller asks to launch a cmd row, the server returns200 { ok: true, data: { ok: false, requiresConfirm: true } }— every cmd launch, not just a first one, because the route always sendsconfirmed: false; "go confirm it in the Omniscio UI, then come back" never turns into a spawn from the CLI. Note the two-levelokenvelope: the outerok: trueonly signals "the HTTP route handled the request"; the innerdata.ok: falseis the launcher's verdict. A CLI caller checking only the outer flag will misclassify a cmd launch as success — always checkresponse.data.okANDresponse.data.requiresConfirm. This is load-bearing security control — never relax the schema to accept additional fields.An Omniscio-link URL bookmark only navigates. A
urlbookmark whose value is anomniscio://(oragentmc://) link is accepted byPOSTandPATCHonly when the link is a navigation link (an action inNAV_ONLY_DEEP_LINK_ACTIONS); a link that would start a session, fork a share or send anything is refused with a400and abookmarks: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 answersfocusSuppressed: truewhen 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
orderedIdsexists in the database. - Every id in
orderedIdscurrently has the requestedparentId(or null for root). - Every existing sibling under that
parentIdappears inorderedIdsexactly 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.
Related
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