Skip to main content

​
pioneer install

Install or replace the managed gateway binary and optionally start the service. 
pioneer install [--source local|release|channel] [--asset <path> --checksums <path>] [--channel stable|beta|canary] [--version x.y.z] [--managed-by desktop|script|manual|unknown] [--no-start] [--force-start] [--json]
Examples: 
pioneer install --source release --channel stable
pioneer install --source local --asset ./pioneer-gateway-linux-x86_64.gz --checksums ./SHA256SUMS
pioneer install --source local --asset ./asset.gz --checksums ./SHA256SUMS --no-start
Release install requires published gateway assets and a matching SHA256SUMS file for your OS, architecture, and gateway variant.

​
pioneer update

Alias: pioneer self-update Update the managed gateway binary using the same installer flow. 
pioneer update [--source local|release|channel] [--asset <path> --checksums <path>] [--channel stable|beta|canary] [--version x.y.z] [--managed-by desktop|script|manual|unknown] [--no-start] [--force-start] [--json]
Examples: 
pioneer update
pioneer update --source release --channel stable
pioneer update --source local --asset ./asset.gz --checksums ./SHA256SUMS --force-start
Release updates preserve the installed gateway variant. A headless gateway uses the standard release asset name; a computer-use gateway uses the -computer-use asset name.

​
pioneer start

Start the current-user gateway service. 
pioneer start
pioneer start --json
On Linux, pioneer start validates that a systemd --user service can survive logout. If systemd linger is disabled and cannot be enabled by the current user, the command fails with linux_linger_required in JSON install failures and tells you to run: 
sudo loginctl enable-linger "$USER"
On macOS and Windows, pioneer start --json can return warnings for direct script/manual installs because the current service modes start at user login, not before login.

​
pioneer status

Show service and gateway reachability status. 
pioneer status
pioneer status --json
Human output includes:
  • service name
  • listen address
  • service active state
  • gateway reachable state
  • runtime home
  • install state if present

​
pioneer issue-superuser-token

Generate and print a JWT for privileged clients. 
pioneer issue-superuser-token
Use this when adding a gateway connection from a custom client or remote desktop app. The token is signed with the current singleton superuser JWT material stored in the gateway keystore.
Treat this token like a password. It grants privileged access to the gateway.

​
pioneer secrets status

Show keystore status without printing secret values. 
pioneer secrets status
pioneer secrets status --json
Human output includes:
  • keystore path
  • encryption mode
  • total secret entry count
  • counts by secret kind
  • runtime directory and keystore file permission health
  • MCP orphan secret status
If gateway.db does not exist yet, MCP orphan status is reported as unavailable.

​
pioneer secrets garbage-collection

Clean orphan MCP secret values from the gateway keystore. 
pioneer secrets garbage-collection
pioneer secrets garbage-collection --dry-run
pioneer secrets garbage-collection --json
The command compares stored MCP secret refs with active MCP installation refs in gateway.db. It only deletes MCP secret values, and it refuses to run when gateway.db is missing. Use --dry-run to inspect counts without deleting anything.

​
pioneer secrets rotate-jwt-token superuser

Rotate the singleton superuser JWT signing material. 
pioneer secrets rotate-jwt-token superuser
pioneer secrets rotate-jwt-token superuser --json
Rotation does not print signing material or bearer tokens. If material already existed, existing superuser bearer tokens become invalid. Run pioneer issue-superuser-token afterwards to issue a fresh token.

​
pioneer stop

Stop and unregister the current-user gateway service. 
pioneer stop
The current CLI uses stop for service removal. There is no separate uninstall command.

​
pioneer version

Print CLI version information. 
pioneer version
pioneer version --json
pioneer --version
pioneer -V

​
pioneer help

Show CLI help. 
pioneer help
pioneer --help
pioneer -h

​
Install source options

OptionMeaning
--source localUse a local gateway asset and local checksum file
--source releaseDownload a release asset from GitHub Releases
--source channelRequire an explicit --channel and use that release channel
--asset <path>Local gateway archive path
--checksums <path>Local SHA256SUMS path
`—channel stablebetacanary`Release channel
--version x.y.zPin a release version
Release asset names include the OS, architecture, and optional gateway variant suffix. Standard headless assets use names like pioneer-gateway-linux-x86_64.gz; computer-use assets use names like pioneer-gateway-linux-x86_64-computer-use.gz.

​
Install behavior

The native installer flow:
  1. Resolves the asset and checksum file.
  2. Verifies the asset checksum.
  3. Stages the new binary.
  4. Stops the current service if needed.
  5. Atomically replaces the binary.
  6. Exposes the CLI command.
  7. Optionally starts the service.
  8. Checks gateway health.
  9. Rolls back on failure.
When --json is used, install/start output can include warnings. Treat these as service lifecycle caveats that did not prevent the gateway from starting. Linux headless persistence failures are blocking for script/manual installs because a systemd --user service without linger will stop when the login session ends.