CLI reference

The taiku CLI creates collaborative terminal sessions, manages authentication, exposes tunnels, and configures filesystem sandboxing. This page is a reference for the main commands and options. 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:

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

Options

taiku new

Start another taiku session from this machine, in addition to any you already have running.

taiku new [PATH] [OPTIONS]

PATH is the directory the new session starts in (defaults to the current directory).

taiku local

Start a local-only session on a loopback server, with no traffic leaving your machine. Useful for working offline or keeping a session fully private.

taiku local [PATH] [OPTIONS]

It takes the same PATH and sandbox options as taiku new, plus:

taiku local runs its own loopback server, so it needs the taiku-server binary available. It looks for one next to the taiku binary or at TAIKU_SERVER_BIN; if your install doesn't include it, point --server-bin at one.

taiku login

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 machines without a desktop (typical servers or build runners), 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

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. If you are already signed in, taiku login reports that account and exits without re-running the sign-in flow — so taiku sessions you start are already authenticated. To switch accounts, run taiku logout first, or taiku login --force to overwrite the existing credentials.

Inside a taiku session, taiku login and taiku logout are unavailable: the session already runs as your signed-in account, so manage credentials from your host machine instead.

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]

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

Install and manage the command-line tools taiku uses, routing each install to the right manager (mise, Homebrew, or your system package manager).

taiku install

Shortcut for taiku tools install.

taiku install [SPEC] [--global]

With no SPEC, it opens the interactive picker.

taiku init

Print shell setup code that adds taiku's terminal helpers to your shell. Run it once from your shell config so the helpers load in every new shell.

# zsh / bash — add to ~/.zshrc or ~/.bashrc
eval "$(taiku init zsh)"
eval "$(taiku init bash)"

# PowerShell — add to your $PROFILE
taiku init pwsh | Out-String | Invoke-Expression

The setup code installs a switch shell function (so taiku switch can change your current directory) along with lightweight wrappers that make taiku's path and tool integrations work smoothly inside your shell. On PowerShell, which reserves the switch keyword, it installs a Switch-Worktree function with an sw alias instead.

taiku switch

Jump between git worktrees and branches with a fuzzy picker. Run it inside any git repository.

taiku switch [NAME] [OPTIONS]

With no argument, taiku switch opens an interactive picker (using fzf or sk if installed, otherwise a numbered list) over your worktrees and branches. Pick one and your shell changes into it. With a NAME, it jumps directly:

• A name that matches an existing worktree changes into that worktree.
• A branch name without a worktree creates one under <repo>/.claude/worktrees/<name>/ and changes into it.
• Anything else prints an error.

To change your current directory, taiku switch relies on the switch shell function installed by taiku init. Once that is set up, you can also just type switch instead of taiku switch.

Picker controls

When the fzf/sk picker is open:

The list is ranked by how often and how recently you switch into each worktree, with the current worktree pinned at the top. Open pull requests for a branch are shown inline when the GitHub CLI (gh) is installed and authenticated.

Options

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. While it is running, the device accepts remote Start session commands from the dashboard. The desktop app achieves the same thing with a GUI; taiku bystand does the same without a local window.

taiku remote

Request remote desktop from inside a taiku session shell.

taiku remote [--session <name>] [--client <id>] [--password <password>]

This command is only available inside a shell that was created by taiku. It is for the case where you are already in a remote taiku terminal from another computer and want to open the host's desktop in the taiku desktop app.

When you run it, taiku sends a remote desktop request to the connected session client. If the host requires manual approval, the command prints that the request is pending and waits for approval, rejection, or timeout. If the host uses password-only access, pass --password.

taiku remote does not start a new terminal session. It uses the session you are already in, and it still follows the normal remote desktop requirements: both sides need the desktop app, the controller must be a different device from the host, and the host's guard mode may require approval.

taiku share

Publish the session you are already in to a shareable link, without interrupting your live terminal. Run it from inside a session you are hosting on this machine.

taiku share [OPTIONS]

taiku share snapshots the running session and moves its hosting onto a server so the link works from anywhere, then prints the URL to send to collaborators. Your terminal keeps running throughout; only where the session is hosted changes. Run outside a session, it prints an error telling you to start one first.

Everyone with the link can type by default. Start the session with --enable-readers if you also want a read-only link to hand out.

To hand the session to a managed machine instead of hosting it from your device, see taiku cloud.

taiku cloud

Provision or reuse a managed cloud workspace for a local project, start file sync, and open a taiku session on the cloud machine.

taiku cloud [PATH] [OPTIONS]

If PATH is omitted, taiku uses the current directory. The local path becomes a binding, so future runs from that same path reopen the same workspace when possible.

Run from inside a session, taiku cloud moves that session's project onto the managed machine and continues there, so it survives device sleep and stays reachable from anywhere.

Options

The default transfer also includes Taiku user preferences that should follow the workspace, such as global .taikuignore rules and tool configuration. Those preferences refresh on later taiku cloud runs. Machine identity, login credentials, active-session state, diagnostics, and sandbox path approvals stay local.

Subcommands

rebuild [--path <PATH>] [--yes] is available only on dev-mode servers. It replaces the backing machine with the current server cloud image for local cloud-image iteration.

.taikuignore

Taiku initializes a global ignore file at ~/.config/taiku/taikuignore the first time an ignore-aware command needs it. That file contains editable default rules for cloud sync and recursive scans, such as node_modules/, target/, .svelte-kit/, and logs.

Add .taikuignore at the workspace root for path-specific rules. Workspace rules are applied after the global file, so they can add ignores or opt back in with ! negation:

private/
archive/
generated-docs/
vendor-notes/
*.log
!private/keep.md
!node_modules/

Blank lines and # comments are ignored. Some feature policies are still separate: markdown scans keep crawl limits and root dot-directory handling, and gitfile worktrees keep cloud-local .git handling so remote git diff works. Ignore files apply to recursive work only; explicitly opening or reading a file is not blocked by the ignore file.

For the end-to-end workflow, see Cloud workspaces.

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 a connected client. A session window must be open (browser or desktop app) for commands to work. If nothing is connected, commands time out after a few 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.
• Use --client <id> (from list-users) when several participants are connected and you need to control a specific client.
• Commands that affect terminals follow the session's normal control model. You can manage your own terminals; other active participants' terminals require handoff or tunnel-admin access.

Layout commands

Workspace commands

Shell commands

Session info commands

Chat commands

Agent commands

Other commands

taiku logs

Manage local diagnostic logs the CLI stores for support and debugging.

taiku logs export

Export diagnostic logs as an encrypted bundle.

taiku logs export [--output <FILE>]

taiku logs clear

Clear all stored diagnostic logs.

taiku logs clear

taiku logs status

Show how many log entries are stored and approximate database size.

taiku logs status

taiku update

Check for a newer taiku release and optionally self-update.

taiku update

Environment variables