Documentation

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.

Playground

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

Not connected

Base URL Directory optional Bearer token optional

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	/find	find.text
get	/find/file	find.files
get	/find/symbol	find.symbols
get	/file	file.list
get	/file/content	file.read
put	/file/content	file.write
get	/file/status	file.status

get /find # find.text

Parameters

Name	In	Type	Required
pattern	query	string	required
directory	query	string	optional
workspace	query	string	optional

Responses

200 Success application/json

({
  path: {
    text: string
  }
  lines: {
    text: string
  }
  line_number: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  absolute_offset: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  submatches: ({
    match: {
      text: string
    }
    start: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    end: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
  })[]
})[]

Example response captured

[
  {
    "path": {
      "text": "greet.ts"
    },
    "lines": {
      "text": "  // TODO: localise this"
    },
    "line_number": 2,
    "absolute_offset": 38,
    "submatches": [
      {
        "match": {
          "text": "TODO"
        },
        "start": 5,
        "end": 9
      }
    ]
  }
]

SDK example

find.text

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.find.text({
  ...
})

Try it

pattern query · required directory query workspace query

get /find/file # find.files

Parameters

Name	In	Type	Required
query	query	string	required
dirs	query	"true" \| "false" \| null	optional
type	query	"file" \| "directory" \| null	optional
limit	query	string \| null	optional
directory	query	string	optional
workspace	query	string	optional

Responses

200 Success application/json

string[]

Example response captured

[
  "greet.ts",
  "README.md"
]

SDK example

find.files

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.find.files({
  ...
})

Try it

query query · required dirs query type query limit query directory query workspace query

get /find/symbol # find.symbols

Parameters

Name	In	Type	Required
query	query	string	required
directory	query	string	optional
workspace	query	string	optional

Responses

200 Success application/json

({
  name: string
  kind: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  location: {
    uri: string
    range: {
      start: {
        line: 
          | number
          | "Infinity" | "-Infinity" | "NaN"
        character: 
          | number
          | "Infinity" | "-Infinity" | "NaN"
      }
      end: {
        line: 
          | number
          | "Infinity" | "-Infinity" | "NaN"
        character: 
          | number
          | "Infinity" | "-Infinity" | "NaN"
      }
    }
  }
})[]

Example response from schema

[
  {
    "name": "",
    "kind": 0,
    "location": {
      "uri": "",
      "range": {
        "start": null,
        "end": null
      }
    }
  }
]

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

SDK example

find.symbols

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.find.symbols({
  ...
})

Try it

query query · required directory query workspace query

get /file # file.list

Parameters

Name	In	Type	Required
path	query	string	required
directory	query	string	optional
workspace	query	string	optional

Responses

200 Success application/json

({
  name: string
  path: string
  absolute: string
  type: "file" | "directory"
  ignored: boolean
})[]

Example response captured

[
  {
    "name": "greet.ts",
    "path": "greet.ts",
    "absolute": "/Users/me/demo/greet.ts",
    "type": "file",
    "ignored": false
  },
  {
    "name": "README.md",
    "path": "README.md",
    "absolute": "/Users/me/demo/README.md",
    "type": "file",
    "ignored": false
  }
]

SDK example

file.list

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.file.list({
  ...
})

Try it

path query · required directory query workspace query

get /file/content # file.read

Parameters

Name	In	Type	Required
path	query	string	required
directory	query	string	optional
workspace	query	string	optional

Responses

200 FileContent application/json

{
  type: "text"
  content: string
  diff?: string | null
  patch?: 
    | {
    oldFileName: string
    newFileName: string
    oldHeader?: string | null
    newHeader?: string | null
    hunks: ({
      oldStart: 
        | number
        | "Infinity" | "-Infinity" | "NaN"
      oldLines: 
        | number
        | "Infinity" | "-Infinity" | "NaN"
      newStart: 
        | number
        | "Infinity" | "-Infinity" | "NaN"
      newLines: 
        | number
        | "Infinity" | "-Infinity" | "NaN"
      lines: string[]
    })[]
    index?: string | null
  }
    | null
  encoding?: "base64" | null
  mimeType?: string | null
}

Example response captured

{
  "type": "text",
  "content": "export function greet(name: string) {\n  // TODO: localise this\n  return `Hello, ${name}!`\n}"
}

SDK example

file.read

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.file.read({
  ...
})

Try it

path query · required directory query workspace query

put /file/content # file.write

Parameters

Name	In	Type	Required
directory	query	string	optional
workspace	query	string	optional

Request body · required · application/json

{
  path: string
  content: string
}

Responses

200 FileWriteResult application/json

{
  success: boolean
}

Example response from schema

{
  "success": false
}

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

SDK example

file.write

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.file.write({
  ...
})

Try it

directory query workspace query

Request body application/json

get /file/status # file.status

Parameters

Name	In	Type	Required
directory	query	string	optional
workspace	query	string	optional

Responses

200 Success application/json

({
  path: string
  added: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  removed: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  status: "added" | "deleted" | "modified"
})[]

Example response captured

[]

SDK example

file.status

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.file.status({
  ...
})

Try it

directory query workspace query

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.

File

{
  path: string
  added: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  removed: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  status: "added" | "deleted" | "modified"
}

FileContent

{
  type: "text"
  content: string
  diff?: string | null
  patch?: 
    | {
    oldFileName: string
    newFileName: string
    oldHeader?: string | null
    newHeader?: string | null
    hunks: ({
      oldStart: 
        | number
        | "Infinity" | "-Infinity" | "NaN"
      oldLines: 
        | number
        | "Infinity" | "-Infinity" | "NaN"
      newStart: 
        | number
        | "Infinity" | "-Infinity" | "NaN"
      newLines: 
        | number
        | "Infinity" | "-Infinity" | "NaN"
      lines: string[]
    })[]
    index?: string | null
  }
    | null
  encoding?: "base64" | null
  mimeType?: string | null
}

FileNode

{
  name: string
  path: string
  absolute: string
  type: "file" | "directory"
  ignored: boolean
}

FileWritePayload

{
  path: string
  content: string
}

FileWriteResult

{
  success: boolean
}

SearchMatch

{
  path: {
    text: string
  }
  lines: {
    text: string
  }
  line_number: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  absolute_offset: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  submatches: ({
    match: {
      text: string
    }
    start: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    end: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
  })[]
}

Symbol

{
  name: string
  kind: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  location: {
    uri: string
    range: {
      start: {
        line: 
          | number
          | "Infinity" | "-Infinity" | "NaN"
        character: 
          | number
          | "Infinity" | "-Infinity" | "NaN"
      }
      end: {
        line: 
          | number
          | "Infinity" | "-Infinity" | "NaN"
        character: 
          | number
          | "Infinity" | "-Infinity" | "NaN"
      }
    }
  }
}