Omniscio

CLI Tags Control (manage the tag library from external AI)

The eight local HTTP routes that let an outside AI agent or script list, propose, edit, and soft-delete your tag library, and apply or remove tags on individual sessions — including which routes need your approval in the inbox and which apply immediately.

On this page

What it is

Omniscio's tag library — the curated colored labels you attach to sessions for triage (bug, urgent, client-acme, followup) — is reachable from outside Omniscio over the same 127.0.0.1:19519 localhost HTTP server that already exposes cron jobs, automations, recipes, and settings. An external AI agent (Claude Code in another project, ChatGPT with the omniscio-control skill, a curl script) holding the Omniscio bearer token can list every library tag, propose new ones, edit existing ones, soft-delete obsolete ones, and apply or unapply tags to specific sessions — all from a shell.

There is one kind of session tag, described in tag-manager.md: tags rows with name / color / description / icon / scope (global or specific projects), applied to sessions via the session_tags join. This page covers the eight library routes that expose that system over HTTP, plus two older session routes that now work on the same tags by name (see "Setting a session's tags by name" below).

The gating model is split across the eight routes by blast radius:

  • Library mutations are approval-gated. POST /tags (create), PATCH /tags/:id (update), and DELETE /tags/:id (soft-delete with cascade) all enqueue tags.create / tags.update / tags.delete rows in the same cli_pending_actions queue used by cron jobs, automations, settings PATCH, and session lifecycle. The route returns HTTP 202 immediately; the change does not apply until the user clicks Approve in the Omniscio inbox. The user-in-the-loop guarantee is identical to the twenty-one other approval-gated CLI capabilities documented in cli-pending-actions.md, and shares the same open-pending cap.
  • Per-session apply / unapply is immediate. POST /sessions/:id/tags (apply a library tag to one session) and DELETE /sessions/:id/tags/:tagId (remove that application) apply inline with no inbox row. The reasoning matches the in-app T-hotkey picker — applying a tag to a single session is reversible by removing the chip, the per-session 10-tag cap is enforced at insert time, and the project-scope visibility rule is checked synchronously, so adding an approval gate would just add latency without any new safety.
  • Reads are bearer-gated and read-budgeted. GET /tags (list every active library tag with session counts) and GET /sessions/:id/tags (list applied tags for one session) require the bearer token and are read-budgeted at 60 reads/minute per SOURCE — keyed on the source session the dispatcher publishes for the request, with the bearer hash used only when the request names no source — under a 600 reads/minute fleet-wide backstop that bounds every source combined. It is not one 60/min bucket shared by every token holder.

The split mirrors the in-app surface: tag management lives in the Tags view (deliberate, dialog-driven, low-frequency), per-session apply lives behind the T hotkey (frequent, lightweight, instantly reversible).

Where to find it

There is no Omniscio screen for any of this — the whole feature lives outside the app. Its surface is the local HTTP control server on your own machine, the same one that already answers for cron jobs, automations, recipes, and settings; an outside AI agent or a script reaches it by holding your Omniscio token. Anything that changes your tag library is not applied straight away: it is queued and appears in the Omniscio inbox as a card you approve or reject by hand.

How it behaves

How to use it

The eight routes:

Method Path Approval-gated? Status Purpose
GET /tags n/a (read) 200 OK List every active library tag with derived scope, projectIds, sessionCount. Optional ?projectId=X narrows to tags visible in that project.
POST /tags Yes 202 Accepted Queue creation of a new library tag. Body: { name, color?, description?, icon?, projectIds? }.
PATCH /tags/:id Yes 202 Accepted Queue an update. Body is a partial — only included fields change; omitted fields are preserved. At least one field is required.
DELETE /tags/:id Yes 202 Accepted Queue soft-delete. Preview text embeds the cascade size (Delete tag "foo" (used by 3 sessions)).
GET /tags/:id/sessions n/a (read) 200 OK Reverse lookup — every session id carrying this library tag (what the Tags view uses to show "everything tagged X"). Unknown id returns an empty list.
POST /sessions/:id/tags No (immediate) 200 OK Apply a library tag to one session. Body: { tagId }.
DELETE /sessions/:id/tags/:tagId No (immediate) 200 OK Remove that application. No body.
GET /sessions/:id/tags n/a (read) 200 OK List TagApplication rows ({ sessionId, tagId, appliedAt, appliedBy }) for one session.

