CLI reference

The taiku CLI creates collaborative terminal sessions, manages authentication, exposes tunnels, and configures filesystem sandboxing. This page is a pure reference for every command and option. For real-world usage patterns, see Scenarios and Common Workflows.

`taiku`

Start a new collaborative terminal session. This is the primary command. Running taiku with no subcommand creates a session, connects to the server, and opens the session URL in your browser or desktop app.

taiku [OPTIONS]

When you run taiku, it:

Resolves your authentication credentials.
Connects to the taiku server via gRPC.
Spawns a local shell process (your default shell, or the one specified with --shell).
Opens the session URL in the taiku desktop app (or browser, depending on configuration).
Copies the session URL to your clipboard.
Streams terminal I/O between your local shell and the server until you exit.

Options

Option	Description
`--shell <SHELL>`	Shell command to run instead of your default shell. It can be any executable, including `/bin/bash`, `/bin/zsh`, `fish`, or `python3`. If omitted, taiku uses the `SHELL` environment variable or falls back to `/bin/sh`.
`--name <NAME>`	Display name for the session. Shown in the title bar and session list. Defaults to `user@hostname`.
`--quiet` / `-q`	Quiet mode. Suppresses the greeting banner and only prints the session URL to stdout. Useful for scripting.
`--verbose` / `-v`	Enable verbose logging output. Prints debug-level logs to stderr.
`--no-app`	Skip opening the desktop app. The session URL opens in your default browser instead. Use this on headless servers or when you prefer the browser experience.
`--app`	Force opening the desktop app, even if it would not be the default.
`--no-browser`	Do not open a browser window on startup. The session URL is still printed and copied to clipboard.
`--no-copy`	Do not copy the session URL to the clipboard on startup.
`--enable-readers`	Generate separate read-only and write/admin URLs. All of them share the same session fragment for terminal decryption; the write/admin URLs add an extra password after the fragment to unlock typing or tunnel management.
`--no-viewer-auth`	Disable the server-side viewer OAuth gate for this session. It does not remove the URL fragment requirement for terminal decryption. This flag is only available on Pro plans.
`--token <TOKEN>`	Use a specific API token for authentication instead of the stored credentials or environment variable.
`--tunnel <PORTS>`	Expose local ports as HTTP tunnels, accessible to session participants. Accepts a comma-separated list of port numbers.
`--open-tunnel`	Auto-approve all tunnel port requests from session users. Without this flag, each tunnel port request requires manual approval in the terminal.
`--sandbox <PATH>`	Restrict the shell to a workspace directory using OS-level enforcement. On Linux, this uses Landlock; on macOS, it uses Seatbelt (SBPL). The shell can only access files within the specified path.
`--sandbox-ro`	Make the sandbox workspace read-only. Implies `--sandbox`. The shell can read files in the workspace but cannot create, modify, or delete them.
`--sandbox-mode <MODE>`	Sandbox behavior profile. Options are `isolated` (default) and `trusted`. Trusted mode relaxes certain restrictions for scenarios where the sandboxed process needs broader system access.
`--sandbox-allow <PATH>`	Add an additional path to the sandbox read-only allow list. Can be repeated to allow multiple paths.
`--sandbox-bridge-claude-auth`	Allow sandboxed shells to reuse host Claude authentication and configuration state.
`--sandbox-bridge-codex-auth`	Allow sandboxed shells to reuse host Codex authentication and configuration state.
`--sandbox-bridge-opencode-auth`	Allow sandboxed shells to reuse host OpenCode authentication and configuration state.
`--server <URL>`	Address of the remote taiku server. Defaults to `https://taiku.live`. Can also be set via `TAIKU_SERVER`.

Authenticate with your taiku account. This stores credentials locally so subsequent taiku commands are authenticated.

taiku login [OPTIONS]

On machines with a browser, taiku login opens the OAuth login page. You authenticate in the browser, and the CLI receives the credentials automatically via the device authorization flow.

On headless machines (servers, CI), taiku login prints a URL and a device code. You visit the URL on any device, enter the code, and authenticate. The CLI polls for completion and stores the credentials when the flow succeeds.

Options

Option	Description
`--token <TOKEN>`	Provide an API token directly instead of using the interactive device flow. Useful for CI/CD pipelines where browser-based auth is not possible.

Where credentials are stored

After successful login, credentials are written to ~/.config/taiku/credentials:

{
  "server": "https://taiku.live",
  "api_key": "tk_...",
  "email": "you@example.com"
}

This file is readable only by your user. The CLI reads it automatically on every invocation. To switch accounts, run taiku login again. It overwrites the existing credentials.

`taiku logout`

Remove stored credentials and log out.

