Remote Commands

Remote Commands let you control a live taiku session from outside the browser.

Use them when you want to:

• drive a session from taiku ctl, curl, or automation scripts
• inspect layouts, shells, chat, or agent state
• build AI agent integrations that interact with terminal sessions

Quick startCopy Anchor Link

taiku ctl is also available as taiku func; the two are the same command.

# Run from inside a taiku shell (auto-detects session + client)
taiku ctl list-tiles
taiku ctl run "ls -la"
taiku ctl get-layout

# Run from outside (specify session explicitly)
taiku ctl --session <name> list-users
taiku ctl --session <name> --client <id> split-h

Client targetingCopy Anchor Link

Commands run in a connected client: a browser tab, the desktop app, or the terminal client. Many operate on that client's own state (layout, workspace, focus), so taiku picks one:

Commands that read session-wide state (shells, users, agents) can be answered by any client and skip this choice. Use taiku ctl list-users to see connected clients and their IDs.

Without --session, the CLI uses the session in TAIKU_SESSION (set inside taiku shells), then the session you last started on this machine.

Where a tile is optional, leaving it out means the answering client's focused tile, which can change if someone clicks elsewhere. Commands with an optional tile also take --current, which targets the shell the command is running in (macOS and Linux).

AuthenticationCopy Anchor Link

All remote commands require authentication as the session owner. The CLI uses your login credentials from taiku login. To use an API key instead, pass it before the subcommand (taiku --token <api_key> ctl list-users) or set TAIKU_TOKEN.

REST APICopy Anchor Link

You can also send remote commands directly via HTTP:

curl -X POST https://taiku.live/api/v1/sessions/{session_id}/remote/command \
  -H "X-Taiku-Token: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method": "getLayout", "params": {}}'

Request bodyCopy Anchor Link

ResponseCopy Anchor Link

{ "result": { ... } }

On error, returns a text body with the status: 400 when the client refused the command (the body is its error) or the request is malformed, 403 when you are not the session owner, 404 for an unknown session or client, 503 when no client is connected, 504 when no client answered within 5 seconds, and 410 when the session closed.

method can be any method from the Plugin API, such as splitTile or sendChat, and runs without plugin permission checks. The CLI commands below cover the common ones.

GET shortcutsCopy Anchor Link

Common read commands have GET shortcuts:

Command referenceCopy Anchor Link

LayoutCopy Anchor Link

Commands that manipulate or read the target client's tiled terminal layout.

split-h / split-vCopy Anchor Link

Split the tile of the shell you run it in, horizontally or vertically, creating a new shell beside it. Like the other commands that open or close a shell, it needs the Admin link (see Shells).

taiku ctl split-h              # Split this shell's tile
taiku ctl split-v              # The same, vertically

close-tileCopy Anchor Link

Close a tile from the layout.

taiku ctl close-tile --tile 3

reset-layoutCopy Anchor Link

Reset the layout to a balanced grid of all current tiles.

taiku ctl reset-layout

toggle-directionCopy Anchor Link

Toggle a split's direction between horizontal and vertical.

taiku ctl toggle-direction --tile 3

set-ratioCopy Anchor Link

Set a split ratio (controls how space is divided between two tiles).

taiku ctl set-ratio 0.7 --tile 3

swap-tilesCopy Anchor Link

Swap the positions of two tiles.

taiku ctl swap-tiles 1 2

maximizeCopy Anchor Link

Maximize a tile to fill the entire workspace.

taiku ctl maximize              # Maximize focused tile
taiku ctl maximize --tile 3     # Maximize specific tile

focus-tileCopy Anchor Link

Focus a specific tile.

taiku ctl focus-tile 3

focus-directionCopy Anchor Link

Focus the neighboring tile in a direction.

taiku ctl focus-direction left

rename-tileCopy Anchor Link

Rename a tile (sets a custom label in the titlebar).

taiku ctl rename-tile "logs" 3

get-layoutCopy Anchor Link

Get the current layout with tile positions and sizes.

taiku ctl get-layout

Returns:

