CLI and Deep Links

Install aster in Settings → Shell → Aster CLI, then control the workspace from a Shell:

aster open ~/project --title API
aster view README.md --right
aster edit Sources/App.swift --new-window
aster jump project
aster learn ~/project
aster ignore ~/Downloads
aster pane capture --lines 100 --format json
aster pane send-text 'npm test\n'
aster pane run -- npm test
aster pane exec --format json -- git status --short

open/view/edit/jump/learn/ignore/capture are read-only or workspace actions. pane send/run/exec require Settings → Control → IPC Allow Sending Input; SSH/sudo and other sensitive sessions also require IPC Allow Sensitive Sessions. aster://learn?... handles only bounded directory-learning requests; ssh:// only prefills, never automatically executes.

The installed aster symlinks to aster-cli inside Aster.app, preferably in /usr/local/bin, otherwise ~/.local/bin when unwritable (ensure it is on PATH). Old sh-script installs are replaced. An unrelated existing aster is not overwritten; installation reports that conflict. The CLI uses a current-user-only local socket, normally ~/Library/Application Support/Aster/Control/aster.sock, falling back to $TMPDIR/aster-control.sock if HOME makes the path too long. It listens on no network port. Aster terminals receive the actual ASTER_SOCKET_PATH. Set absolute ASTER_CONTROL_SOCKET_PATH before launching the app to change its listener; CLI --socket <path> or ASTER_SOCKET_PATH selects it explicitly. If Aster is not running, the CLI launches it in the background and waits up to 5 seconds, then exits 69 if still unable to connect. aster --help and aster --version show syntax and version.

Within Aster terminals, commands can inspect and control other Panes and Agents:

aster session snapshot                       # All windows / tabs / Panes
aster agent list                             # Running Agents and status
aster agent read w1:p2 --lines 40            # Read an Agent's screen
aster agent prompt w1:p2 "Run the tests" --wait  # Submit and wait for idle
aster pane read --current --source recent
aster pane send-text --pane w1:p3 'npm test' --enter
aster pane wait-output w1:p3 --match "passed" --timeout 60000
aster pane split --current --direction down  # Split a new Pane below; prints its ID
aster pane close w1:p3                       # Close a Pane; closes the tab if it is the last one
aster tab new --cwd ~/project                # New tab, selected; prints tab and Pane IDs
aster tab focus w1:t2                        # Switch to a tab
aster tab rename w1:t2 "build"               # Pin the tab name; --clear restores the automatic title
aster tab close w1:t2                        # Close the whole tab
aster events subscribe --kind pane.agent_status_changed
aster notification show "Build complete" --body "All passed"
aster session terminals                      # Managed terminals and actual status
aster session detach --current               # Detach; background tasks continue
aster session end w1:p3                      # Terminate this managed terminal

pane split, pane close, tab new, and tab close start or end processes, so they need "Allow Send Keys" just like sending input. They run without a confirmation dialog (unsaved documents still prompt to save). pane close and tab close require an explicit target or --current. In tab commands the target can be a tab ID or the ID of any Pane inside that tab.

Remote TUI Client

Run the full terminal client in a remote SSH Shell with aster-session installed there:

aster-session ui <state-parent> <session-name>              # Interactive
aster-session ui <state-parent> <session-name> --observe    # Read-only observation
aster-session ui --remote <ssh-target> --session <name>     # Through SSH
aster-session ui --remote <ssh-target> --session <name> --observe  # Remote read-only

--remote SSHes from the local machine to run the remote TUI, without a manual ssh first. Targets are separated with -- and remote commands use POSIX quoting to prevent Shell reinterpretation.

Shortcuts use a Ctrl+B prefix:

Key	Action
Ctrl+B q / d	Detach; exit TUI while background tasks continue
Ctrl+B n	Next tab
Ctrl+B p	Previous tab
Ctrl+B o	Next Pane
Ctrl+B w	Next workspace
Ctrl+B c	New tab
Ctrl+B %	Horizontal split
Ctrl+B "	Vertical split
Ctrl+B x	Close current Pane
Ctrl+B Ctrl+B	Send literal Ctrl+B
Ctrl+B ?	Show help

The bottom bar shows workspace > tab [Pane/total]. Below 40×20, the TUI uses a compact layout.

session terminals/detach/end applies only to managed terminals running in the background session service. Closing a window or quitting Aster detaches; tasks continue and reopening attaches to the same process. Only end terminates it. One Aster window can input to a terminal at a time: with two Aster instances, the later one shows detached; Reattach transfers control, leaving the first detached until it takes control back. New terminals from the packaged app default to the managed path with background aster-session. ASTER_SESSION_BINARY and ASTER_SESSION_STATE_DIR override binary/state locations. Unmigrated old unmanaged layouts stay as they were. Ordinary local terminals are unaffected; detach/end on an ordinary Pane errors without ending its Shell. File offers equivalent detach/end/manage-layout actions. A normal background-service replacement stops it and cold-restores. Experimental live handoff can transfer PTY ownership without terminating processes, but is not exposed in the UI.

Short IDs identify windows (w1), tabs (w1:t2), and Panes (w1:p5); Agent names or --current from ASTER_PANE_ID also work. agent, events, and notification require Aster terminals (ASTER_ENV=1) unless explicitly using --allow-outside. Writes share the pane send/run/exec IPC switches. --json returns raw results; errors print {"code":"…","message":"…"} to stderr and exit 1.