Skip to content
nikcli
Docs
Documentation

Terminals

Pseudo-terminal sessions — create, resize, remove, and the upgrade endpoint that attaches to one.

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

6 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.

get /pty pty.list
post /pty pty.create
get /pty/{ptyID} pty.get
put /pty/{ptyID} pty.update
delete /pty/{ptyID} pty.remove
get /pty/{ptyID}/connect pty.connect
get /pty # pty.list
Parameters
Name In Type Required
directory query string optional
workspace query string optional
Responses
200 PtyList application/json 
Pty_1[]
Example response captured 
[]
SDK example
pty.list
ts 
import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.pty.list({
  ...
})
Try it
post /pty # pty.create
Parameters
Name In Type Required
directory query string optional
workspace query string optional
Request body · required · application/json 
{
  command?: string | null
  args?: string[] | null
  cwd?: string | null
  title?: string | null
  env?: 
    | {
    [key: string]: string
  }
    | null
}
Responses
200 Pty application/json 
{
  id: string
  title: string
  command: string
  args: string[]
  cwd: string
  status: "running" | "exited"
  pid: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
}
400 PtyCreateErrorBody application/json 
{
  name: "PtyCreateError"
  data: { [key: string]: unknown }
}
Example response from schema 
{
  "id": "",
  "title": "",
  "command": "",
  "args": [
    ""
  ],
  "cwd": "",
  "status": "running",
  "pid": 0
}

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

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

const client = createNikcliClient()
await client.pty.create({
  ...
})
Try it
get /pty/{ptyID} # pty.get
Parameters
Name In Type Required
ptyID path string required
directory query string optional
workspace query string optional
Responses
200 Pty application/json 
{
  id: string
  title: string
  command: string
  args: string[]
  cwd: string
  status: "running" | "exited"
  pid: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
}
404 PtyNotFoundError application/json 
{
  name: "NotFoundError"
  data: { [key: string]: unknown }
}
Example response from schema 
{
  "id": "",
  "title": "",
  "command": "",
  "args": [
    ""
  ],
  "cwd": "",
  "status": "running",
  "pid": 0
}

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

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

const client = createNikcliClient()
await client.pty.get({
  ...
})
Try it
put /pty/{ptyID} # pty.update
Parameters
Name In Type Required
ptyID path string required
directory query string optional
workspace query string optional
Request body · required · application/json 
{
  title?: string | null
  size?: 
    | {
    rows: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    cols: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
  }
    | null
}
Responses
200 Pty application/json 
{
  id: string
  title: string
  command: string
  args: string[]
  cwd: string
  status: "running" | "exited"
  pid: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
}
404 PtyNotFoundError application/json 
{
  name: "NotFoundError"
  data: { [key: string]: unknown }
}
Example response from schema 
{
  "id": "",
  "title": "",
  "command": "",
  "args": [
    ""
  ],
  "cwd": "",
  "status": "running",
  "pid": 0
}

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

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

const client = createNikcliClient()
await client.pty.update({
  ...
})
Try it
delete /pty/{ptyID} # pty.remove
Parameters
Name In Type Required
ptyID path string required
directory query string optional
workspace query string optional
Responses
200 Success application/json 
boolean
Example response from schema 
false

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

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

const client = createNikcliClient()
await client.pty.remove({
  ...
})
Try it

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

get /pty/{ptyID}/connect # pty.connect
Parameters
Name In Type Required
ptyID path string required
directory query string optional
workspace query string optional
Responses
200 WebSocket upgrade application/json 
unknown
Example response from schema 
null

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

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

const client = createNikcliClient()
await client.pty.connect({
  ...
})
Try it

Schemas

The 6 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.

Pty_1
{
  id: string
  title: string
  command: string
  args: string[]
  cwd: string
  status: "running" | "exited"
  pid: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
}
PtyCreateErrorBody
{
  name: "PtyCreateError"
  data: { [key: string]: unknown }
}
PtyCreateInput
{
  command?: string | null
  args?: string[] | null
  cwd?: string | null
  title?: string | null
  env?: 
    | {
    [key: string]: string
  }
    | null
}
PtyList
Pty_1[]
PtyNotFoundError
{
  name: "NotFoundError"
  data: { [key: string]: unknown }
}
PtyUpdateInput
{
  title?: string | null
  size?: 
    | {
    rows: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    cols: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
  }
    | null
}