{
  "tiles": [
    { "key": 1, "type": "shell", "id": 1, "x": 0, "y": 44, "w": 756, "h": 813 },
    {
      "key": 2,
      "type": "shell",
      "id": 2,
      "x": 756,
      "y": 44,
      "w": 756,
      "h": 813
    }
  ]
}

list-tilesCopy Anchor Link

List tiles on the current workspace (lighter than get-layout).

taiku ctl list-tiles

list-tab-groupsCopy Anchor Link

List tab groups (tiles with multiple tabbed items).

taiku ctl list-tab-groups

TabsCopy Anchor Link

Commands for switching tabs inside a tabbed tile. Only the terminal client (taiku tui) answers these; the browser and the desktop app refuse them.

select-tabCopy Anchor Link

Switch to a tab by zero-based index.

taiku ctl select-tab 1
taiku ctl select-tab 2 --tile 3

next-tabCopy Anchor Link

Switch to the next tab in a tile.

taiku ctl next-tab
taiku ctl next-tab --tile 3

prev-tabCopy Anchor Link

Switch to the previous tab in a tile.

taiku ctl prev-tab
taiku ctl prev-tab --tile 3

show-layoutCopy Anchor Link

Pretty-print the layout JSON from get-layout.

taiku ctl show-layout

WorkspacesCopy Anchor Link

Commands for managing workspaces (virtual desktops).

list-workspacesCopy Anchor Link

List workspaces.

taiku ctl list-workspaces

create-workspaceCopy Anchor Link

Create a new workspace.

taiku ctl create-workspace

switch-workspaceCopy Anchor Link

Switch to a workspace by index.

taiku ctl switch-workspace 0

list-user-tilesCopy Anchor Link

List tiles for a specific connected client. Automatically targets the requested client.

taiku ctl list-user-tiles 2

setupCopy Anchor Link

Set up a grid layout with specific tile types.

taiku ctl setup --grid 2x2
taiku ctl setup --grid 2x2 --tiles "shell,shell,tunnel:3000,shell"
taiku ctl setup --grid 1x3 --tiles "shell,shell,shell" --commands "htop,git log,npm start"

ShellsCopy Anchor Link

Commands for creating, reading, and writing to terminal shells.

Commands that type into a shell or read one (write-to-shell, run, agent-prompt, rename-tile, get-shell-output, pane-read, pane-process-info) act only on the shell you run them in, and only when the session's owner has it open from the Admin link. If one is refused for that reason, open the session's Admin link and run it again.

Commands that open or close a shell (create-shell, split-h, split-v, close-shell) need the same, and run only from one of the owner's own shells. A new shell is the owner's, opened the way a click opens one, and close-shell closes only a shell of the owner's own.

list-shellsCopy Anchor Link

List all shells in the session.

taiku ctl list-shells

create-shellCopy Anchor Link

Create a new shell. Waits for server confirmation and returns the real shell ID.

taiku ctl create-shell

close-shellCopy Anchor Link

Close a shell of the session owner's own.

taiku ctl close-shell 3

write-to-shellCopy Anchor Link

Write data to a shell. To write to the shell the command runs in, pass "$TAIKU_SHELL_ID" as the ID.

taiku ctl write-to-shell 3 "ls -la\n"

runCopy Anchor Link

Execute a command (shorthand for write-to-shell with a newline appended).

taiku ctl run "ls -la"
taiku ctl run "npm start" --tile 2

get-shell-outputCopy Anchor Link

Get terminal output from a shell.

taiku ctl get-shell-output 3
taiku ctl get-shell-output 3 --chunks 5

list-terminal-namesCopy Anchor Link

Get shell names/titles as seen by the target client.

taiku ctl list-terminal-names

pane-readCopy Anchor Link

Read a pane's text. A browser tab answers it only for the shell the command runs in.

taiku ctl pane-read --current --source recent --lines 50

pane-process-infoCopy Anchor Link

Show what is running in a pane's shell, so a script can check the pane is at a prompt before typing into it. A browser tab answers it only for the shell the command runs in, and leaves the process id, process group and tty empty.

taiku ctl pane-process-info --shell 3

Session infoCopy Anchor Link

Commands for reading session metadata and user state.

