API Reference
Every HTTP endpoint the nikcli server exposes — 349 operations across 290 paths, generated from the server's own OpenAPI document.
Overview
The nikcli server is a single Effect HttpApi.
Every endpoint on this page is declared as a typed HttpApiEndpoint with
schema-checked request and response bodies, so the reference below, the generated SDK and the
running server all come from the same declaration — not from three copies of it that drift.
349 operations
Across 290 paths and 34 resource groups.
616 schemas
Request and response shapes, each reachable from the endpoints that use it.
OpenAPI 3.1.0
Emitted by nikcli generate from the composed API, then consumed by the SDK
generator and by this page.
One surface
The CLI, TUI, web app, desktop app and mobile app all talk to these same routes.
Read Server & API for how the server is built — the request pipeline, the auth layers, why some paths are raw handlers instead of typed endpoints. Read this section for the endpoints themselves.
Base URL
There is no hosted nikcli API: the server runs on your machine, or on a machine you control. Start one and the base URL is whatever it binds to.
# loopback, no password needed
nikcli serve --hostname 127.0.0.1 --port 4096
# reachable from the network — set a password first
NIKCLI_SERVER_PASSWORD=secret \
nikcli serve --hostname 0.0.0.0 --port 4096 Server.listen() falls back to an ephemeral port rather than failing when the
requested one is taken, so read the URL the command prints instead of assuming
4096.
Inside the terminal UI, sdk.url is the synthetic origin
http://nikcli.local and requests are dispatched in process. Use
sdk.client.* there; a hand-built fetch() against that host fails
DNS resolution silently.
Authentication
Four credential types resolve to one principal before any route runs. Which one you use depends on how the server was started; all of them are accepted on every non-public route.
| Scheme | Sent as | Used by |
|---|---|---|
bearerAuth | Authorization: Bearer <token> | Mobile pairing tokens and nku_ account tokens. |
auth_token | ?token=<token> | The same tokens, for clients that cannot set headers — EventSource, mostly. |
basicAuth | Username and password | NIKCLI_SERVER_PASSWORD, with the username defaulting to
nikcli.
|
| Tailscale identity | Tailscale-User-Login |
Trusted only on a loopback listener with
NIKCLI_SERVER_TAILSCALE_AUTH set.
|
curl -s http://127.0.0.1:4096/session \
-H "Authorization: Bearer $NIKCLI_TOKEN"
curl -s -u nikcli:$NIKCLI_SERVER_PASSWORD \
http://127.0.0.1:4096/session
The share routes — /s/:shareID, /share/:shareID and
/api/share/:shareID — answer before the auth check, and
/user/login, /user/register and /user/status are public
so an account can be created in the first place.
Choosing an instance
One server hosts many project instances. Every endpoint below accepts
directory and workspace query parameters that decide which project
handles the request; the same values can travel as
x-nikcli-directory and x-nikcli-workspace headers instead.
curl -s "http://127.0.0.1:4096/session?directory=/Users/me/project" \
-H "Authorization: Bearer $NIKCLI_TOKEN"
curl -s http://127.0.0.1:4096/session \
-H "x-nikcli-directory: /Users/me/project" \
-H "Authorization: Bearer $NIKCLI_TOKEN"
With neither set, a /session/:sessionID/… path recovers the directory from the
session itself, and everything else falls back to the server's working directory. The
/global, /user and /account roots never bind a
directory at all.
Instance selection is transport middleware rather than endpoint input, so the generator
adds directory and workspace to each operation when it writes the
OpenAPI document. They are optional everywhere.
Conventions
- JSON in, JSON out. Request and response bodies are
application/jsonunless an operation says otherwise. - Operation ids are dotted.
session.prompt,mobile.git.commit,experimental.workspace.warp. They map to the namespaced methods on the generated client —session.promptisclient.session.prompt— with a handful renamed where the dotted id would collide. - Errors are typed too. A failure schema such as
ConfigUpdateErrororProviderAuthErroris declared on the endpoint and encoded in the response, rather than collapsing into a bare 500. - Schema names ending in
_2are not duplicates. The OpenAPI emitter disambiguates same-named schemas declared by different groups; the shapes differ.
Streaming
The long-lived paths cannot round-trip through a response schema, so they are served as raw handlers ahead of the typed bridge — while still being declared in the API, which is why they appear in this reference at all.
| Path | Shape | Carries |
|---|---|---|
GET /event | SSE | Every event for the resolved instance. |
GET /global/event | SSE | Every event across every instance the server hosts. |
GET /sync/stream | SSE | Sync events; the one /sync/ path served instance-less. |
GET /session/:id/v2/events | SSE | Entry-level events for one session. |
POST /session/:id/message | Streamed body | Assistant output as it is produced. |
GET /pty/:ptyID/connect | WebSocket upgrade | Terminal input and output. |
curl -N "http://127.0.0.1:4096/event?token=$NIKCLI_TOKEN"Clients
@nikcli-ai/sdk/httpapi is generated from this same document, so every operation
id below is a typed method on the client. Reach for it before hand-writing requests.
import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"
const client = createNikcliClient({
baseUrl: "http://127.0.0.1:4096",
directory: "/Users/me/project",
})
// calls resolve with { data, error } unless throwOnError is set
const { data: sessions } = await client.session.list()
const { data: session } = await client.session.create({ title: "from the SDK" })For code running inside the nikcli process — plugins, tools, the TUI — the embedded SDK binds the same client to the in-process server instead of a socket.
Resources
349 operations, grouped the way the server declares them. The mobile surface is split across five pages because it is a third of the API on its own.
Core
Core
Instance lifecycle, resolved paths, version control status and apply, and the registries of commands, agents, skills, language servers and formatters.
Sessions
The session lifecycle: create, fork, revert, share and delete sessions, read messages and parts, inspect todos, diffs, context and goals, and drive background delegations and monitors.
Prompting
The two entry points that send a prompt to a session: the synchronous call that returns the assistant message, and the async call that returns immediately and streams over the event feed.
Events
Server-sent event feeds. One feed is scoped to the resolved instance, the other spans every instance the server hosts.
Files & Search
Reading and writing files in the resolved project, listing a directory, reading the working-tree status, and the three search endpoints behind text, filename and symbol lookup.
Projects
Project registry: the known projects, the one the current request resolved to, the directories inside it, and the project-copy lifecycle.
Tools & Worktrees
Experimental surface: the tool registry, the resource list, plain git worktrees, and the managed worktrees that carry parent/child links.
Workspaces
Workspace contexts — create, list, restore and remove them, read their status and event feed, and warp a session from one workspace into another.
Configuration
Read and patch the merged nikcli config, reload it from disk, resolve the provider table, and manage MCP server entries and config profiles.
Providers & Auth
Model providers and the credentials behind them: list providers and their auth state, set or remove an API key, and run the OAuth authorize/callback pair.
Connectors
Connector status, per-connector credentials, and cache invalidation.
MCP
Model Context Protocol servers: status, adding a server, connecting and disconnecting it, toggling it, and the OAuth flow for servers that need one.
Permissions
Pending permission requests and the reply that approves or denies one.
Questions
Questions an agent has asked the user, and the reply or rejection that unblocks it.
Loops
Loop definitions and their runs: list, upsert, generate from a description, toggle, run, pause, resume and abort, plus the run history.
Missions
Mission definitions, their feature list, and the execution lifecycle — start, pause, cancel — along with recent executions.
Brain
Background learning status and the manual trigger that forces a pass.
Profile
The declared user profile and the habits the Brain learned, plus the preview of what actually reaches the system prompt.
Analytics
Usage rollups: global and daily totals, per-session detail, the session list that backs the project breakdown, the leaderboard, and the combined data payload.
Sync
Event-sourced sync: push events, read the outbox and snapshots, stream changes, and manage the connection and drain.
Terminals
Pseudo-terminal sessions — create, resize, remove, and the upgrade endpoint that attaches to one.
TUI Control
The control channel a running terminal UI exposes: append or submit a prompt, open a dialog, execute a command, show a toast, and the request/response pair behind remote control.
Chatbots
Registered chat bots and the start/stop control for each one.
Discord
Discord integration status, first-time setup, and the start/stop control.
Voice
Audio transcription for voice input.
Skills & Logs
Creating and deleting skills, and the log sink clients write into.
Accounts & Users
The nikcli account behind a server (login and its completion step) and the local UserDB records the server owns.
Sharing
Public read endpoints for a shared session, in both the page and JSON forms.
Health & Doctor
Server health, global dispose, and the doctor report that checks the install end to end.
Mobile
Host & Bootstrap
The mobile host surface: pairing tokens, the bootstrap payload the app opens with, projects and commands, memory, worktrees, and the host capability probes behind browser, computer, island, devtools and LAN.
Sessions
Session endpoints shaped for the mobile app: list and create, send a message, stream updates, answer permissions and questions, read diffs and todos, and teleport a session between hosts.
Git & GitHub
The git toolbar behind the mobile review panel — status, diff, commits, branches, stage, commit, push and pull — plus the GitHub side: repos, branches, imports, Actions runs and the device OAuth flow.
Automation
Loops, missions and routines as the mobile app drives them, including the tokenised routine trigger.
Terminals
Pseudo-terminals for the mobile app, including the connect endpoint the terminal view attaches to.
The OpenAPI document
The document behind this reference is served from this site and checked into the repository at
packages/sdk/openapi.json. Point a generator at it to build a client in any
language.
curl -s https://nikcli-ai.dev/docs/api/openapi.json -o nikcli-openapi.json
# or regenerate it from a checkout
bun run script/generate.tsDownload the OpenAPI document · OpenAPI 3.1.0, 290 paths, 616 schemas.