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 use session-scoped authentication.

listSessionDirectory and readSessionFile accept viewer access. A viewer-only caller also needs the host to grant file access; otherwise the request returns 403.

Writers and admins do not need that additional grant. Non-admin callers can only list and read within the host's sandbox root. Without a sandbox root, non-admin access is denied. Writing files, renaming them, and extracting archives still require write access.

streamSessionFile uses the same access rules and 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

Send X-Taiku-Session-Auth, derived from the same challenge using the write or admin secret, when proving elevated access. A viewer with the host's file-access grant can list and read without it, including in a write-protected session. Session sign-in and invitation requirements still apply.

The plugin SDK and host bridge handle this automatically, so you usually do not need to wire the challenge flow yourself.

Common responses to expect:

• 400 for malformed challenge headers or a missing required file path
• 401 for missing or invalid session challenge proof, or when sign-in is required
• 403 when a viewer-only caller has no file access from the host, session access is refused, or a list/read request is denied by filesystem or sandbox rules; archive extraction also returns 403 for a viewer-only caller
• 502 when no connected CLI can accept the request or its conditional-read response is invalid
• 504 when the CLI does not answer before the timeout or its reply channel closes
• 503 when the server cannot queue or stage the CLI-backed request right away