Omniscio

CLI Control (control Omniscio from scripts and hotkeys)

CLI Control is the local-only HTTP door into Omniscio: how to turn it on, copy or regenerate its token, drive the app from a script or a hotkey, and what it refuses to do without your say-so. This overview covers what the server is, where its switch and token live, and the walkthrough for calling it.

On this page

What it is

CLI Control is a tiny HTTP server that Omniscio runs on your own machine at 127.0.0.1:19519. It lets any tool that can make an HTTP request — AutoHotKey, PowerShell, curl, Python, Bash, an external AI like Claude Code — navigate Omniscio, launch sessions with a pre-typed prompt, bring the window to front, pop a project or integration out into its own window, or create/schedule/toggle cron jobs. It's on by default, localhost-only (cannot be reached from other machines), and any mutation (starting a session, creating a cron job) requires a token that Omniscio auto-generates and stores at ~/.amc/cli-token with OS-level file-permission hardening. Read-only endpoints like /ping and /status are open, so your scripts can check health without handling the token.

Where to find it

CLI Control lives in Settings → CLI Control, which is where you switch the server on or off, read and copy its token, regenerate that token, and decide which outside requests must wait for your approval. It is not a panel you open to use; it is a door other programs knock on, and that Settings page is where you choose how far it opens.

How it behaves

