Skip to content
nikcli
Docs
Documentation

Projects

Project registry: the known projects, the one the current request resolved to, the directories inside it, and the project-copy lifecycle.

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

7 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 /project project.list
get /project/current project.current
patch /project/{projectID} project.update
get /project/{projectID}/directory project.directory.list
post /project/{projectID}/copy project.copy.create
delete /project/{projectID}/copy project.copy.remove
post /project/{projectID}/copy/refresh project.copy.refresh
get /project # project.list
Parameters
Name In Type Required
directory query string optional
workspace query string optional
Responses
200 Success application/json 
({
  id: string
  worktree: string
  canonical: string
  vcs?: "git" | null
  name?: string | null
  icon?: 
    | {
    url?: string | null
    override?: string | null
    color?: string | null
  }
    | null
  commands?: 
    | {
    start?: string | null
  }
    | null
  time: {
    created: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    updated: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    initialized?: 
      | 
      | number
      | "Infinity" | "-Infinity" | "NaN"
      | null
  }
  sandboxes: string[]
})[]
Example response from schema 
[
  {
    "id": "",
    "worktree": "",
    "canonical": "",
    "vcs": "git",
    "name": "",
    "icon": {
      "url": "",
      "override": "",
      "color": ""
    },
    "commands": {
      "start": ""
    },
    "time": {
      "created": 0,
      "updated": 0,
      "initialized": 0
    },
    "sandboxes": [
      ""
    ]
  }
]

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

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

const client = createNikcliClient()
await client.project.list({
  ...
})
Try it
get /project/current # project.current
Parameters
Name In Type Required
directory query string optional
workspace query string optional
Responses
200 Project application/json 
{
  id: string
  worktree: string
  canonical: string
  vcs?: "git" | null
  name?: string | null
  icon?: 
    | {
    url?: string | null
    override?: string | null
    color?: string | null
  }
    | null
  commands?: 
    | {
    start?: string | null
  }
    | null
  time: {
    created: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    updated: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    initialized?: 
      | 
      | number
      | "Infinity" | "-Infinity" | "NaN"
      | null
  }
  sandboxes: string[]
}
Example response captured 
{
  "id": "c6d9c4f98cc34c8bfb0a40b3a60eca6f624750e6",
  "worktree": "/Users/me/demo",
  "canonical": "/Users/me/demo",
  "vcs": "git",
  "time": {
    "created": 1789656731762,
    "updated": 1789656731762
  },
  "sandboxes": []
}
SDK example
project.current
ts 
import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.project.current({
  ...
})
Try it
patch /project/{projectID} # project.update
Parameters
Name In Type Required
projectID path string required
directory query string optional
workspace query string optional
Request body · required · application/json 
{
  name?: string | null
  icon?: 
    | {
    url?: string | null
    override?: string | null
    color?: string | null
  }
    | null
}
Responses
200 Project application/json 
{
  id: string
  worktree: string
  canonical: string
  vcs?: "git" | null
  name?: string | null
  icon?: 
    | {
    url?: string | null
    override?: string | null
    color?: string | null
  }
    | null
  commands?: 
    | {
    start?: string | null
  }
    | null
  time: {
    created: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    updated: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    initialized?: 
      | 
      | number
      | "Infinity" | "-Infinity" | "NaN"
      | null
  }
  sandboxes: string[]
}
Example response from schema 
{
  "id": "",
  "worktree": "",
  "canonical": "",
  "vcs": "git",
  "name": "",
  "icon": {
    "url": "",
    "override": "",
    "color": ""
  },
  "commands": {
    "start": ""
  },
  "time": {
    "created": 0,
    "updated": 0,
    "initialized": 0
  },
  "sandboxes": [
    ""
  ]
}

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

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

const client = createNikcliClient()
await client.project.update({
  ...
})
Try it
get /project/{projectID}/directory # project.directory.list
Parameters
Name In Type Required
projectID path string required
directory query string optional
workspace query string optional
Responses
200 Success application/json 
({
  directory: string
  strategy?: string | null
})[]
Example response from schema 
[
  {
    "directory": "",
    "strategy": ""
  }
]

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

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

const client = createNikcliClient()
await client.project.directory.list({
  ...
})
Try it
post /project/{projectID}/copy # project.copy.create
Parameters
Name In Type Required
projectID path string required
directory query string optional
workspace query string optional
Request body · required · application/json 
{
  strategy: "git_worktree"
  directory: string
  name?: string | null
}
Responses
200 ProjectCopy application/json 
{
  directory: string
}
Example response from schema 
{
  "directory": ""
}

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

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

const client = createNikcliClient()
await client.project.copy.create({
  ...
})
Try it
delete /project/{projectID}/copy # project.copy.remove
Parameters
Name In Type Required
projectID path string required
directory query string optional
workspace query string optional
Request body · required · application/json 
{
  directory: string
  force: boolean
}
Responses
204 <No Content>
SDK example
project.copy.remove
ts 
import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

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

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

post /project/{projectID}/copy/refresh # project.copy.refresh
Parameters
Name In Type Required
projectID path string required
directory query string optional
workspace query string optional
Responses
200 ProjectCopyRefresh application/json 
{
  updated: string[]
  removed: string[]
}
Example response from schema 
{
  "updated": [
    ""
  ],
  "removed": [
    ""
  ]
}

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

SDK example
project.copy.refresh
ts 
import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.project.copy.refresh({
  ...
})
Try it

Schemas

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

Project_2
{
  id: string
  worktree: string
  canonical: string
  vcs?: "git" | null
  name?: string | null
  icon?: 
    | {
    url?: string | null
    override?: string | null
    color?: string | null
  }
    | null
  commands?: 
    | {
    start?: string | null
  }
    | null
  time: {
    created: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    updated: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    initialized?: 
      | 
      | number
      | "Infinity" | "-Infinity" | "NaN"
      | null
  }
  sandboxes: string[]
}
ProjectCopy
{
  directory: string
}
ProjectCopyCreateInput
{
  strategy: "git_worktree"
  directory: string
  name?: string | null
}
ProjectCopyRefresh
{
  updated: string[]
  removed: string[]
}
ProjectCopyRemoveInput
{
  directory: string
  force: boolean
}
ProjectDirectory
{
  directory: string
  strategy?: string | null
}
ProjectUpdateInput
{
  name?: string | null
  icon?: 
    | {
    url?: string | null
    override?: string | null
    color?: string | null
  }
    | null
}