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 func, curl, or automation scripts
• inspect layouts, shells, chat, or agent state
• build AI agent integrations that interact with terminal sessions

Quick start

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

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

Client targeting

Many commands operate on a specific browser client's state (layout, workspace, focus). taiku resolves the target client automatically:

Use taiku func list-users to see connected clients and their IDs.

Authentication

All remote commands require authentication as the session owner. The CLI uses your login credentials from taiku login, or you can pass --token <api_key>.

REST API

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 body

Response

{ "result": { ... } }

On error, returns an HTTP error status with a text body.

GET shortcuts

Common read commands have GET shortcuts:

Command reference

Layout

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

split-h / split-v

Split a tile horizontally or vertically, creating a new shell.

taiku func split-h              # Split focused tile
taiku func split-v --tile 3     # Split specific tile

close-tile

Close a tile from the layout.

taiku func close-tile --tile 3

reset-layout

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

taiku func reset-layout

toggle-direction

Toggle a split's direction between horizontal and vertical.

taiku func toggle-direction --tile 3

set-ratio

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

taiku func set-ratio 0.7 --tile 3

swap-tiles

Swap the positions of two tiles.

taiku func swap-tiles 1 2

maximize

Maximize a tile to fill the entire workspace.

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

focus-tile

Focus a specific tile.

taiku func focus-tile 3

focus-direction

Focus the neighboring tile in a direction.

taiku func focus-direction left

rename-tile

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

taiku func rename-tile "logs" 3

get-layout

Get the current layout with tile positions and sizes.

taiku func 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-tiles

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

taiku func list-tiles

get-tab-groups

List tab groups (tiles with multiple tabbed items).

taiku func get-tab-groups

Tabs

Commands for switching tabs inside a tabbed tile.

select-tab

Switch to a tab by zero-based index.

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

next-tab

Switch to the next tab in a tile.

taiku func next-tab
taiku func next-tab --tile 3

prev-tab

Switch to the previous tab in a tile.

taiku func prev-tab
taiku func prev-tab --tile 3

show-layout / show-tree

ASCII visualization of the current layout.

taiku func show-layout    # JSON pretty-print
taiku func show-tree      # Indented tree view

Workspaces

Commands for managing workspaces (virtual desktops).

list-workspaces

List workspaces.

taiku func list-workspaces

create-workspace

Create a new workspace.

taiku func create-workspace

switch-workspace

Switch to a workspace by index.

taiku func switch-workspace 0

list-user-tiles

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

taiku func list-user-tiles 2

setup

Set up a grid layout with specific tile types.

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

Shells

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

list-shells

List all shells in the session.

taiku func list-shells

create-shell

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

taiku func create-shell
taiku func create-shell --cwd /tmp

close-shell

Close a shell. Non-admin users can only close their own shells.

taiku func close-shell 3

write-to-shell

Write data to a shell. When run from inside a taiku shell without specifying an ID, writes to the current shell.

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

run

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

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

get-shell-output

Get terminal output from a shell.

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

get-terminal-names

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

taiku func get-terminal-names

Session info

Commands for reading session metadata and user state.

get-session

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

taiku func get-session

list-users

List connected users/clients. Use this to find client IDs for --client.

taiku func list-users

Returns:

[
  {
    "id": 1,
    "name": "nathanz",
    "canWrite": true,
    "device": "Mac Web",
    "clientKind": "browser"
  },
  {
    "id": 2,
    "name": "nathanz",
    "canWrite": true,
    "device": "Desktop App",
    "clientKind": "desktop"
  }
]

get-role

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

taiku func get-role

get-ownership

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

taiku func get-ownership

adopt-shell

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

taiku func adopt-shell 5

Chat

get-chat

Get chat history.

taiku func get-chat

send-chat

Send a chat message.

taiku func send-chat "hello everyone"

broadcast-event

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

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

Agents

Commands for inspecting AI agent activity.

list-agents

List active AI agents detected in the session.

taiku func list-agents

get-agent-cost

Get token usage and cost summary across all agents.

taiku func get-agent-cost

list-agent-sessions

List agent sessions (distinct agent runs).

taiku func list-agent-sessions

get-agent-events

Get events from a specific agent session.

taiku func get-agent-events abc123 --types tool_call,user_message --limit 20

Tunnels

list-tunnels

List active tunnel ports.

taiku func list-tunnels

Notifications

toast

Show a toast notification on the target client.

taiku func toast "Build complete" --kind success

notify

Send a browser/desktop notification on the target client.

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