Skip to content
nikcli
Docs
Documentation

Core

Instance lifecycle, resolved paths, version control status and apply, and the registries of commands, agents, skills, language servers and formatters.

Playground

Send these requests to your own running server. Values stay in this browser.

Not connected
How this works

Start a server with nikcli serve --hostname 127.0.0.1 --port 4096. Requests go straight from this page to that address — the browser allows it because loopback counts as a secure origin, and the server allows it because nikcli-ai.dev is in its CORS allowlist.

To try things without touching your real sessions or config, start the server with NIKCLI_TEST_HOME pointed at a throwaway directory — see the guided tour.

Operations

11 endpoints, generated from the server's own OpenAPI document. Every path also accepts the directory and workspace query parameters that select which instance handles the request.

post /instance/dispose instance.dispose
get /path path.get
get /vcs vcs.get
get /vcs/status vcs.status
get /vcs/diff/raw vcs.diff.raw
post /vcs/apply vcs.apply
get /command command.list
get /agent app.agents
get /skill app.skills
get /lsp lsp.status
get /formatter formatter.status
post /instance/dispose # instance.dispose
Parameters
Name In Type Required
directory query string optional
workspace query string optional
Responses
200 InstanceDisposeResult application/json 
boolean
Example response from schema 
false

Generated from the response schema — field values are placeholders, the shape is real.

SDK example
instance.dispose
ts 
import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.instance.dispose({
  ...
})
Try it

This changes or removes server state, against whatever base URL is set above.

get /path # path.get
Parameters
Name In Type Required
directory query string optional
workspace query string optional
Responses
200 Path application/json 
{
  home: string
  state: string
  config: string
  worktree: string
  directory: string
}
Example response captured 
{
  "home": "/Users/me/demo/.nikcli-home",
  "state": "/Users/me/demo/.nikcli-home/state",
  "config": "/Users/me/demo/.nikcli-home/config",
  "worktree": "/Users/me/demo",
  "directory": "/Users/me/demo"
}
SDK example
path.get
ts 
import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.path.get({
  ...
})
Try it
get /vcs # vcs.get
Parameters
Name In Type Required
directory query string optional
workspace query string optional
Responses
200 VcsInfo application/json 
{
  branch?: string | null
}
Example response captured 
{
  "branch": "main"
}
SDK example
vcs.get
ts 
import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.vcs.get({
  ...
})
Try it
get /vcs/status # vcs.status
Parameters
Name In Type Required
directory query string optional
workspace query string optional
Responses
200 Success application/json 
({
  file: string
  additions: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  deletions: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  status: "added" | "deleted" | "modified"
})[]
Example response from schema 
[
  {
    "file": "",
    "additions": 0,
    "deletions": 0,
    "status": "added"
  }
]

Generated from the response schema — field values are placeholders, the shape is real.

SDK example
vcs.status
ts 
import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.vcs.status({
  ...
})
Try it
get /vcs/diff/raw # vcs.diff.raw
Parameters
Name In Type Required
directory query string optional
workspace query string optional
Responses
200 Success text/x-diff; charset=utf-8 
string
Example response from schema 
""

Generated from the response schema — field values are placeholders, the shape is real.

SDK example
vcs.diff.raw
ts 
import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.vcs.diff.raw({
  ...
})
Try it
post /vcs/apply # vcs.apply
Parameters
Name In Type Required
directory query string optional
workspace query string optional
Request body · required · application/json 
{
  patch: string
}
Responses
200 VcsApplyResult application/json 
{
  applied: boolean
}
400 VcsApplyError application/json 
{
  name: "VcsApplyError"
  data: {
    message: string
    reason: string
  }
}
Example response from schema 
{
  "applied": false
}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example
vcs.apply
ts 
import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.vcs.apply({
  ...
})
Try it
get /command # command.list
Parameters
Name In Type Required
directory query string optional
workspace query string optional
Responses
200 Success application/json 
({
  name: string
  description?: string | null
  agent?: string | null
  model?: string | null
  mcp?: boolean | null
  skill?: boolean | null
  template: unknown
  subtask?: boolean | null
  hints: string[]
})[]
Example response from schema 
[
  {
    "name": "",
    "description": "",
    "agent": "",
    "model": "",
    "mcp": false,
    "skill": false,
    "template": null,
    "subtask": false,
    "hints": [
      ""
    ]
  }
]

Generated from the response schema — field values are placeholders, the shape is real.