How to use it

  1. Confirm it's on and copy your token. Open Settings → CLI Control. CLI Control ships enabled. The Token field shows a hex string you can copy; use Regenerate to invalidate the old one at any time. A small "Created N ago" line under the token shows its age and turns amber once it is over 90 days old, nudging you to Regenerate (the token itself never auto-expires). A fresh token is also mirrored to ~/.amc/cli-token (%USERPROFILE%\.amc\cli-token on Windows). If that file is ever deleted, emptied to 0 bytes or left blank, Omniscio rewrites it from its own stored token within about a minute (at once when it notices the change); a file that already holds a different non-empty key is left alone, so two installs sharing one folder do not overwrite each other.
  2. Call the read-only endpoints. GET http://127.0.0.1:19519/ping returns {ok: true}. GET /status is open for liveness — a tokenless caller gets the identity triple and the readiness bits — but the project overview (a project count, the project-name list, and the integration aliases) comes back only to a caller with a valid bearer; a tokenless call is still 200, with those fields omitted rather than a 401. It also answers 503 instead of 200 when the database readiness probe fails (the JSON body still rides along). GET /cron/jobs, /cron/jobs/:id, /cron/jobs/:id/runs, /cron/runs/upcoming return cron state — these require Authorization: Bearer <token> (they surface private cron data) and share a per-token 60/min read budget. No token is needed for /ping, and none is needed for /status when all you want is liveness. /status carries two readiness bits plus a failure list for scripts that gate on it. ready is the database and spawn path. routesReady says the command-server route REGISTRATION PASS HAS FINISHED — it is false only while groups are still mounting, so a false is transient and a retry genuinely differs. routeFamiliesFailed is the separate, new signal (2026-10-13): it names any route family whose import rejected or whose registrar threw at start-up, and it is empty on a healthy boot. Read it to tell "this app never mounted that route" from "I have the wrong endpoint" — a 404 with a non-empty routeFamiliesFailed is a permanent fact about the running build, not something to retry. These are deliberately two fields: routesReady cannot carry the failure without turning a permanent fault into a transient-looking signal, which is what the runners that gate on it would then wait out forever.
  3. Navigate or focus. GET /inbox, /focus, /project/<name> (fuzzy-matched, case-insensitive), or /superprompt/<id>. These need a valid bearer token (Authorization: Bearer <token>) — a tokenless call is rejected with 403, even one that claims to come from a same-origin page (Sec-Fetch-Site: same-origin), because any local program, or anyone on a machine linked through an SSH remote's line home, can send that header. This closes a hole where a program without your token could steal window focus or force navigation. Hotkey macros must send the Authorization header. (/ping stays open with no token; /status answers a tokenless caller with liveness only — the project overview needs a bearer.)
  4. Launch a session or create a cron. POST /project/<name>/new — Authorization: Bearer <token> and a JSON body like { "prompt": "..." } — spawns a session and auto-sends the prompt. Use POST: it is the Unicode-safe, header-auth form. The legacy GET /project/<name>/new?token=<YOUR_TOKEN>&prompt=<url-encoded prompt> form still works for old AHK/curl scripts, but it is deprecated — it carries the token in the URL and drives a billable spawn from a GET, so it answers Deprecation: true plus a successor-version link pointing at the POST form, and logs a line naming the replacement on every use. Build nothing new on it. The spawn is created by the background engine and is durable — as of 2026-06-04 it no longer depends on the Omniscio window being responsive, so a 200 means the session was actually created, and a spawn survives a busy/frozen UI or an app restart mid-spawn (a rapid burst is paced, returning 202 for the queued ones). By default the new session opens silently in the background — Omniscio does NOT come to the foreground. That's the right default for agent-driven calls (the user is working in another app and shouldn't be yanked away). A focus field is still accepted so old callers do not break, but its value is discarded — a CLI-driven spawn never brings the window forward. To put Omniscio in front, call GET /focus or POST /window/open after the spawn; both honour the agent-foreground rules below. /focus and /window/open bring the window forward; /project/<name> (activate-project, no /new), /inbox, /settings/open, and the note / mind-map / Gmail-thread / saved-prompt routes SWITCH which screen you're looking at — and the "don't take over the user's screen" rule covers both. (a) Foreground: an agent-initiated /focus / /window/open (a call sending X-AMC-Source-Session-Id) is auto-blocked while a different app owns the foreground (returns focusSuppressed: true + an inbox note you can silence via its "Turn off these notices" button or Settings → Notifications → "Screen-grab block notices"); it still foregrounds when you're already in Omniscio, or when you opt in at Settings → CLI Control → "Let agents bring Omniscio to the front" (default off). (b) View-switch: an agent-initiated activate-project / /inbox / setting / note / mind-map / Gmail-thread / saved-prompt request no longer changes your view directly — while you're IN Omniscio it drops a click-to-go toast ("…wants to switch to X — Go there") that navigates only when you click, and while you're in another app it drops an inbox note instead — that note keeps the destination the agent asked for and offers Go there (replays exactly that navigation), beside a one-click Let agents switch my view that turns the opt-in on from the card, with an Undo; either way it never moves you on its own, unless you opt in at Settings → CLI Control → "Let agents switch your view directly" (default off). GET /inbox is stricter than the rest: a bare agent-initiated call is treated as a READ — every helper that makes it means "what is waiting on the user" — so it surfaces nothing at all, not even the toast, and answers { navigated: false, reason: "agent-read-never-navigates" } (the direct-navigation opt-in below still overrides this, as it does everywhere). An agent that means to open your inbox asks for it with GET /inbox?navigate=1, which rides the ordinary suggestion path (toast / inbox note, and direct navigation if you opted in). A human's own hotkey, notification click, phone tap, or the in-app UI is never affected. /cron/jobs supports POST (create), PATCH /cron/jobs/:id (update), DELETE /cron/jobs/:id (delete), POST /cron/jobs/:id/run (fire now), and POST /cron/jobs/:id/toggle (enable/disable). All cron mutations require Authorization: Bearer <token> and are capped at 10 per minute. There is no ceiling on how many cron jobs an install may hold — the MAX_CRON_JOBS row-count cap (200, later 500) was removed on 2026-09-06 because it measured the wrong quantity: it counted every row in the table (inactive, rejected, spent one-shots, wake schedules), so an install with 199 dead rows was refused a create while one with 199 jobs firing every five minutes was not. What replaced it is the create-RATE policy above, which is what a runaway caller actually runs into; the single source is cron-job-create-rate.ts.
  5. Pop a project or integration into its own window. POST /window/open with a JSON body { "projectId": "<id>" } opens (or focuses) that project — a real project or an integration like Tasks — in its own themed desktop window, the HTTP half of the in-app "Open in new window" button. projectId takes a project UUID, a friendly alias, or an integration id such as tasks-v2. It's bearer-authed, shares the 10/min mutation cap, and is idempotent (a second call just focuses the existing window, returning state: "already-open"). Full details — id resolution, response shape, and the 404 / 409 (a dedicated window like KMS has its own route) / 400 (no panel to show) cases — live on the omniscio-control windows surface. (Yes, this is supported: earlier notes that called a CLI pop-out "out of scope" predate this route.)
    • POST variant for Unicode-safe prompts. POST /project/<name>/new exists alongside the GET form because Windows mangles non-ASCII chars (em-dash, arrows, accented chars, emoji, non-Latin scripts) in the cmd.exe / Git Bash argv pipeline before curl can encode them — they arrive at the spawned session as ? or U+FFFD replacement chars. The POST variant takes the prompt as a JSON body field, which streams from the socket as raw bytes and bypasses argv encoding entirely. Auth is header-only (Authorization: Bearer <token> — query-string ?token=... is rejected with 401), Content-Type must be application/json (charset suffix allowed), body schema is .strict() and accepts, every field optional: prompt, name, provider, model, thinkingLevel, isolationOverride, location ('local' | 'cloud'), localReason, branch, cloudProvider, suppressOverlayPrompts, blindSpawn, holdForApproval, source, and focus (accepted and discarded, above). location: 'cloud', branch and holdForApproval are how a caller asks for a cloud spawn, a named branch, or a returned-work hold, and each is REFUSED rather than silently ignored when it cannot apply. The old review / reviewer lock shapes are refused too, with a pointer to POST /reviews. Empty body is allowed for a source-less call (no prompt → blank session), but a prompt-less agent spawn — one sending X-AMC-Source-Session-Id — is rejected 400 ("a spawned session needs a prompt"): an agent always has a task for the child it spawns, so a missing prompt is a caller bug that would otherwise leave a dead empty session. Only the literal boolean true is accepted for a flag, and focus in particular changes nothing. provider forces the engine for this one session; omit it and the session uses the project's configured default provider (the one set via PATCH /project/:id defaultProvider, gated by the show-alternate-providers master toggle), falling back to Claude — the same provider the UI's + New button would pick, so a CLI / cron / recipe spawn into a project defaulted to e.g. Gemini now correctly starts on Gemini instead of silently using Claude. name stamps an exact session title instead of letting the AI titler infer one. The 1 MB body cap matches the other mutations, but /new is deliberately not on the 10/min mutation bucket — spawns are serialized by a FIFO spawn pacer at one every 30 s (≈2/min), and a burst is queued and released in order (each queued spawn returns 202) up to a 50-deep runaway backstop that returns 429. Validation errors are self-explanatory: a malformed JSON body returns 400 with the parser’s own message, the character position, and a short snippet of the body around the break (echoed only to the caller, never logged), and an unrecognized body field returns 400 with a did-you-mean hint (Unexpected field: message — Did you mean ‘prompt’? — common aliases like message/text/task map to prompt, and close typos suggest the nearest accepted field). An optional X-Client-Request-Id header (≤64 chars) makes a retry safe — reuse the same id and a duplicate POST returns 200 { idempotent: true } instead of spawning a second session (without it, /new dedups only a request that arrives while an identical one is still in flight). The id is claimed before the route does any of its work, so a retry that lands while the first request is still going finds it. That replay is a receipt, not a bare acknowledgement: it carries the ORIGINAL spawn's spawnId, plus status and sessionId once the session exists — so a caller that timed out and retried learns WHICH session its first call made instead of being told only that something happened. A CLOUD spawn is answered as soon as it is accepted, not when it is up: location: 'cloud' returns 202 { ok: true, accepted: true, status: 'pending', spawnId, sessionId } while the machine is still being booted or attached (a cold bring-up runs into minutes) — the sessionId is the id the session will be created with, so you can address it at once (GET /session/:id answers { queued: true } until it starts) and GET /spawn/:spawnId reports the same id. Treat pending as success and confirm it — do NOT retry: the request that got no answer is the one that used to hold the socket open for the whole bring-up, which is how a launcher ends up paying for three cloud workers on one task. Source required by default: with requireSpawnSourceSession on (the default), both /new forms AND POST /agent/sessions refuse a spawn that sends no source with 400 — pass X-AMC-Source-Session-Id: $AMC_SESSION_ID (an Omniscio-spawned agent has it in env) so the child links back to its origin, or the user turns the setting off in Settings → CLI Control for anonymous script/hotkey spawns. Only the global CLI token spawns by default: the /new forms accept the global CLI token (~/.amc/cli-token), but an in-app session token, an agent's scoped per-session token (the $AMC_CLI_TOKEN Omniscio injects into every spawned session), and a cloud session's own token are ALL refused (401/403) unless the user opts in at Settings → CLI Control → "Let agents spawn sessions with their own token" (allowAgentTokenSpawn, default off; it governs every one of those token kinds on this road — spawnAuthAllows returns true only for cli-token, and in-app-session / agent-session / cloud-session all fall through to the setting) — so a compromised MCP server / npm dep reading an agent's env can't spend money by spawning paid sessions; the narrowest per-MCP-server token never spawns. (A live crew lead is the one exception, and it applies at every start door because they all ask the same predicate — see the start-authority contract.) (The separate POST /agent/sessions agent-driven-spawn path has its own agentDrivenSessionsEnabled gate.)
    • The Free plan's sessions-at-once limit applies here too. When that limit is switched on and the signed-in plan is Free, a request that would start a new session while 10 are already running or queued answers 429 with code RATE_LIMITED and the plan-limit message, and nothing starts. It covers every agent route that starts a new session (including the legacy GET form), not routes that message or restart an existing one. Pro plans and an install with nobody signed in are never limited.
    • Confirming a spawn — GET /spawn/:spawnId. Every /new reply (200 immediate, 202 queued, 202 starting, 202 accepted) carries a durable spawnId; this route resolves it. Response { ok: true, spawnId, status, sessionId, error } where status is created (the session exists — sessionId names it), pending (accepted, not driven yet — sessionId is the id it will be created with), failed (the driver gave up, or its caller withdrew it — error says why), or unknown (no spawn by that id). Resolved from the session's own origin_spawn_id anchor, so it is exact. Confirm with this, never by listing /sessions and taking the newest — a perf:instant-new-session prewarm shell is indistinguishable from a fresh spawn (both blank + ready), so a timestamp guess picks the wrong one. Read-only, on the 60/min read budget; the global CLI token sees any spawn, an agent's scoped token only spawns it originated (403 otherwise).
    • Withdrawing a queued spawn — DELETE /spawn/:spawnId. A spawn paced into the queue (202) can be taken back before it starts. The spawn pacer gives each caller a share of its 50-deep queue measured from the queue itself, so a request you no longer want holds a slot you cannot use — and until this route there was no way to give one back. Withdrawing cancels the request itself, not just its place in line, so nothing can start it later — GET /spawn/:spawnId then answers failed with the error "withdrawn by its caller". Answers 200 with withdrawn (how many queued entries were removed), cancelled (whether the spawn is withdrawn for good — false if it had already begun starting, or there was nothing to cancel) and queued (whether it is still waiting); an id that already fired or was never queued is a harmless 200 no-op, never a 404. The global CLI token may withdraw any spawn; an agent's scoped token only one it originated, never an operator's or a cron's (403 otherwise). On the mutation budget.
