CLI Filesystem

CLI Filesystem routes talk to the connected CLI process, not the server's own disk.

Use them when a plugin needs to inspect files on the host machine that owns the session.

These routes all use session-scoped auth, but the access level differs by endpoint. listSessionDirectory and readSessionFile require writer access because they ask the connected CLI to touch the host filesystem directly. streamSessionFile is viewer-accessible and only stages the result for browser download.

If you call these endpoints directly over HTTP, the auth flow is challenge based:

1. GET /api/s/{session_id}/auth-challenge
2. sign the returned one-time challenge/nonce with the session secret
3. send X-Taiku-Session-Nonce and X-Taiku-Session-Key

If you call listSessionDirectory or readSessionFile on a write-protected session, also send X-Taiku-Session-Auth derived from the same challenge.

The plugin SDK and host bridge handle this automatically, so normal plugin authors usually do not need to implement it manually.

Common responses to expect:

• 401 for missing or invalid session challenge proof
• 403 for missing writer access on listSessionDirectory and readSessionFile
• 502 when no connected CLI can accept the request
• 504 when the CLI stayed connected but did not answer before the timeout
• 503 when the server cannot queue or stage the CLI-backed request right away