CLI reference — SpaceApp Docs

Complete command families#

Prefix each command with npx --yes run-spaceapp@latest, or use the explicitly selected installed launcher version. Arguments shown in angle brackets are placeholders, not literal input.

Command	Purpose and effect
`help`	Show command list and supported options; works before installation.
`init`	Create installation configuration, secrets and runtime files; does not replace the complete install workflow.
`install`	Initialize/check prerequisites, pull/start the selected runtime, verify readiness and setup, optionally open browser. Also the preferred upgrade entry point.
`reinstall`	Recreate installation/runtime setup while preserving existing data and credentials through the supported flow.
`repair`	Inspect and repair existing configuration/runtime files; requires change approval.
`repair --dry-run`	Inspect intended repair without applying it.
`doctor`	Read-only check of Node.js, configuration, resources and Docker; one PASS/FAIL line each.
`doctor --fix`	Run repair behavior for the existing installation; not merely read-only diagnosis.
`up`	Start/apply the configured Compose stack.
`down`	Stop/remove the running Compose stack while retaining persistent data; interrupts services.
`status`	Show service state and bindings.
`logs`	Print the last 200 log lines of each service. Do not invent an unsupported follow flag.
`open`	Open the configured application URL in the host browser.
`support-bundle`	Write a small diagnostic JSON file (versions, settings, readiness); see Troubleshooting.
`update [version]`	Update runtime images through the launcher's version/update workflow.
`rollback`	Return to the recorded previous image/configuration version; not database reversal.
`backup`	Create a portable application backup with manifest/checksums.
`restore`	Restore the latest selected valid portable backup after explicit confirmation.
`factory-reset`	Safety-backup/reset workflow that removes application state; destructive.
`workspace add <path> [--read-only]`	Register an allowed host project mount.
`workspace list`	Print registered projects as JSON.
`workspace remove <id-or-path>`	Unregister a workspace.
`credentials set <provider>`	Read/import a provider key through masked input.
`credentials list`	Print the provider IDs the launcher accepts (bundled, owner-installed, experimental); it does not show which keys are stored.
`credentials remove <provider>`	Remove the local imported key; does not revoke upstream.
`provider install <provider>`	Owner-install a supported optional CLI.
`owner reset-password`	Reset owner password through masked local input.
`owner rotate-setup-token`	Refresh an expired/unclaimed setup token; refused after owner claim.
`uninstall`	Remove containers/network, retain configuration, data volumes, secrets and backups.
`uninstall --purge-data`	Remove runtime volumes after explicit destructive confirmation.

Do not assume restore takes an arbitrary file/path argument: the verified launcher selects the latest valid backup. backup and logs also do not accept arbitrary flags simply because Docker underneath has them.

Installation and global options#

Installation/reinstallation options include:

--profile auto|small|medium|large|light|standard: choose service/resource profile.
--access isolated|host-root: choose access policy where supported by platform/runtime.
--with-companions: include supported optional companion services.
--no-open: skip automatically opening a browser.
--keep-data: explicit preservation intent on reinstall.

Global options shown by the verified launcher:

--plan: print the planned action without executing the change.
--json: structured output where that command supports it; not a guarantee for all output.
--log-file <file>: append execution logs to a chosen file; review logs before sharing.
--local-images: use preloaded images; missing images fail. Intended for controlled offline/lab workflows, not proof that AI inference is offline.
--non-interactive: fail when required input is missing instead of prompting.
--answers <json|path>: supply answers; automated changes require explicit confirm:true.

support-bundle --out <path> is handled by the verified implementation to select a JSON output path. Check the chosen version before relying on options absent from abbreviated help. The launcher's complete help text, generated from the published package, is at the end of the CLI reference page.

Profile/access flags select choices but do not bypass final confirmation. Preserve license, elevation, typed destructive-confirmation and other gates. A dry-run establishes the plan, not that an installation or repair succeeded.

Automation example#

For an authorized unattended install, create a non-secret answers JSON file:

{
  "confirm": true,
  "profile": "auto",
  "access": "isolated",
  "companions": false,
  "telemetry": false,
  "open": false
}

Then run:

npx --yes run-spaceapp@latest install --non-interactive --answers answers.json

A file avoids platform-specific shell quoting problems. In launcher 1.1.1, "telemetry": false keeps the first-install ping off; SPACEAPP_TELEMETRY in the invoking environment overrides the file in either direction. Do not add provider keys or passwords to the answers file. Missing prerequisite approvals, terms acceptance or OS interactions can still prevent unattended completion. Read exit status and readiness evidence; a non-interactive process launch is not acceptance.

