Subshell Docs

Node CLI

Look up the commands supported by the subshell node binary.

Command summary

CommandPurpose
setupInteractive enrollment and service setup.
enrollEnrollment primitive without setup questions.
configureRepoint or store a rotated node key.
runRun the node daemon.
dashboardRun local node management without the daemon.
statusInspect recorded node state.
serviceControl the per-user daemon service.
maintenanceStop sessions and refuse new launches.
updateApply or roll back a binary update.
unenrollRemove enrollment credentials.
resetClear local node state while keeping the binary.
uninstallRemove the service and binary, optionally state.
version / licensePrint identity or license information.
mcp / report / pane-logPane integration operations.

setup and enroll

subshell setup --server <url> --key <setup-key> [--name <name>]
               [--data-dir <dir>] [--no-service] [--yes] [--json]
subshell enroll --server <url> --key <setup-key> --name <name>
                [--data-dir <dir>] [--json]

setup asks for a name and offers service installation. Supply --name with --yes, --json, or noninteractive setup. enroll always requires the name and doesn't offer a service.

configure

subshell configure [--server <url>] [--key <node-key>] [--json] requires at least one change. It keeps node identity and the trusted control-plane key. A setup key is refused here. A running daemon reloads valid connection settings on its next heartbeat and reconnects; a stopped daemon uses them when started.

run and dashboard

Both support --dashboard-port <n>; SUBSHELL_DASHBOARD_PORT is the environment equivalent. The management dashboard listens on 127.0.0.1:3090 by default and has no login. Host, Origin, and JSON-content checks protect browser requests, but another local OS user can reach the port.

On a machine with untrusted local users, set SUBSHELL_DASHBOARD=0 in the node daemon's environment and restart it to disable the dashboard. See Files and paths for the node configuration layers and Security model for the trust boundary.

status

subshell status [--json] [--probe] reads lock-file state and reports paths without exposing the node key.

Active probe

service

subshell service install [--no-autostart]
subshell service uninstall
subshell service status [--json]
subshell service start|stop
subshell service restart [--force]
subshell service autostart on|off [--json]

Install starts the daemon. Autostart changes future login behavior without stopping it. Restart can refuse a definition that would kill live panes; --force accepts that disruption.

maintenance

maintenance on [--yes] [--json] blocks new launches and tries to stop running subshells. Some may keep running if they can't be stopped. Without --yes, live panes are listed and the command refuses before changes. off allows launches again but doesn't restart stopped subshells; status reports local state. All three support --json.

update

subshell update [--check] [--to <version>] [--from <file>]
                [--force] [--yes] [--json] [--no-restart]
subshell update --rollback [--yes] [--json]

Check before disrupting work. Local files require your own provenance check. --force allows downgrade and accepts live-pane disruption. Rollback restores a previous binary when available.

unenroll, reset, and uninstall

unenroll [--yes] [--json] removes the node configuration and lock, keeping its data, binary, and service definition. It always refuses a live daemon. --yes can accept orphaning remaining panes.

reset stops local work, removes the service, and clears local node data while retaining the binary. uninstall also removes the binary and asks separately about data, defaulting to keep it. Both require the machine name, with --confirm <name> for a headless run; neither accepts --yes. Uninstall supports --reset-data.

The node's record remains on the server until its owner removes it. These commands don't reset another machine or the control plane.

Pane integration

mcp requires injected pane identity. report attention, report session, and report exit <status> are hook operations. pane-log --file <path> captures pane output. There is no node-side plugin command; plugins live on the server.

For environment overrides, see Files and paths to identify where to apply the value on the execution machine.

See also

Manage nodes and Version compatibility.

Edit on GitHub

Last updated on

On this page