All eight require the bearer token in Authorization: Bearer <token>, header-only — a ?token=<token> query param is rejected with 401 (no CLI route outside the legacy GET /project/:name/new spawn form opts into query-token auth). The mutating five share the global 10-mutations-per-minute rate limit; the three GETs are read-budgeted at 60 reads/minute per source (the requesting source session; the bearer hash only when no source is named), bounded by a 600 reads/minute fleet-wide backstop.

Workflow

  1. Discover what's already there with GET /tags before proposing duplicates. The response includes scope ('global' | 'project'), projectIds (empty array when global), and sessionCount per row, so you know what's in use and what's free.
  2. Propose a new tag with POST /tags — name + color + scope. Send X-Client-Request-Id (≤64 chars) so retries are idempotent in a 30-day window. The route returns HTTP 202 with the queued row's id. Tell the user "open Omniscio's inbox and approve to apply" and stop. The tag does not exist until the user clicks Approve.
  3. Edit a tag with PATCH /tags/:id — partial body, only the fields you want to change. Omitted fields are preserved at dispatch time (the dispatcher merges the patch into the existing row), so you can rename a tag without re-sending its color and scope. Same approval flow as create.
  4. Delete a tag with DELETE /tags/:id — no body. Approval card preview embeds the cascade size — "Delete tag 'foo' (used by 3 sessions)" — so the user sees the blast radius before approving. Approval cascades: the dispatcher hard-deletes every session_tags row for that tag, then soft-deletes the library row (is_deleted = 1). 5. Apply a library tag to a session with POST /sessions/:id/tags body { tagId }. Returns 200 immediately on success. Returns 409 with reason: 'cap' if that session already carries 10 tags, or reason: 'visibility' if the tag's project scope excludes this session's project.
  5. Remove an application with DELETE /sessions/:id/tags/:tagId. Returns 200 if a row was actually deleted, 404 if the tag wasn't applied to that session.
  6. Inspect what's applied with GET /sessions/:id/tags — returns the raw join rows. Pair with GET /tags if you need the tag color / name.

Approval flow recap

For the three approval-gated routes (POST /tags, PATCH /tags/:id, DELETE /tags/:id):

  1. Route returns HTTP 202 with { ok: true, data: { id, actionKind, status: 'pending', previewText, ... } }.
  2. The pending row appears in Omniscio's inbox as a yellow card titled with the preview text (e.g. Create tag "urgent", Update tag "bug", Delete tag "stale" (used by 7 sessions)).
  3. The user clicks the card — a dedicated TagsApprovalPane opens (separate from the generic JSON-payload pane) showing a per-kind preview: name + color swatch + scope for create, before/after for update, name + cascade size for delete.
  4. Approve → the dispatcher executes the side effect (create row + scope rows / merge patch / cascade-delete + soft-delete), emits tags:changed (with affectedSessionIds for delete), and stamps dispatched_at. Reject → row flips to rejected with the reason, no side effect.
  5. The renderer's open clients receive the tags:changed push and refresh the library + session chip strips automatically.

The dispatcher distinguishes permanent from transient dispatch failures. Permanent — name collides at approve-time (someone else created the same name in-app), tag soft-deleted between enqueue and approval, target row missing — flips the pending row to rejected with PermanentDispatchError so the user doesn't loop forever clicking Approve. Transient — DB lock, network blip — reverts the row to pending for retry.

Idempotency

The three approval-gated routes accept an X-Client-Request-Id header (≤64 chars). When set, the same id within a 30-day window returns the existing pending row (HTTP 200, body includes idempotent: true) instead of queuing a duplicate. The lookup is scoped per action_kind, so the same id can map to a tags.create and a tags.update and a tags.delete independently.

The two immediate routes (POST /sessions/:id/tags, DELETE /sessions/:id/tags/:tagId) are idempotent at the database layer (INSERT OR IGNORE on apply, no-op delete on absent join row), so client-side idempotency keys aren't needed there.

Setting a session's tags by name

