#CLI Reference

coterm provides both a CLI tool and a Unix socket for programmatic control. Every command is available through both interfaces.

#Socket

Build	Path
Release	`/tmp/coterm.sock`
Debug	`/tmp/coterm-debug.sock`
Tagged debug build	`/tmp/coterm-debug-<tag>.sock`

Override with the COTERM_SOCKET_PATH environment variable. Send one newline-terminated JSON request per call:

{"id":"req-1","method":"workspace.list","params":{}}
// Response:
{"id":"req-1","ok":true,"result":{"workspaces":[...]}}

JSON socket requests must use method and params. Legacy v1 JSON payloads such as {"command":"..."} are not supported.

#Access modes

Mode	Description	How to enable
Off	Socket disabled	Settings UI or COTERM_SOCKET_MODE=off
Coterm processes only	Only processes spawned inside coterm terminals can connect.	Default mode in Settings UI
allowAll	Allow any local process to connect (no ancestry check).	Environment override only: COTERM_SOCKET_MODE=allowAll

On shared machines, use Off or Coterm processes only.

#CLI options

Flag	Description
`--socket PATH`	Custom socket path
`--json`	Output in JSON format
`--window ID`	Target a specific window
`--workspace ID`	Target a specific workspace
`--surface ID`	Target a specific surface
`--id-format refs\|uuids\|both`	Control identifier format in JSON output

#Workspace commands

list-workspaces

List all open workspaces.

CLI

coterm list-workspaces
coterm list-workspaces --json

Socket

{"id":"ws-list","method":"workspace.list","params":{}}

new-workspace

Create a new workspace.

CLI

coterm new-workspace

Socket

{"id":"ws-new","method":"workspace.create","params":{}}

select-workspace

Switch to a specific workspace.

CLI

coterm select-workspace --workspace <id>

Socket

{"id":"ws-select","method":"workspace.select","params":{"workspace_id":"<id>"}}

current-workspace

Get the currently active workspace.

CLI

coterm current-workspace
coterm current-workspace --json

Socket

{"id":"ws-current","method":"workspace.current","params":{}}

close-workspace

Close a workspace.

CLI

coterm close-workspace --workspace <id>

Socket

{"id":"ws-close","method":"workspace.close","params":{"workspace_id":"<id>"}}

#Split commands

new-split

Create a new split pane. Directions: left, right, up, down.

CLI

coterm new-split right
coterm new-split down

Socket

{"id":"split-new","method":"surface.split","params":{"direction":"right"}}

list-panels

List all surfaces in the current workspace.

CLI

coterm list-panels
coterm list-panels --json

Socket

{"id":"surface-list","method":"surface.list","params":{}}

list-pane-surfaces

List surfaces in the focused pane.

CLI

coterm list-pane-surfaces
coterm list-pane-surfaces --json

Socket

{"id":"pane-surfaces","method":"pane.surfaces","params":{}}

focus-panel

Focus a specific surface.

CLI

coterm focus-panel --panel <id>

Socket

{"id":"surface-focus","method":"surface.focus","params":{"surface_id":"<id>"}}

#Input commands

send

Send text input to the focused terminal.

CLI

coterm send "echo hello"
coterm send "ls -la\n"

Socket

{"id":"send-text","method":"surface.send_text","params":{"text":"echo hello\n"}}

send-key

Send a key press. Keys: enter, tab, escape, backspace, delete, up, down, left, right.

CLI

coterm send-key enter

Socket

{"id":"send-key","method":"surface.send_key","params":{"key":"enter"}}

send --surface

Send text to a specific surface.

CLI

coterm send --surface <id> "command"

Socket

{"id":"send-surface","method":"surface.send_text","params":{"surface_id":"<id>","text":"command"}}

send-key --surface

Send a key press to a specific surface.

CLI

coterm send-key --surface <id> enter

Socket

{"id":"send-key-surface","method":"surface.send_key","params":{"surface_id":"<id>","key":"enter"}}

#Notification commands

notify

Send a notification.

CLI

coterm notify --title "Title" --body "Body"
coterm notify --title "T" --subtitle "S" --body "B"

Socket

{"id":"notify","method":"notification.create","params":{"title":"Title","subtitle":"S","body":"Body"}}

list-notifications

List all notifications.

CLI

coterm list-notifications
coterm list-notifications --json

Socket

{"id":"notif-list","method":"notification.list","params":{}}

clear-notifications

Clear all notifications.

CLI

coterm clear-notifications

Socket

{"id":"notif-clear","method":"notification.clear","params":{}}

Set status pills, progress bars, and log entries in the sidebar for any workspace. Useful for build scripts, CI integrations, and AI coding agents that want to surface state at a glance.

set-status

Set a sidebar status pill. Use a unique key so different tools can manage their own entries.

CLI

coterm set-status build "compiling" --icon hammer --color "#ff9500" --priority 80
coterm set-status deploy "v1.2.3" --workspace workspace:2

Socket

set_status build compiling --icon=hammer --color=#ff9500 --priority=80 --tab=<workspace-uuid>

clear-status

Remove a sidebar status entry by key.

CLI

coterm clear-status build

Socket

clear_status build --tab=<workspace-uuid>

list-status

List all sidebar status entries for a workspace.

CLI

coterm list-status

Socket