SDK example
command.list
ts 
import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.command.list({
  ...
})
Try it
get /agent # app.agents
Parameters
Name In Type Required
directory query string optional
workspace query string optional
Responses
200 Success application/json 
({
  name: string
  description?: string | null
  mode: "subagent" | "primary" | "all"
  native?: boolean | null
  hidden?: boolean | null
  topP?: 
    | 
    | number
    | "Infinity" | "-Infinity" | "NaN"
    | null
  temperature?: 
    | 
    | number
    | "Infinity" | "-Infinity" | "NaN"
    | null
  color?: string | null
  permission: ({
    permission: string
    pattern: string
    action: "allow" | "deny" | "ask"
  })[]
  permissionMode?: "default" | "auto" | null
  model?: 
    | {
    modelID: string
    providerID: string
  }
    | null
  advisor?: 
    | {
    model: {
      modelID: string
      providerID: string
    }
    maxUses?: 
      | 
      | number
      | "Infinity" | "-Infinity" | "NaN"
      | null
  }
    | null
  variant?: string | null
  prompt?: string | null
  options: { [key: string]: unknown }
  steps?: 
    | 
    | number
    | "Infinity" | "-Infinity" | "NaN"
    | null
})[]
Example response from schema 
[
  {
    "name": "",
    "description": "",
    "mode": "subagent",
    "native": false,
    "hidden": false,
    "topP": 0,
    "temperature": 0,
    "color": "",
    "permission": [
      {
        "permission": null,
        "pattern": null,
        "action": null
      }
    ],
    "permissionMode": "default",
    "model": {
      "modelID": "",
      "providerID": ""
    },
    "advisor": {
      "model": {
        "modelID": null,
        "providerID": null
      },
      "maxUses": 0
    },
    "variant": "",
    "prompt": "",
    "options": {},
    "steps": 0
  }
]

Generated from the response schema — field values are placeholders, the shape is real.

SDK example
app.agents
ts 
import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.app.agents({
  ...
})
Try it
get /skill # app.skills
Parameters
Name In Type Required
directory query string optional
workspace query string optional
Responses
200 Success application/json 
({
  name: string
  description: string
  location: string
  category?: string | null
  tags?: string[] | null
  version?: string | null
})[]
Example response from schema 
[
  {
    "name": "",
    "description": "",
    "location": "",
    "category": "",
    "tags": [
      ""
    ],
    "version": ""
  }
]

Generated from the response schema — field values are placeholders, the shape is real.

SDK example
app.skills
ts 
import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.app.skills({
  ...
})
Try it
get /lsp # lsp.status
Parameters
Name In Type Required
directory query string optional
workspace query string optional
Responses
200 Success application/json 
({
  id: string
  name: string
  root: string
  status: "connected" | "error"
})[]
Example response captured 
[]
SDK example
lsp.status
ts 
import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.lsp.status({
  ...
})
Try it
get /formatter # formatter.status
Parameters
Name In Type Required
directory query string optional
workspace query string optional
Responses
200 Success application/json 
({
  name: string
  extensions: string[]
  enabled: boolean
})[]
Example response from schema 
[
  {
    "name": "",
    "extensions": [
      ""
    ],
    "enabled": false
  }
]

Generated from the response schema — field values are placeholders, the shape is real.

SDK example
formatter.status
ts 
import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.formatter.status({
  ...
})
Try it

Schemas

The 12 schemas reachable from these endpoints. Each is shown one level deep; nested types link to their own entry below. Names ending in _2, _3 and so on are the OpenAPI emitter disambiguating same-named schemas declared by different HttpApi groups — they are distinct shapes, not duplicates.

Agent
{
  name: string
  description?: string | null
  mode: "subagent" | "primary" | "all"
  native?: boolean | null
  hidden?: boolean | null
  topP?: 
    | 
    | number
    | "Infinity" | "-Infinity" | "NaN"
    | null
  temperature?: 
    | 
    | number
    | "Infinity" | "-Infinity" | "NaN"
    | null
  color?: string | null
  permission: ({
    permission: string
    pattern: string
    action: "allow" | "deny" | "ask"
  })[]
  permissionMode?: "default" | "auto" | null
  model?: 
    | {
    modelID: string
    providerID: string
  }
    | null
  advisor?: 
    | {
    model: {
      modelID: string
      providerID: string
    }
    maxUses?: 
      | 
      | number
      | "Infinity" | "-Infinity" | "NaN"
      | null
  }
    | null
  variant?: string | null
  prompt?: string | null
  options: { [key: string]: unknown }
  steps?: 
    | 
    | number
    | "Infinity" | "-Infinity" | "NaN"
    | null
}
Command
{
  name: string
  description?: string | null
  agent?: string | null
  model?: string | null
  mcp?: boolean | null
  skill?: boolean | null
  template: unknown
  subtask?: boolean | null
  hints: string[]
}
FormatterStatus
{
  name: string
  extensions: string[]
  enabled: boolean
}
InstanceDisposeResult
boolean
LSPStatus
{
  id: string
  name: string
  root: string
  status: "connected" | "error"
}
Path
{
  home: string
  state: string
  config: string
  worktree: string
  directory: string
}
Skill
{
  name: string
  description: string
  location: string
  category?: string | null
  tags?: string[] | null
  version?: string | null
}
VcsApplyError
{
  name: "VcsApplyError"
  data: {
    message: string
    reason: string
  }
}
VcsApplyInput
{
  patch: string
}
VcsApplyResult
{
  applied: boolean
}
VcsFileStatus
{
  file: string
  additions: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  deletions: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  status: "added" | "deleted" | "modified"
}
VcsInfo
{
  branch?: string | null
}