> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getpioneer.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Commands

> Reference for the pioneer CLI commands and common flags.

This reference covers direct gateway management. If you normally use the desktop app, start with [CLI Overview](/cli/overview) and use this page when you need a command or flag.

<Note>
  Commands that print tokens or manage secrets can affect gateway access. Read the warning near the command before running it.
</Note>

## `pioneer install`

Install or replace the managed gateway binary and optionally start the service.

```bash theme={null}
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:

```bash theme={null}
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
```

<Note>
  Release install requires published gateway assets and a matching `SHA256SUMS` file for your OS, architecture, and gateway variant.
</Note>

## `pioneer update`

Alias: `pioneer self-update`

Update the managed gateway binary using the same installer flow.

```bash theme={null}
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:

```bash theme={null}
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.

```bash theme={null}
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:

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

<Warning>
  Treat this token like a password. It grants privileged access to the gateway.
</Warning>

## `pioneer secrets status`

Show keystore status without printing secret values.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
pioneer stop
```

<Note>
  The current CLI uses `stop` for service removal. There is no separate `uninstall` command.
</Note>

## `pioneer task-invariants`

Scan a gateway SQLite database for task runtime invariant violations.

```bash theme={null}
pioneer task-invariants --db <path>
pioneer task-invariants --db ~/.pioneer/gateway.db --json
pioneer task-invariants --db ~/.pioneer/gateway.db --stale-turn-after-seconds 120
```

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.

```bash theme={null}
pioneer version
pioneer version --json
pioneer --version
pioneer -V
```

## `pioneer help`

Show CLI help.

```bash theme={null}
pioneer help
pioneer --help
pioneer -h
```

## Install source options

| Option               | Meaning                                                      |          |                 |
| -------------------- | ------------------------------------------------------------ | -------- | --------------- |
| `--source local`     | Use a local gateway asset and local checksum file            |          |                 |
| `--source release`   | Download a release asset from GitHub Releases                |          |                 |
| `--source channel`   | Require an explicit `--channel` and use that release channel |          |                 |
| `--asset <path>`     | Local gateway archive path                                   |          |                 |
| `--checksums <path>` | Local `SHA256SUMS` path                                      |          |                 |
| \`--channel stable   | beta                                                         | canary\` | Release channel |
| `--version x.y.z`    | Pin 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.

## Further reading

* [Gateway Architecture](/architecture/gateway) explains what the service does after `pioneer start`.
* [Secret Storage](/architecture/secrets) explains `pioneer secrets` and `issue-superuser-token`.
* [Persistence](/architecture/persistence) explains the SQLite state inspected by `pioneer task-invariants`.