Server CLI
Look up the commands supported by subshell-server.
Command summary
| Command | Purpose |
|---|---|
| No subcommand | Boot the control plane. |
help | Print usage; also --help and -h. |
version | Print version; also --version and -v. |
license | Print copyright and license notice. |
status | Read resolved configuration and diagnostics. |
init | Prepare first-run settings and offer a service. |
configure | Edit persistent configuration. |
service | Install and control a per-user service. |
backup | Create a full instance archive. |
restore | Inspect or restore an archive while the server is stopped. |
update | Check, apply, or roll back an update. |
reset | Stop and clear instance data, retaining the binary. |
uninstall | Remove the service and binary, optionally data. |
node | Hand a node to another account (node transfer; the API key comes from stdin). See Transfer a node. |
mcp | Serve pane-bound MCP over stdio. |
report | Report pane state from harness hooks. |
pane-log | Capture stdin for a tmux pane log. |
status
subshell-server status --jsonReads 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 GitHubLast updated on