Use a dedicated installation root for a disposable test, and keep the root consistent on every follow-up command. Never reset an important installation to create a test fixture.

Complete launcher help#

This is the exact output of npx --yes run-spaceapp@1.1.4 help, generated from launcher 1.1.4. Run the same command, or help with your installed launcher, to see the text for your version.

SpaceApp self-hosted launcher

Usage: npx --yes run-spaceapp@latest <command>
       spaceapp <command>             Optional global launcher

  init                              Create a local SpaceApp installation
  install [--profile auto|small|medium|large|light|standard] [--access isolated|host-root] [--with-companions] [--no-open]
                                    Install prerequisites, initialize, and start
  reinstall [--keep-data] [--profile auto|small|medium|large|light|standard] [--access isolated|host-root] [--with-companions] [--no-open]
                                    Clean reinstallation preserving data and credentials
  repair [--dry-run]                Verify and repair configuration and runtime files
  up | down | status | logs         Manage the Docker application
  open                              Open the local web application
  doctor [--fix]                    Diagnose; --fix repairs existing config and runtime
  support-bundle                    Generate a diagnostic bundle JSON for support
  update [version] | rollback       Update or roll back images
  backup | restore                  Back up or restore persistent state
  factory-reset                     Safety backup, purge all volumes/data, and reset
  workspace add <path> [--read-only]
  workspace remove <id-or-path>
  workspace list
  credentials set <provider>        Read a credential from masked stdin
  credentials remove <provider>
  credentials list
  provider install <provider>       Install an optional CLI in its persistent volume
                                    codex, gemini, qwen, kimi, grok, claude, deepseek,
                                    autohand, cursor, copilot (also installed on first use)
  owner reset-password              Read the new password from masked stdin
  owner rotate-setup-token          Replace an expired unclaimed setup token
  uninstall [--purge-data]          Remove containers; keep data by default

Options:
  --plan                            Dry-run mode: print actions without executing
  --json                            Output structured JSON where supported
  --log-file <file>                 Append all execution logs to specified file
  --local-images               Use preloaded images only (offline/lab; missing images fail)
  --non-interactive                 Run non-interactively, failing on missing input
  --answers <json|path>             Pre-seed answers; automation requires confirm:true

Profiles (auto uses CPU, RAM and free disk, then checks Docker resources):
  small:  4 CPUs, 7 GiB usable RAM, 6.5 GiB fresh space; SpaceApp + OpenCode.
          Background integration workers and managed browser are disabled.
  medium: 4 CPUs, 11 GiB usable RAM, 8 GiB fresh space; adds background workers.
  large:  8 CPUs, 15 GiB usable RAM, 11 GiB fresh space; adds managed browser.
  light/standard: compatibility settings for existing installations.
Upgrades keep the installed profile unless you explicitly choose another one.
Upgrade space: missing layers + database checkpoint + 0.5 GiB reserve.
Cached target images need no extra image space; existing data stays in place.
Unknown layer sizes use a conservative estimate; space is rechecked after pull.
No automatic deletion of images, volumes, workspaces, or backups to free space.

Quick start: install (automatic profile, OpenCode first, browser opens on completion).
Windows PowerShell: use npx.cmd if script execution policy blocks npx.ps1.
The npx command requires Node.js 20.11+ installed; Docker is installed if missing.
Data lives in SPACEAPP_HOME (config/secrets) and persistent Docker volumes.
Use backup before major changes; uninstall preserves data unless --purge-data.
Never use factory-reset to solve an ordinary installation problem.

Automation: --non-interactive --answers '{"confirm":true,"profile":"auto","access":"isolated","companions":false,"telemetry":false,"open":false}'
For shells with different quoting, save that JSON to a file and pass --answers file.json.
Use help or <command> --help from any directory, including before installation.

Interactive setup wizard: install, reinstall, update, init, rollback, repair,
factory-reset, and uninstall ask questions and require a final confirmation
before any change. Command flags pre-select answers; unattended changes require explicit confirm:true.

Help for individual commands#

In launcher 1.1.4, <command> --help prints the same text as help for every command (init, install, reinstall, repair, up, down, status, logs, open, doctor, support-bundle, update, rollback, backup, restore, factory-reset, workspace, credentials, provider, owner, uninstall), so it is not repeated here.