core

name	core
description	Core Supaterm CLI guide for controlling spaces, tab groups, tabs, panes, selectors, diagnostics, settings, licensing, and coding-agent integrations with `sp`. Read this before running Supaterm commands.

Supaterm core

Use sp to control Supaterm from a terminal already running inside Supaterm. Run sp skills get coding-agents before launching or prompting a coding agent.

Terminology

• Space: the top-level container, users might use this to separate work / life profile. Spaces are shared across windows: a space has one name, color, and position in the list, and every window can display it.
• Group: an ordered collection of tabs inside a space
• Tab: a terminal tab inside a space. Tabs belong to one window and one space, so the same space holds different tabs in each window.
• Pane: a split terminal region inside a tab

A window displays one space at a time and switches in place. Space commands switch the window they run in and never open, close, or touch another window.

Fast Start

Show setup commands and diagnostics:

sp onboard
sp diagnostic
sp instance ls

Inspect the live topology and copy a typed short ref:

sp ls

Use sp ls --json when durable automation needs canonical UUIDs.

Resolve the first project icon:

sp project icon
sp project icon ~/code/project --json

Inspect the license without exposing its key:

sp license

Creation commands use typed JSON keys instead of a generic id:

sp tab new --json
# => { "spaceID": "...", "tabID": "...", "paneID": "...", ... }

sp pane split --json right
# => { "spaceID": "...", "tabID": "...", "paneID": "...", ... }

sp tab new --plain and sp pane split --plain right print the new pane UUID for direct chaining.

List, create, and display spaces:

sp space ls
sp space new Work
sp space focus 1

Create, focus, and pin tabs:

sp tab new --focus
sp tab focus 1/2
sp tab pin 1/2
sp tab unpin 1/2

Create a group and place tabs in it:

sp group new Build --color blue
sp tab new --group Build
sp tab move 1/2 --group Build
sp group collapse Build

Omit both a trailing command and --script to start the account login shell.

The first argument after -- names an executable to launch directly. Supaterm resolves it with the caller's PATH, preserves all arguments exactly, skips shell startup files, and closes the tab or pane when the executable exits.

Use --script for builtins, aliases, or raw code for the account login shell to parse. Supaterm enters the text visibly and returns to the same shell after the script ends.

sp tab new --script 'printf "ready\n"; pwd'

Read JSON creation output for tabID and paneID. Capture the pane later with its UUID or a live p: ref: sp pane capture --scope scrollback --lines 160 <pane-target>.

Save any rendered pane as a PNG with sp pane screenshot <pane-uuid> --output pane.png.

Split panes and send commands:

Splits leave focus unchanged by default. Add --focus when the new pane should become active.

sp pane split down -- htop
sp pane split --layout keep right
sp pane send --newline 'echo hello'
sp pane key ctrl-c

Deep-Dive References

Load every reference:

sp skills get core --full

Resolve the version-matched directory when reading one reference directly:

sp skills path core

• Connection and diagnostics
• Project commands
• Targeting and selectors
• Space commands
• Group commands
• Tab commands
• Pane commands
• License commands
• Agent commands