list_status --tab=<workspace-uuid>

set-progress

Set a progress bar in the sidebar (0.0 to 1.0).

CLI

coterm set-progress 0.5 --label "Building..."
coterm set-progress 1.0 --label "Done"

Socket

set_progress 0.5 --label=Building... --tab=<workspace-uuid>

clear-progress

Clear the sidebar progress bar.

CLI

coterm clear-progress

Socket

clear_progress --tab=<workspace-uuid>

log

Append a log entry to the sidebar. Levels: info, progress, success, warning, error.

CLI

coterm log "Build started"
coterm log --level error --source build "Compilation failed"
coterm log --level success -- "All 42 tests passed"

Socket

log --level=error --source=build --tab=<workspace-uuid> -- Compilation failed

clear-log

Clear all sidebar log entries.

CLI

coterm clear-log

Socket

clear_log --tab=<workspace-uuid>

list-log

List sidebar log entries.

CLI

coterm list-log
coterm list-log --limit 5

Socket

list_log --limit=5 --tab=<workspace-uuid>

sidebar-state

Dump all sidebar metadata (cwd, git branch, ports, status, progress, logs).

CLI

coterm sidebar-state
coterm sidebar-state --workspace workspace:2

Socket

sidebar_state --tab=<workspace-uuid>

#Utility commands

ping

Check if coterm is running and responsive.

CLI

coterm ping

Socket

{"id":"ping","method":"system.ping","params":{}}
// Response: {"id":"ping","ok":true,"result":{"pong":true}}

capabilities

List available socket methods and current access mode.

CLI

coterm capabilities
coterm capabilities --json

Socket

{"id":"caps","method":"system.capabilities","params":{}}

identify

Show focused window/workspace/pane/surface context.

CLI

coterm identify
coterm identify --json

Socket

{"id":"identify","method":"system.identify","params":{}}

#Environment variables

Variable	Description
`COTERM_SOCKET_PATH`	Override the socket path used by CLI and integrations
`COTERM_SOCKET_ENABLE`	Force-enable/disable socket (1/0, true/false, on/off)
`COTERM_SOCKET_MODE`	Override access mode (cotermOnly, allowAll, off). Also accepts coterm-only/coterm_only and allow-all/allow_all
`COTERM_WORKSPACE_ID`	Auto-set: current workspace ID
`COTERM_SURFACE_ID`	Auto-set: current surface ID
`TERM_PROGRAM`	Set to ghostty
`TERM`	Set to xterm-ghostty

Legacy COTERM_SOCKET_MODE values full and notifications are still accepted for compatibility.

#Detecting Coterm

bash

# Prefer explicit socket path if set
SOCK="${COTERM_SOCKET_PATH:-/tmp/coterm.sock}"
[ -S "$SOCK" ] && echo "Socket available"

# Check for the CLI
command -v coterm &>/dev/null && echo "coterm available"

# In coterm-managed terminals these are auto-set
[ -n "${COTERM_WORKSPACE_ID:-}" ] && [ -n "${COTERM_SURFACE_ID:-}" ] && echo "Inside coterm surface"

# Distinguish from regular Ghostty
[ "$TERM_PROGRAM" = "ghostty" ] && [ -n "${COTERM_WORKSPACE_ID:-}" ] && echo "In coterm"

#Examples

#Python client

python

import json
import os
import socket

SOCKET_PATH = os.environ.get("COTERM_SOCKET_PATH", "/tmp/coterm.sock")

def rpc(method, params=None, req_id=1):
    payload = {"id": req_id, "method": method, "params": params or {}}
    with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as sock:
        sock.connect(SOCKET_PATH)
        sock.sendall(json.dumps(payload).encode("utf-8") + b"\n")
        return json.loads(sock.recv(65536).decode("utf-8"))

# List workspaces
print(rpc("workspace.list", req_id="ws"))

# Send notification
print(rpc(
    "notification.create",
    {"title": "Hello", "body": "From Python!"},
    req_id="notify"
))

#Shell script

bash

#!/bin/bash
SOCK="${COTERM_SOCKET_PATH:-/tmp/coterm.sock}"

coterm_cmd() {
    printf "%s\n" "$1" | nc -U "$SOCK"
}

coterm_cmd '{"id":"ws","method":"workspace.list","params":{}}'
coterm_cmd '{"id":"notify","method":"notification.create","params":{"title":"Done","body":"Task complete"}}'

#Build script with notification

bash

#!/bin/bash
npm run build
if [ $? -eq 0 ]; then
    coterm notify --title "✓ Build Success" --body "Ready to deploy"
else
    coterm notify --title "✗ Build Failed" --body "Check the logs"
fi

#CLI Reference

#Socket

#Access modes

#CLI options

#Workspace commands

list-workspaces

new-workspace

select-workspace

current-workspace

close-workspace

#Split commands

new-split

list-panels

list-pane-surfaces

focus-panel

#Input commands

send

send-key

send --surface

send-key --surface

#Notification commands

notify

list-notifications

clear-notifications

#Sidebar metadata commands

set-status

clear-status

list-status

set-progress

clear-progress

log

clear-log

list-log

sidebar-state

#Utility commands

ping

capabilities

identify

#Environment variables

#Detecting Coterm

#Examples

#Python client

#Shell script

#Build script with notification