Skip to main content
This reference covers direct gateway management. If you normally use the desktop app, start with CLI Overview and use this page when you need a command or flag.
Commands that print tokens or manage secrets can affect gateway access. Read the warning near the command before running it.

​
pioneer install

Install or replace the managed gateway binary and optionally start the service.
Examples:
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.
Examples:
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.
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:
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.
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.
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.
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.
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.
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.
The current CLI uses stop for service removal. There is no separate uninstall command.

​
pioneer task-invariants

Scan a gateway SQLite database for task runtime invariant violations.
The command exits non-zero when it finds violations. Use --json for automation and --stale-turn-after-seconds to tune stale turn detection.

​
pioneer version

Print CLI version information.

​
pioneer help

Show CLI help.

​
Install source options

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.

​
Further reading