Control CLI¶

kortty-cli is the command-line client for korTTY's Control API. It ships inside every korTTY package as a second launcher beside the application itself, finds the running korTTY on its own, authenticates, and turns the API's answers into something a shell script or a coding agent can act on.

It talks only to a korTTY running on the same computer as you, and only while that korTTY has the Control API switched on. Everything the API refuses, the CLI refuses too.

Where the command lives¶

kortty-cli is not a script — it is a real launcher built into the packaged application image, so it starts the bundled JVM without needing Java on your PATH.

Only the pacman package puts it on your PATH for you. Everywhere else, add the directory to PATH or link the launcher into a directory that is already on it:

# macOS
sudo ln -s /Applications/korTTY.app/Contents/MacOS/kortty-cli /usr/local/bin/kortty-cli

# Linux deb/rpm
sudo ln -s /opt/kortty/bin/kortty-cli /usr/local/bin/kortty-cli

# Windows, for the current user
[Environment]::SetEnvironmentVariable(
    'Path', $env:Path + ';C:\Program Files\korTTY', 'User')

The launcher is deliberately not called kortty: that name belongs to the graphical launcher (/usr/bin/kortty on Arch, korTTY elsewhere), and on macOS and Windows, whose filesystems ignore case, a second launcher called kortty would collide with it.

Shape of a command¶

kortty-cli <group> <command> [options]

The groups are pane, tab, window, agent, events, notify, raw, ping and schema, plus mcp, which is not a single call but a long-running server (see Serving MCP clients). Inside a group, a command name is the API method after the dot with its underscores spelled as dashes — pane.send_text is pane send-text. Four methods do not follow from their name and are worth learning: api.schema is schema, events.subscribe is events, notification.show is notify, and anything without a command of its own — events.unsubscribe, pane.resolve — is reached through raw.

Everything a command needs is a flag. There are no positional arguments except the key names of pane send-keys and agent send-keys, and the method and JSON of raw.

kortty-cli ping                                   # is a korTTY listening?
kortty-cli pane list                              # every open pane
kortty-cli pane read --focused --recent --lines 200
kortty-cli pane run --pane p1a2b3c4d --command 'make test'
kortty-cli pane wait-output --pane p1a2b3c4d --contains 'BUILD SUCCESSFUL' --timeout-ms 300000
kortty-cli raw events.unsubscribe '{"subscription":"s1"}'

kortty-cli schema prints the complete machine-readable command surface — every command, its options, its result shape, its errors and a worked example — straight from the running korTTY. The parameters, results and errors come from the same declarations the server dispatches, and each entry's cli line is checked against this client's own parser before release, so both describe the version you are actually talking to; use it rather than guessing, especially from a script that has to keep working across versions.

Command reference¶

Every flag the client accepts is one of the global flags below or belongs to one of the commands in the table after them. A flag that a command does not list is refused with exit 2 before anything is sent to korTTY.

Global flags¶

Commands¶

The --kind values of agent list and agent start are claude-code, codex, gemini-cli, minimax-code, qwen-code, opencode, cursor-agent, aider, amp, goose, crush, kiro, continue, grok, jules, copilot, grok-build, antigravity, cline and kilo. The --state values of agent list are blocked, working, done, idle and unknown.

tab close and tab rename are listed by the API as reserved; kortty-cli refuses them itself, so they never reach korTTY.

Choosing a pane¶

Every command that addresses one pane takes exactly one selector, and every selector is a flag. pane list, pane current and agent list take none, and agent start accepts --split-from in place of a selector:

Giving none of them, or more than one, is a syntax error (exit 2) that names the four; a bare p1a2b3c4d or @focused written where a flag belongs is a syntax error too.

--current is resolved by the client, not the server: it walks its own process ancestry and asks korTTY which pane owns one of those process ids. That is why it works from a sub-shell, a Makefile recipe or a nested script without any setup, and why it fails loudly with a clear message where it cannot work rather than addressing the wrong pane.

Opening a connection¶

kortty-cli tab create --connection <id|name> opens a saved or teamwork connection in a new tab and prints the tab. --isolation none|process|sandbox runs it with that session isolation instead of the connection's own, --incognito opens it as an incognito session, and --window w2 picks the window. The organization's minimum isolation is never undercut: asking for less is refused with exit 3. When signing in needs a question, the answer says "pending": true and korTTY asks you before it opens the tab.

kortty-cli tab create --connection web-01 --isolation sandbox --incognito

Waiting¶

Commands that wait — pane wait-output, agent wait, agent prompt --wait-until, agent start --wait — block until the condition is met or the timeout expires, and exit 4 on a timeout. Every wait has a server-side hard cap of ten minutes; a longer request is clamped and the answer says so.

