Subshell Docs

Server CLI

Look up the commands supported by subshell-server.

Command summary

CommandPurpose
No subcommandBoot the control plane.
helpPrint usage; also --help and -h.
versionPrint version; also --version and -v.
licensePrint copyright and license notice.
statusRead resolved configuration and diagnostics.
initPrepare first-run settings and offer a service.
configureEdit persistent configuration.
serviceInstall and control a per-user service.
backupCreate a full instance archive.
restoreInspect or restore an archive while the server is stopped.
updateCheck, apply, or roll back an update.
resetStop and clear instance data, retaining the binary.
uninstallRemove the service and binary, optionally data.
nodeHand a node to another account (node transfer; the API key comes from stdin). See Transfer a node.
mcpServe pane-bound MCP over stdio.
reportReport pane state from harness hooks.
pane-logCapture stdin for a tmux pane log.

status

subshell-server status --json

Reads boot configuration, source layers, paths, version, service state, tmux and MCP availability, and setup state. It doesn't start the server. Secret values are masked.

init and configure

Both accept --port <n>, --host <h>, --base-url <url>, --db-path <path>, --trusted-origins <comma-separated-origins>, --yes, and --verbose.

init additionally accepts --service and --no-service. --yes accepts configuration defaults, tmux installation, PATH updates, and the background service. A terminal-less run without that acceptance skips interactive extras and reports its defaults.

An empty trusted-origin argument clears operator extras; derived origins remain separate.

service

subshell-server service install [--no-autostart]
subshell-server service uninstall
subshell-server service enable
subshell-server service disable
subshell-server service status [--json]
subshell-server service start
subshell-server service stop
subshell-server service restart [--force]

Installation starts the service. Enable and disable change login startup without touching the current process. Restart's --force accepts a reported live-pane refusal.

backup

subshell-server backup [--output <archive>] [--encrypt]
                       [--password-file <file|->] [--json]

Every new backup is a full instance archive. Encryption defaults off; new encrypted archives require at least eight Unicode characters. See Backups and restoration for password guidance and offline guessing limits. Password files must be private, owned regular files containing one line; - reads a line from stdin. Passwords are never command-line arguments.

restore

subshell-server restore <archive> [--password-file <file|->] [--inspect] [--json]
subshell-server restore <archive> --prepare [choices] --no-start --json
subshell-server restore --list-staged --json
subshell-server restore --discard-staged <id> --json
subshell-server restore --staged <id> [--yes] [--force] [--no-start] [--json]

--prepare validates and saves an archive and its choices as a protected local stage without stopping the server or replacing state. Prepared destination paths remain fixed; prepare another archive to change them. Stages expire after ten minutes, and --discard-staged deletes one, including an expired stage.

An interactive restore asks for destination choices and confirms replacement. --yes accepts replacement; --force separately accepts the reported interruption of sessions that can't be preserved. Starting afterward defaults to yes; --no-start leaves the restored instance stopped, with the previous state retained until a successful boot.

For migration, use --mode migration with --data-dir, --database-path, --config-dir, and address overrides --base-url, --host, --port, and --trusted-origins. Network publication stays disabled until reviewed. The default mode is same-machine.

Optional account recovery uses --recover-admin <id> and --temporary-password-file <file|->. The selected existing administrator must change the temporary password before ordinary access. Recovery defaults off. Both password options can't read stdin together.

See Backups and restoration for archive scope, Settings staging, and recovery behavior.

update

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

--check reports update availability. --to requires the requested version to match the newest server release in the configured index. Use --from for a local file whose origin and integrity you've verified. --force allows downgrade and accepts pane disruption. Rollback can restore both the previous binary and database snapshot. Containers update by image replacement instead.

reset and uninstall

Both require the machine's name, typed interactively or supplied as --confirm <machine-name>. --yes is refused.

Reset removes data and settings while keeping the binary. Uninstall removes the binary and asks whether to remove data, defaulting to keep it. --reset-data answers uninstall's separate data question in a headless run; reset refuses that flag because it always clears data.

MCP and reporting

mcp is a long-running stdio child of an agent. report attention turn_complete|needs_attention|resumed and report session are harness-hook operations. pane-log --file <path> is used by tmux capture, not ordinary administration.

Logging

--verbose increases console detail on supported verbs or when booting the server. It can't be combined with --json. SUBSHELL_VERBOSE is its environment equivalent.

See also

Environment variables, Files and paths, and Server administration.

Edit on GitHub

Last updated on

On this page