Supacode CLI
Control Supacode from the terminal. The supacode command is available in all Supacode terminal sessions.
CRITICAL: ID Tracking
NEVER call supacode tab new or supacode surface split without capturing
the output. These commands print the new resource UUID to stdout. You MUST
capture it into a variable — without it you cannot target the resource afterward.
NEVER omit -t and -s flags when targeting a resource you created.
The environment variables $SUPACODE_TAB_ID and $SUPACODE_SURFACE_ID refer
to the shell session you are running in, NOT to any tab or surface you created.
If you omit -t/-s, the command targets your own shell — not the new resource.
For new tabs, the initial surface ID equals the tab ID.
Correct pattern — ALWAYS follow this:
Run all related commands in a SINGLE Bash call so captured variables
are available to subsequent commands. If you split across tool calls,
variables like $TAB_ID will be lost.
# 1. ALWAYS capture the UUID from tab new / surface split.
TAB_ID=$(supacode tab new -i "npm start")
# 2. ALWAYS pass -t and -s explicitly when targeting created resources.
# For new tabs: surface ID = tab ID.
SPLIT_ID=$(supacode surface split -t "$TAB_ID" -s "$TAB_ID" -d v -i "npm test")
# 3. ALWAYS use captured IDs for subsequent operations.
supacode surface focus -t "$TAB_ID" -s "$SPLIT_ID" -i "echo hello"
supacode surface close -t "$TAB_ID" -s "$SPLIT_ID"
supacode tab close -t "$TAB_ID"
WRONG — never do this:
# BAD: not capturing the UUID — you lose the reference.
supacode tab new -i "npm start"
# BAD: missing -t/-s — this targets your own shell, not the new tab.
supacode surface split -d v -i "npm test"
# BAD: splitting commands across separate Bash calls — variables are lost.
# Call 1: TAB_ID=$(supacode tab new)
# Call 2: supacode surface split -t "$TAB_ID" ... ← $TAB_ID is empty!
CRITICAL: Archiving or Deleting the Current Worktree
supacode worktree archive and supacode worktree delete remove the worktree
from Supacode's active terminals. Run against the worktree you are working in,
they close your own surface: commands after the call do not run. Worktrees
removed directly through Git disappear the same way once Supacode refreshes.
--background does not change this; it only leaves focus untouched.
Make archiving or deleting your own worktree your FINAL operation. Finish all edits, checks, commits, integration, and reporting first, and do not chain or schedule follow-up commands after it.
Sandboxed Harnesses
supacode talks to the app over a Unix domain socket. Sandboxes that deny
socket connections fail every command with "Operation not permitted"; that is
the sandbox, not Supacode. Re-run the command with escalated permissions
(approve the elevation prompt) or from an unsandboxed shell.
Environment
Inside Supacode terminals, these environment variables are set automatically:
| Variable | Description |
|---|---|
SUPACODE_WORKTREE_ID |
Current worktree (percent-encoded path). |
SUPACODE_TAB_ID |
Current tab UUID (your shell's tab, not created ones). |
SUPACODE_SURFACE_ID |
Current surface UUID (your shell's surface, not created ones). |
SUPACODE_REPO_ID |
Current repository (percent-encoded path). |
SUPACODE_SOCKET_PATH |
Socket for app communication. |
-w, -t, -s, -r default to these when omitted. This is only useful for
targeting your own session. For anything you create, pass explicit IDs.
Commands
App
supacode # Bring Supacode to front.
supacode open # Same as above.
Worktree
supacode worktree list [-f] [--status <status>] [--not-archived] [--with-status] # List worktree IDs (-f = focused only).
supacode worktree status [-w <id>] # Read status/archived/focused for one worktree.
supacode worktree focus [-w <id>] # Focus worktree.
supacode worktree run [-w <id>] [-c <uuid>] [--background] # Run script (default: primary run-kind; -c for a specific UUID).
supacode worktree stop [-w <id>] [-c <uuid>] [--background] # Stop script (default: all run-kind; -c for a specific UUID).
supacode worktree script list [-w <id>] # List configured scripts (id / kind / name).
supacode worktree archive [-w <id>] [--background] # Archive worktree.
supacode worktree unarchive [-w <id>] [--background] # Unarchive worktree.
supacode worktree delete [-w <id>] [--background] # Delete worktree.
supacode worktree pin [-w <id>] [--background] # Pin worktree.
supacode worktree unpin [-w <id>] [--background] # Unpin worktree.
supacode worktree appearance [-w <id>] [--title <title>] [--color <value>] # Read stored title/tint overrides; flags update them (empty title or color none clears).
Tab
supacode tab list [-w <id>] [-f] # List tab UUIDs in worktree (-f = focused only).
supacode tab focus [-w <id>] [-t <id>] # Focus tab.
supacode tab new [-w <id>] [-i <cmd>] [-n <uuid>] [--title <title>] [--background] # Create tab (prints UUID to stdout).
supacode tab rename [-w <id>] [-t <id>] --title <title> # Rename tab (empty title clears override; script tabs are locked).
supacode tab close [-w <id>] [-t <id>] [--background] # Close tab.
Surface
supacode surface list [-w <id>] [-t <id>] [-f] # List surface UUIDs in tab (-f = focused only).
supacode surface focus [-w <id>] [-t <id>] [-s <id>] [-i <cmd>] # Focus surface.
supacode surface split [-w <id>] [-t <id>] [-s <id>] [-i <cmd>] [-d h|v] [-n <uuid>] [--background] # Split (prints UUID to stdout).
supacode surface close [-w <id>] [-t <id>] [-s <id>] [--background] # Close surface.
Repository
supacode repo list # List repository IDs.
supacode repo open <path> # Open repository.
supacode repo worktree-new [-r <id>] [--branch <name>] [--base <ref>] [--upstream <ref> | --no-upstream] [--fetch] [--name <folder>] [--location <dir>] [--pin] [--background] # Create worktree (prints the new worktree ID to stdout; --upstream sets the new branch's tracking branch, --no-upstream clears it; --pin pins it as soon as creation starts, local repositories only).
Settings
supacode settings [<section>] # Open settings (general|notifications|worktrees|developer|shortcuts|scripts|updates|github).
supacode settings repo [-r <id>] # Open repository settings.
supacode settings repo scripts [-r <id>] # Open repository Scripts settings.
Socket
supacode socket # List active socket paths.
Output Formats
list commands output one ID per line: percent-encoded paths for worktrees and
repositories, UUIDs for tabs and surfaces. Use these IDs directly as -w, -t,
-s, -r, -c flag values.
worktree list filters with --status main|pinned|unpinned|archived
(comma-separated) or --not-archived (not both); --with-status appends a
tab-separated status column.
worktree status outputs status=<value>, archived=<true|false>, and
focused=<true|false> for a single worktree.
worktree script list outputs tab-separated <uuid>\t<kind>\t<displayName>
rows. When stdout is a TTY, running scripts are ANSI-underlined; captured or
piped output carries no running indicator.
worktree appearance with no flags outputs title=<stored override>,
color=<stored override or none>, and displayTitle=<effective title>.
With --title / --color, omitted update flags preserve existing values;
--title "" clears the title override and --color none clears the tint.
Background Mode
Pass --background when acting on behalf of a user working elsewhere: it
leaves the sidebar selection and keyboard focus untouched, and new tabs and
splits stay in the background instead of becoming active. It is accepted by
every action that would otherwise focus its target (tab new, surface split,
repo worktree-new, worktree run/stop/archive/unarchive/delete/
pin/unpin, and the close commands); the focus commands do not accept it.
Flag Reference
| Flag | Short | Default | Description |
|---|---|---|---|
--worktree |
-w |
$SUPACODE_WORKTREE_ID |
Worktree ID. |
--tab |
-t |
$SUPACODE_TAB_ID |
Tab UUID. |
--surface |
-s |
$SUPACODE_SURFACE_ID |
Surface UUID. |
--script |
-c |
- | Script UUID (for worktree run/stop). |
--title |
- | - | Tab title for tab new/rename, or sidebar title for worktree appearance; an empty string clears it for rename and appearance (rejected by tab new). |
--color |
- | - | Sidebar tint override; pass none to clear. |
--repo |
-r |
$SUPACODE_REPO_ID |
Repository ID. |
--input |
-i |
- | Command to run in the terminal. |
--direction |
-d |
horizontal |
Split direction (horizontal/h or vertical/v). |
--id |
-n |
random | UUID for new tab/surface. |
--focused |
-f |
- | Print only the focused item in list commands. |
--background |
- | - | Do not move the selection or focus; see Background Mode. |
--timeout |
- | app default | Seconds to wait for the app's response; 0 waits indefinitely. |