Requests on one connection run one at a time, so a script that wants to wait on one pane while doing something in another simply runs two commands concurrently — each opens its own connection. Up to eight connections may be open at once.

Watching events¶

kortty-cli events subscribes to korTTY's coding-agent events and prints one JSON object per line, as they happen, until it is told to stop.

kortty-cli events --kinds agent.state_changed --panes p1a2b3c4d --count 1
kortty-cli events --include-evidence --timeout 60000

--kinds and --panes take comma-separated lists and narrow what is delivered. The kinds are agent.added, agent.state_changed, agent.seen, agent.alias_changed, agent.removed, agent.evidence and events.overflow. Without --kinds, every kind except agent.evidence is sent. agent.evidence is sent only with --include-evidence, and at most once a second per pane. events.overflow is always sent and reports how many frames were dropped when the stream fell behind. --count N stops after N events. Three things end the stream: --count is reached, the --timeout passes, or you interrupt it. The first two exit 0. An interrupt is not handled — there is deliberately no signal handler, so the process ends with the shell's 128 + SIGINT = 130, which is worth allowing for in a CI job that wraps the stream in timeout.

With neither --count nor --timeout, the stream has no deadline at all and runs until korTTY exits or you stop it.

Serving MCP clients¶

kortty-cli mcp turns the client into a Model Context Protocol server, so an AI assistant that speaks MCP can read your korTTY panes. It speaks the MCP stdio transport only: the assistant's host starts kortty-cli mcp as a child process and exchanges newline-delimited JSON-RPC messages with it on stdin and stdout. There is no network listener; the process reaches korTTY over the same local Control API endpoint as every other command, and declares itself as an mcp client so korTTY applies the MCP rules to every request.

korTTY has to allow it: the Control API must be on, the separate MCP server switch under Settings › Terminal › Control API must be on, and the enterprise policy must not deny mcp-server. While any of them says no, every tool call returns an error that says why, and the assistant can still list the tools.

Most MCP hosts are configured with a JSON entry like this one; put the full path of kortty-cli from the table above in command if it is not on your PATH:

{
  "mcpServers": {
    "kortty": {
      "command": "kortty-cli",
      "args": ["mcp"]
    }
  }
}

The server offers these tools. Each argument has the name of the API parameter it fills, and pane takes a pane id from pane_list or @focused:

The read tools are marked read-only and the write tools destructive, so a host that asks before destructive tools asks before each of them. korTTY asks as well, whatever the host does: every write tool call opens a consent prompt in korTTY, and a write tool call waits up to 70 seconds for your answer before it gives up. A tool result is the API's JSON answer as text; korTTY has already masked the secrets it knows about and capped the size. A refusal, a denied or unanswered prompt, a stopped korTTY or a switched-off MCP server comes back as a tool error naming the reason, for example method_not_allowed_for_mcp or mcp_write_denied, and the assistant can show it to you. The tool list is read once per tools/list request, so switching the write tools on or off takes effect the next time the assistant lists the tools.

Each tool call opens its own connection, so restarting korTTY needs no restart of the assistant. Calls are handled one at a time: a long pane_wait_output delays the next answer until it returns. stdout carries only protocol messages; kortty-cli mcp writes one diagnostic line per request to stderr, naming the method or tool but never its arguments or results, and --quiet silences those lines. --config-dir works as for every other command.

Exit codes¶

The exit code comes from the server, not from a table the client keeps, so the two can never disagree.

Every failure prints a one-line diagnostic on stderr in the form kortty-cli: <message> (<code>), where <code> is the stable wire code — not_found, timeout, blocked_by_policy — that the exit code above was derived from. Add --pretty to get the whole JSON-RPC error object instead, which is what a script should branch on:

kortty-cli pane read --focused --pretty 2>err.json || code=$(jq -r .error.data.code err.json)

Failures the client diagnoses on its own are the exception: an unparseable command line, a korTTY that is not running, a --current that matches no pane and an expired client deadline never reached the server, so they carry no wire code and print a bare kortty-cli: <message> on either setting. Branch on the exit code for those.

Checking the installation¶

kortty-cli --version prints the version and exits 0. --version and --help both answer without a running korTTY, which makes --version the right thing to put in an installation check or a CI smoke test.

kortty-cli --version || echo 'kortty-cli is not installed or not on PATH'

Scripting notes¶

• Nothing is written to stdout except the command's result, so kortty-cli pane read --focused pipes cleanly.
• Diagnostics, warnings and error objects go to stderr.
• The authentication token is read from ~/.kortty/control/endpoint.json by the client. There is no --token option and no environment variable, deliberately: a token on a command line ends up in the process list and in your shell history.
• korTTY logs one line per action the CLI performs, and raises one desktop notification the first time a program types into a pane. Your script is not invisible, by design.