> ## 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 Overview

> Use the pioneer CLI to install, start, stop, inspect, update, and authenticate the gateway.

The `pioneer` CLI manages the gateway service and provides maintenance commands for its secrets and runtime state.

Use it to:

* installing the gateway on a server
* checking gateway health
* starting or stopping the service
* updating gateway binaries
* issuing a token for protocol clients
* checking keystore status and permissions
* cleaning orphan MCP secret values
* rotating the superuser JWT signing material
* scanning task runtime invariants in a gateway database
* debugging a desktop connection problem

## Common commands

```bash theme={null}
pioneer status
pioneer start
pioneer stop
pioneer update
pioneer issue-superuser-token
pioneer secrets status
pioneer secrets garbage-collection --dry-run
pioneer secrets rotate-jwt-token superuser
pioneer task-invariants --db ~/.pioneer/gateway.db
pioneer version
pioneer help
```

## JSON output

Several commands support `--json`:

```bash theme={null}
pioneer status --json
pioneer start --json
pioneer secrets status --json
pioneer secrets garbage-collection --json
pioneer secrets rotate-jwt-token superuser --json
pioneer task-invariants --db ~/.pioneer/gateway.db --json
pioneer version --json
```

Use JSON output for scripts, health checks, or automation.

## Production and development binaries

Production binary:

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

Development binary:

```bash theme={null}
pioneer-dev
```

The development binary is built with:

```bash theme={null}
cargo run -p pioneer-cli --features dev --bin pioneer-dev -- help
```

Development uses separate config, service name, runtime home, install paths, and default port.

## Service behavior

`pioneer start` registers and starts a current-user service.

`pioneer stop` stops and unregisters the service.

The service runs as the current OS user.

| Platform | Service mode                | Notes                                                                                                                                     |
| -------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Linux    | `systemd --user` service    | Server/headless installs require systemd linger. If automatic setup is denied, run `sudo loginctl enable-linger "$USER"` and start again. |
| macOS    | per-user LaunchAgent        | Starts after user login. It is not a boot-time LaunchDaemon.                                                                              |
| Windows  | current-user Scheduled Task | Starts at user logon. It is not a boot-time Windows Service.                                                                              |

<Warning>
  Tool runs execute as the user account running the gateway service.
</Warning>

## Related

<Card title="CLI Commands" icon="code" href="/cli/commands">
  See command syntax, flags, and examples.
</Card>

## Further reading

* [Gateway Architecture](/architecture/gateway) explains the service the CLI starts and stops.
* [Secret Storage](/architecture/secrets) explains the keystore commands and superuser token material.
* [Persistence](/architecture/persistence) explains the gateway database used by task invariant checks.