get-sessionCopy Anchor Link

Get session metadata (ID, name, user count, shell count).

taiku ctl get-session

list-usersCopy Anchor Link

List the clients connected to the session, by id, display name and kind. Use the id with --client.

taiku ctl list-users

Returns:

[
  { "id": 1, "name": "nathanz", "clientKind": "browser" },
  { "id": 2, "name": "nathanz", "clientKind": "desktop" },
  { "id": 3, "name": "nathanz", "clientKind": "terminal" }
]

clientKind is browser (a web browser or the mobile app), desktop (the desktop app), terminal (a taiku tui client) or unknown. Running taiku ctl from a shell in the session routes to the client that owns that shell, so you rarely need to pick one.

get-roleCopy Anchor Link

Get the executing client's role (admin, writer, or reader).

taiku ctl get-role

get-ownershipCopy Anchor Link

Get shell ownership info: which shells this client owns, which are owned by others, and which are unowned.

taiku ctl get-ownership

adopt-shellCopy Anchor Link

Adopt a shell into the target client's workspace. Admins adopt directly; regular writers send a request to the current owner.

taiku ctl adopt-shell 5

EventsCopy Anchor Link

Chat has no CLI command; over REST, use the getChat and sendChat methods.

broadcast-eventCopy Anchor Link

Broadcast a plugin event to all connected clients. Cannot be targeted to a single client.

taiku ctl broadcast-event myevent --data '{"key": "value"}'

AgentsCopy Anchor Link

Commands for inspecting AI agent activity.

list-agentsCopy Anchor Link

List active AI agents detected in the session.

taiku ctl list-agents

get-agent-costCopy Anchor Link

Get token usage and cost summary across all agents.

taiku ctl get-agent-cost

list-agent-sessionsCopy Anchor Link

List agent sessions (distinct agent runs).

taiku ctl list-agent-sessions

list-agent-eventsCopy Anchor Link

Get events from a specific agent session.

taiku ctl list-agent-events abc123 --types tool_call,user_message --limit 20

agent-waitCopy Anchor Link

Wait until the agent in a pane settles, then print its state. Exits with code 4 on timeout.

taiku ctl agent-wait --tile 3 --until done

agent-promptCopy Anchor Link

Send a prompt to the agent running in a pane and check that it reacted. Fails with agentPromptStalled if the agent's state does not change within 5 seconds. Use run for a plain shell.

taiku ctl agent-prompt "run the tests" --tile 3 --wait --until done

Takes the same pane options as agent-wait, plus --wait to wait for the agent to settle afterwards (--until and --timeout then apply).

TunnelsCopy Anchor Link

list-tunnelsCopy Anchor Link

List active tunnel ports.

taiku ctl list-tunnels

CommentsCopy Anchor Link

commentCopy Anchor Link

Add a comment to a file as an agent. The file opens in a connected client so the comment can be anchored.

taiku ctl comment --file src/app.ts --line 42 --body "This can be null here"

list-commentsCopy Anchor Link

Read back the comments on a file: each thread's status, the lines it covers, the quoted text, and every reply, plus pending suggestions. The file opens in a connected client, which decrypts the comments.

taiku ctl list-comments --file src/app.ts --json

In a notebook each thread also names its cell, in a CSV file its row and column, and in a PDF its page.

resolve-commentCopy Anchor Link

Resolve a thread once it has been dealt with, or reopen it with --reopen.

taiku ctl comment --file src/app.ts --reply-to <thread-id> --body "Added a null check"
taiku ctl resolve-comment <thread-id> --file src/app.ts

suggestCopy Anchor Link

Suggest an edit. The file is not changed until a writer accepts it.

taiku ctl suggest --file README.md --match "teh" --text "the"

Takes the same --file, --line, --match and --author options as comment, plus --kind (insert, delete, or replace, the default) and --text for the new text.

NotificationsCopy Anchor Link

toastCopy Anchor Link

Show a toast notification on the target client.

taiku ctl toast "Build complete" --kind success

notifyCopy Anchor Link

Send a browser/desktop notification on the target client.

taiku ctl notify "Alert" --body "Something happened"