# Unicode-safe — em-dash, arrows, emoji, Chinese, accents all survive intact
node "$HOME/.claude/skill-content/omniscio-control/amc-api.mjs" POST project/MyProject/new \
  '{"prompt":"Em-dash — and arrow → and emoji 🚀 and Chinese 你好"}'

# A spawn never takes the foreground; follow it with /focus if you need the window
node "$HOME/.claude/skill-content/omniscio-control/amc-api.mjs" POST project/MyProject/new \
  '{"prompt":"continue from where we left off"}'
  1. Hand the token to an external AI safely. The omniscio-control skill bundle reads ~/.amc/cli-token automatically and POSTs with approval gating enforced server-side — see omniscio-control.md (the consolidated entry covering cron, automations, settings, sessions, recipes, projects, tags, away-mode, keybindings, and pending actions).
  2. Trigger pre-approved recipes. POST /recipes/run lets an authenticated agent fire a multi-step Claude workflow without opening Omniscio. Two orthogonal gates apply: the recipe must have agentTriggerable.enabled set in the Recipe Editor's "Agent triggering" card (others return 403 — an agent cannot trigger an arbitrary recipe) AND the recipe must have cleared the authoring approval gate (approvalStatus ∉ {pending, rejected}; pending/rejected recipes return 400 even when the agent-trigger flag is on). When someone is signed in, their verified plan must also include recipes, or the route answers 403 with code FORBIDDEN — the same check the Run button makes; a solo install with nobody signed in is never refused. A 30-second cooldown per (recipeId, projectId) tuple prevents accidental retry-loop double-fires; the engine still enforces its singleton lock so concurrent triggers return 409. GET /recipes/triggerable is the discovery endpoint — agents call it first to see what's flagged. Full request/response shapes, error codes, and cost-cap behavior: agent-trigger-recipes.md.

