# CLI setup

Install an approved build, connect one environment, and verify read access.

## Prerequisites and installation

- Maintainer-approved test access and package tarball. `@postede/cli` is unpublished.
- Node.js 24+ and an operator-registered environment. Stop if any prerequisite is missing.
- Replace the placeholder path with the supplied approved tarball.

```sh
npm install --global /path/to/approved-postede-cli.tgz
postede --version
```

## Connect and verify

Select `local`, `dev`, or `production` explicitly. Client discovery uses
`/.well-known/postede-cli`; do not invent a client ID or switch environments
when discovery fails. The user completes browser sign-in and chooses permissions.
Credentials stay in the OS keychain; never request passwords, cookies or tokens
in conversation.

```sh
postede auth login --env local
postede auth status --env local --json
postede projects list --env local --json
```

Success requires status and project listing in the selected environment. An
empty project list is valid. Setup performs no content or delivery writes.

## Connection recovery

| Failure | Action |
| --- | --- |
| Expired access | CLI refreshes automatically. If refresh fails or consent is revoked, run `auth login` in the same environment with user approval. |
| Permission denied | Check granted scope and project access; request only missing access. |
| Rate limit | Wait for `retryAfterSeconds`; do not loop or repeatedly reconnect. |

[Exit codes and exact retry rules](https://postede.com/docs/cli/usage.md).

## Disconnect

```sh
postede auth logout --env local
```

Revokes the refresh credential and removes local credentials. `--local-only`
removes storage without server revocation. `revoked: false` does not prove
revocation; report failures. For immediate full-grant revocation, use
`/agent/connections` in the same environment.

[Command reference](https://postede.com/docs/cli/reference.md).