# Access

## Sign in

Sign in on waitcher.dev with Google. The CLI uses the same account:

```sh
waitcher auth login
waitcher auth status
waitcher auth logout
```

`auth login` opens a browser and receives the sign-in on a local loopback port; it gives up after 180 seconds (`--timeout` changes that). The session is saved privately under `~/.config/waitcher/` and refreshes itself. `auth logout` revokes the session and removes the local copy.

## Access tokens

Agents and CI sign in with an automation token instead of a browser. Tokens keep your account limits; they never grant more than you have.

| Permission | Allows |
| --- | --- |
| `read` | Your monitors, projects, reports, incidents, logs and evidence |
| `write` | Creating, editing and deleting configuration, including deploys and secrets |
| `run` | Manual runs (including `--smoke`) and alert channel tests |

Create tokens in the web app under Access tokens, or from a signed-in CLI session. Describe the token in a JSON file:

```json
{ "name": "CI agent", "scopes": ["read", "write"], "expiresInSeconds": 2592000 }
```

```sh
waitcher token create --file token.json --output ./private/ci-token.json
waitcher auth login --token-file ./private/ci-token.json
```

- The token is written once into a new file (mode 600, in a directory with mode 700) and never printed. `auth login --token-stdin` reads it from a pipe instead.
- Tokens expire after 1 hour to 90 days (default 30 days).
- `token list`, `token rotate --id ID --expected-revision N --output NEW_FILE` and `token revoke --id ID --expected-revision N` manage them. Rotation keeps permissions and expiry. Managing tokens needs a human session; a token cannot create or change other tokens.
- `auth logout` with a token revokes that token everywhere, including copies.
- If a create or rotate response is lost, check `token list` and revoke or rotate the affected token rather than repeating the command.

## Project reach

A token can be limited to one project. In the web app, set Reach to the project; in the CLI, add `projectId`:

```json
{ "name": "GitHub Actions", "scopes": ["read", "write", "run"], "projectId": "PROJECT_ID" }
```

The project ID is `project.id` in the output of `waitcher deploy plan` once the project exists (after the first apply, or `waitcher project list`). A project token can plan, apply and roll back deploys, manage that project's secrets, read its monitors, start runs and read their results. It cannot create projects, list your other monitors or touch other projects. This is the token to give CI ([CI](ci.md)).