Two older session routes work on the same tags, by name rather than by id:

  • POST /session/:id/update-tags — body { tags: [names] } sets the session's tags to exactly that set. Each name resolves (ignoring capital letters and accents) to an existing tag. An unknown name is refused with HTTP 422 and a message to create it first via POST /tags while require approval for CLI tags is on (the default); when that approval is off, the unknown name is created (global, with an automatic colour) and applied. More than 10 names is also a 422. Hidden internal markers on the session are kept.
  • POST /sessions/delete-tag-globally — body { tag } deletes the tag of that name through the same tags.delete approval as DELETE /tags/:id. A name that matches no tag returns 200 with affectedSessionCount: 0.

Examples

# Read the bearer token from Omniscio's auto-delivered file
TOKEN=$(<~/.amc/cli-token)

# 1. List every library tag with session counts
curl -s -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:19519/tags

# 2. Propose creating a global "urgent" tag (red, with description)
curl -X POST http://127.0.0.1:19519/tags \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Client-Request-Id: tag-create-urgent-2026-05-07" \
  -d '{
    "name": "urgent",
    "color": "#ff4444",
    "description": "Needs response within 1 hour",
    "icon": "alert"
  }'
# Returns 202 with the pending row. The tag doesn't exist until the user
# approves in Omniscio's inbox.

# 3. Propose creating a project-scoped tag (visible only to two projects)
curl -X POST http://127.0.0.1:19519/tags \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Client-Request-Id: tag-create-acme-2026-05-07" \
  -d '{
    "name": "client-acme",
    "color": "#1f9d55",
    "projectIds": ["proj-uuid-a", "proj-uuid-b"]
  }'

# 4. Rename a tag (PATCH only the name; color, description, scope preserved)
curl -X PATCH http://127.0.0.1:19519/tags/<tag-uuid> \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Client-Request-Id: tag-rename-2026-05-07" \
  -d '{"name": "high-priority"}'

# 5. Delete a tag (cascade size shown in approval preview)
curl -X DELETE http://127.0.0.1:19519/tags/<tag-uuid> \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Client-Request-Id: tag-delete-stale-2026-05-07"

# 6. Apply a library tag to a session (immediate — no approval)
curl -X POST http://127.0.0.1:19519/sessions/<session-uuid>/tags \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tagId": "<tag-uuid>"}'
# 200 OK on success
# 409 {"reason":"cap"} if the session already carries 10 tags
# 409 {"reason":"visibility"} if the tag's scope excludes this session's project

# 7. Remove a tag from a session (immediate)
curl -X DELETE http://127.0.0.1:19519/sessions/<session-uuid>/tags/<tag-uuid> \
  -H "Authorization: Bearer $TOKEN"
# 200 if a row was actually removed
# 404 if the tag wasn't applied to that session

# 8. Inspect what's applied to a session
curl -s -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:19519/sessions/<session-uuid>/tags
# {"ok":true,"data":{"applications":[{"sessionId":"...","tagId":"...","appliedAt":"...","appliedBy":"user"},...]}}

Out of scope (v1)

  • applied_by: 'cli' — the database has the field but the CLI routes hard-code applied_by: 'user' so a CLI-applied tag is indistinguishable from a user-applied tag in the UI. Distinguishing them was deferred until there's a UX surface that benefits from the distinction.
  • Bulk apply / unapply — there is no POST /sessions/tags/bulk route. Apply per-session if you need to fan out across many sessions; the 10-mutations-per-minute rate limit caps the burst at 10 per minute (and the in-app UI doesn't have a bulk-apply surface either).

The in-app tags these routes drive are described on the tag manager page; how people put tags on a session is on the session tags page; the approval queue every mutation lands in is on the CLI pending actions page; and the server itself — token handling and the full route catalog — is on the CLI control page.

  • tag-manager.md — the tag model (managed in the Tags view), scope rules, sticky behaviour, deletion cascade, IPC contract.
  • session-tags.md — how people put tags on a session with the T picker.
  • cli-pending-actions.md — the shared approval queue every approval-gated CLI mutation lands in.
  • cli-control.md — the CLI server itself, token handling, the full route catalog.
  • omniscio-control skill — the external-AI side of the contract: how an AI queues these actions in practice.

Last verified 2026-10-10