When something hammers the port with the wrong token

Denied requests are counted in a rolling 60-second window. Past 20 denials in that window Omniscio raises ONE inbox card — "Many failed tokens on the control port" — and keeps updating that same card rather than adding another, so a burst is one row no matter how long it runs. Past 50 the server also starts briefly refusing every request that arrives without the right token, and the card is raised again with the larger count so the refusal is visible rather than silent; a command of your own that arrives in that window can be refused with it until the burst stops.

The card names the count, the time the window's first bad request arrived, and the busiest callers as method + caller class + path (the query is dropped, so nothing a caller writes can appear in the card). The caller class is one fixed word worked out from the request's User-Agent — undici for a Node script (including Node's own fetch, which sends the bare word node), curl, python, wget, browser, none when the caller sent no User-Agent at all, and other for anything unrecognised — so a burst reads as GET [ua:undici] /auto-lander/land/req-9 and says what kind of thing to go looking for. The class is a closed set on purpose: the User-Agent is caller-controlled text and this card is Markdown, so it is classified, never echoed. Its copy gives the two usual causes — something on this computer using an old token (a script, a skill, another agent), or a page open in a browser — and says that if neither is recognised, something unexpected is running here. Its one button opens Settings → CLI Control, where the token and its Regenerate control live. The card is never held back by the Overseer gate, so it cannot be delayed by the app's own machinery. It is raised once per window and is not cleared automatically: dismiss it when you are satisfied, and it comes back only if a new burst starts.

On a brand-new install the card is held for the first day of use, like the other startup-shaped alerts — so a burst that both starts and stops inside that first day is dropped rather than shown. The producer re-checks on every window, so a burst still running when the first day ends is raised the moment the hold lifts.

  • omniscio-control.md — the skill bundle that uses /cron/jobs, /automation/*, /settings, /keybindings/*, /recipe/*, etc. from external AIs
  • create-cron-job-with-ai.md — user-facing walkthrough for the cron surface specifically
  • agent-trigger-recipes.md — POST /recipes/run + GET /recipes/triggerable in detail (agent-fired recipe runs)
  • bug-report-intake.md — PATCH /project/:id/bug-intake opt-in details and the email triage pipeline it controls
  • inbox-alerts.md — POST /alert in detail: how an agent drops a persistent row in the user's inbox
  • mobile-remote-access.md — a different server for remote (non-localhost) access from your phone
  • agent-input-modal.md — POST /input-request: how a session asks you for a value it must never see, and the modal that collects it
  • cli-account-login-capture.md — POST /accounts/login-capture: starting and polling an Anthropic account re-login over HTTP
  • Tasks control-server routes — /tasks-v2/* and /tasks-v2-lists/*: reading, creating, completing, bulk-changing and deleting tasks and projects, which key each needs, and the rate limits
  • app-control.md — the routes that fix Omniscio itself: reload a stale interface, restart the dev app, clear a software render fallback, catch up the source, list and restore backups
  • The CLI route gating catalog — the complete, generated route inventory (every route + its gating tier)

This page is split across three parts: part 2 covers the endpoints that change projects, sessions, project docs, away-mode rules and recipes, and part 3 covers the ones that read and drive what you are looking at — coaching data, bookmarks, inbox alerts, screen capture and on-screen highlighting.

Last verified 2026-10-10