taiku logout

This deletes the ~/.config/taiku/credentials file. After logging out, taiku commands that require authentication will prompt you to log in again.

`taiku sandbox`

Manage the persistent sandbox allow-list. This lets you pre-configure paths that sandboxed sessions can access without specifying --sandbox-allow every time.

`taiku sandbox allow`

Add a path to the persistent allow-list.

taiku sandbox allow <PATH> [--rw]

Option	Description
`--rw`	Grant read-write access instead of the default read-only.

`taiku sandbox deny`

Remove a path from the allow-list.

taiku sandbox deny <PATH>

`taiku sandbox list`

Show all currently allowed paths.

taiku sandbox list

`taiku tools`

Manage local taiku terminal tools.

`taiku tools bootstrap-defaults`

Install the default taiku tool set into taiku's managed bin directory. This sets up common utilities that plugins and sandboxed sessions may depend on.

taiku tools bootstrap-defaults

`taiku bystand`

Keep the device online and listen for remote session commands. This is a long-running mode where the CLI stays connected to the server without starting an interactive session, waiting for remote instructions from the dashboard.

taiku bystand

Use this on machines that should be remotely accessible but do not need an active session running at all times. The desktop app achieves the same thing with a GUI; taiku bystand is the headless equivalent.

`taiku func`

Remote session management. Control a running taiku session from the CLI or from inside a taiku terminal. Commands are relayed through the server to the browser client, which executes them and returns results as JSON.

taiku func [--session <name>] <command> [args]

How it works:

When you start a session with taiku, the session name is written to ~/.config/taiku/active-session. taiku func reads this file to know which session to target.
Commands are sent via HTTP to the server, which relays them over WebSocket to the browser. A browser tab must be open on the session for commands to work. If no browser is connected, commands will time out after 5 seconds.
taiku func works inside taiku terminals. It's one of the few commands not blocked by the nested-session guard.
Use --session <name> to target a specific session instead of the active one.

Layout commands

Command	Description
`split-h [--tile <key>]`	Split tile horizontally
`split-v [--tile <key>]`	Split tile vertically
`close-tile [--tile <key>]`	Close a tile
`reset-layout`	Reset to balanced grid
`toggle-direction [--tile <key>]`	Toggle split H/V
`set-ratio <ratio> [--tile <key>]`	Set split ratio (0.1-0.9)
`swap-tiles <key-a> <key-b>`	Swap two tiles
`maximize [--tile <key>]`	Maximize a tile
`focus-tile <key>`	Focus a tile
`focus-direction <left\|right\|up\|down>`	Focus neighbor tile
`rename-tile <key> <name>`	Rename a tile
`get-layout`	Print layout tree as JSON
`list-tiles`	List all tiles
`get-tab-groups`	List tab groups

Workspace commands

Command	Description
`list-workspaces`	List workspace pages
`create-workspace`	Create new workspace
`switch-workspace <index>`	Switch workspace page
`setup --grid <RxC> [--commands <c1,c2,...>]`	Create grid layout

Shell commands

Command	Description
`list-shells`	List shells with sizes
`create-shell [--cwd <path>]`	Create a new shell
`close-shell <id>`	Close a shell
`write-to-shell <id> <data>`	Write to a shell
`run <command> [--tile <key>]`	Run command in a tile
`get-shell-output <id> [--chunks N]`	Get terminal output
`get-terminal-names`	Get shell names
`rename-session <name>`	Rename the session

Session info commands

Command	Description
`get-session`	Session metadata
`list-users`	List connected users
`get-role`	Get your role
`get-ownership`	Shell ownership info
`adopt-shell <id>`	Adopt a shell

Chat commands

Command	Description
`get-chat`	Get chat history
`send-chat <message>`	Send chat message
`broadcast-event <type> [--data <json>]`	Broadcast plugin event

Agent commands

Command	Description
`list-agents`	List active AI agents
`get-agent-cost`	Token usage summary
`list-agent-sessions`	List agent sessions
`get-agent-events <session-id> [--types] [--limit]`	Get session events

Other commands

Command	Description
`list-tunnels`	List tunnel ports
`toast <message> [--kind info\|success\|error]`	Show toast notification
`notify <title> [--body <text>]`	Send notification
`show-layout`	ASCII layout view
`show-tree`	Tree layout view

Environment variables

Variable	Description	Default
`SHELL`	Default shell for new sessions. Taiku reads this when `--shell` is not provided.	System default
`TAIKU_TOKEN`	API token for authentication. Checked after `--token` flag but before the credentials file.	Not set
`TAIKU_SERVER`	Override the server URL. Equivalent to the `--server` flag.	`https://taiku.live`

CLI reference

On this page