Every `authdog` command, grouped by the job it does. Install and sign-in are covered in the [CLI overview](/docs/cli). Global options such as `--json` and `--non-interactive` work on all of them.

Commands marked **after beta.3** are on the `main` branch and are not in the `0.1.0-beta.3` release. See [Release status](/docs/cli#release-status).

| Command | Needs a session | Needs a linked project |
| --- | --- | --- |
| `login`, `logout`, `status` | No | No |
| `whoami` | Yes | No |
| `link`, `init` | Yes | No. They create the link |
| `unlink` | No | No |
| `config pull`, `config diff`, `config patch` | Yes | Yes |
| `webhooks listen` | Yes | Yes |
| `webhooks verify` | No | No |
| `impersonate` | Yes | Yes |
| `deploy status` | Yes | Yes |
| `doctor` | No. It reports what is missing | No |
| `mcp install`, `mcp list`, `mcp uninstall` | No | No |
| `agent rp-init`, `agent onboard` | Yes | Yes |
| `device authorize` | No | No. A link supplies the issuer |
| `api` | Yes | No |

## Session

### login

```bash
authdog login
```

Opens the hosted sign-in page and waits for the browser to redirect to `http://127.0.0.1`. Saves the session to `credentials.json`. `authdog auth login` is an alias.

### logout

```bash
authdog logout
```

Deletes `credentials.json`. It does not revoke the session on the server.

### status

```bash
authdog status
```

Reports whether a session is stored and where the credentials file lives. It makes no network call and prints no token.

### whoami

```bash
authdog whoami
```

Calls `GET /v1/userinfo` with the saved session and prints the account. Use it to confirm the session is still valid. An expired session exits with code `3`.

## Project

### link

```bash
authdog link --tenant-id <uuid> --application-id <uuid> --environment-id <uuid>
```

Writes `.authdog/project.json`. Each flag is optional when your account has exactly one tenant, one project in it, or one environment in that project. Otherwise the command stops and names the missing flag.

### unlink

```bash
authdog unlink
```

Removes `.authdog/project.json`. Your session stays.

### init

```bash
authdog init
authdog init --framework nextjs --pm pnpm --env-file .env --dry-run
```

Detects the framework, links the directory when it is not linked yet, fetches the SDK config for the environment, merges env vars, creates the integration file, and installs the SDK package.

| Flag | What it does |
| --- | --- |
| `--framework <NAME>` | `nextjs`, `react`, `javascript`, `express`, or `fastapi`. Skips detection |
| `--pm <NAME>` | `npm`, `pnpm`, `yarn`, `bun`, `pip`, or `uv`. Skips lockfile detection. After beta.3 |
| `--env-file <PATH>` | Env file to merge into. Default `.env.local` |
| `--skip-install` | Do not run the package manager |
| `--dry-run` | Print the plan and write nothing |

The per-framework packages, env vars, and files are listed in [What init writes](/docs/cli#what-init-writes).

## Configuration as a file

`config` keeps a narrow slice of environment settings in `.authdog/config.json` so you can review changes before they go live.

### config pull

```bash
authdog config pull
```

Writes `.authdog/config.json` with four sections: `sessionConfig`, `redirectUris`, `oidcClients`, and `webhooks`. Secrets are redacted.

### config diff

```bash
authdog config diff
```

Compares the file with the live environment, section by section, and writes nothing. In JSON output, `matches` is `true` when all four sections agree. In `0.1.0-beta.3` this command is a placeholder.

### config patch

```bash
authdog config patch --dry-run
authdog config patch
```

Applies `sessionConfig` and `redirectUris` from the file to the environment. `oidcClients` and `webhooks` are read-only snapshots and are not applied. Run it with `--dry-run` first to see the change. The command refuses a file that contains a secret key, and reports `patch_refused`.

## Webhooks

### webhooks listen

```bash
authdog webhooks listen
authdog webhooks listen --forward http://127.0.0.1:3000/webhooks/authdog
```

With no flags, prints the 20 most recent deliveries for the linked environment once. With `--forward`, polls for new deliveries and POSTs each one to your local handler.

| Flag | What it does |
| --- | --- |
| `--forward <URL>` | Local URL that receives each delivery |
| `--interval-ms <N>` | Time between polls. Default `2000` |
| `--max-polls <N>` | Stop after this many polls. Default `60` |
| `--tunnel <URL>` | Point a webhook endpoint at a public tunnel while the command runs. After beta.3 |
| `--channel-id <ID>` | The webhook endpoint to repoint. Required with `--tunnel` |
| `--restore-url <URL>` | The URL to put back on exit. Required with `--tunnel` |

Tunnel mode rewrites the endpoint's URL for as long as the command runs, so it requires `--yes`. The API does not return the current webhook URL, which is why you supply `--restore-url` yourself. Ctrl+C stops polling and still restores the URL. Bring your own tunnel. Authdog does not host one.

### webhooks verify

```bash
authdog webhooks verify \
  --secret "$WEBHOOK_SECRET" \
  --signature "t=1760000000, v1=5f2b…" \
  --body '{"type":"NEW_USER"}'
```

Checks an `X-Authdog-Signature` header offline. The signature is HMAC-SHA256 over `{t}.{rawBody}`, and a timestamp more than 300 seconds from now is rejected. The command prints `valid` and exits `0` either way, so read the value. It needs no session. See [Events and webhooks](/docs/events-webhooks).

## Support and go-live

### impersonate

```bash
authdog impersonate --user-id <uuid> --reason "Support ticket 4821"
authdog impersonate revoke --grant-id <id>
```

Mints a short-lived sign-in URL for one end user in the linked environment. The CLI creates an impersonation grant for your account, then asks Identity for the URL. The action is recorded in the audit log.

| Flag | What it does |
| --- | --- |
| `--user-id <ID>` | The user to sign in as. Required |
| `--reason <TEXT>` | Why. Required with `--non-interactive` |
| `--duration-minutes <N>` | Grant lifetime. Default `30` |
| `--no-create-grant` | Use an existing grant and do not create one |
| `revoke --grant-id <ID>` | End a grant early. After beta.3 |

Impersonation has to be enabled for the environment first. See [Users in the console](/docs/console/users).

### deploy status

```bash
authdog deploy status
```

Read-only snapshot of the linked environment before you ship. It checks that the security posture, vanity domains, redirect URIs, and webhooks can each be read, and reports one row per check. It changes nothing.

### doctor

```bash
authdog doctor
authdog doctor --mcp --agent-sign-in
```

Runs local and network checks and prints one row each: `cli_version`, `credentials`, `api_health`, and `userinfo`. `--mcp` adds `mcp_metadata`, which fetches the MCP server's protected-resource metadata. `--agent-sign-in` adds the agent key and issuer checks that `agent doctor` runs.

## MCP

### mcp install

```bash
authdog mcp install
authdog mcp install --client claude
authdog mcp install --all
```

Registers the [Authdog MCP server](/docs/ai/mcp-server) (`https://api.authdog.com/mcp`) in a coding agent's user-level config. It writes the server URL only. The client signs in on first use, and no token is written to disk.

| Client | Flag | File |
| --- | --- | --- |
| Cursor | `--client cursor` (default) | `~/.cursor/mcp.json` |
| Claude Code | `--client claude` | `~/.claude.json` |
| VS Code | `--client vscode` | `mcp.json` in the VS Code user profile |
| Codex | `--client codex` | `~/.codex/config.toml` |
| Every installed client | `--all` | Skips clients that are not installed |

Other servers and settings in those files are left as they are. A file that is not valid JSON is not rewritten. `0.1.0-beta.3` supports Cursor only.

### mcp list

```bash
authdog mcp list
```

Prints the config path for each client.

### mcp uninstall

```bash
authdog mcp uninstall --client cursor
authdog mcp uninstall --all
```

Removes the Authdog entry and leaves every other server. In `0.1.0-beta.3` the command is accepted and removes nothing.

## Agents

These commands drive [Agent Sign-In](/docs/agent-sign-in) and agent onboarding. That page explains the flow. This is the flag reference.

| Command | What it does | Flags |
| --- | --- | --- |
| `agent doctor` | Checks the agent key and issuer | None |
| `agent rp-init` | Registers an OIDC client for agent sign-in. Prints the client secret once | `--name`, `--redirect-uri`, `--no-manifest` |
| `agent wait` | Polls until the redirect or code is issued | `--poll`, `--no-poll`, `--auth-token` |
| `agent prove` | Signs the waiting-page token and approves it | `--accept-disclosure` (required), `--key`, `--kid`, `--auth-token`, `--identity-host`, `--environment-id` |
| `agent onboard` | Creates or reuses an agent in the linked environment. Prints the secret once. After beta.3 | `--name`, `--description`, `--scope` (repeatable), `--tool` (repeatable), `--delegation`, `--identity-assertion`, `--verify` |

`rp-init` and `onboard` print a secret once and do not store it. Capture it when the command runs.

## Device flow

### device authorize

```bash
authdog device authorize --client-id <id> --client-secret <secret> --poll
```

Runs the OAuth 2.0 device authorization grant (RFC 8628) against an environment, for clients that cannot open a browser. It prints the verification URL and user code, then polls for the token when `--poll` is set.

| Flag | Env fallback | What it does |
| --- | --- | --- |
| `--client-id <ID>` | `CLIENT_ID`, `AUTHDOG_OIDC_CLIENT_ID` | OIDC client. Required |
| `--client-secret <SECRET>` | `CLIENT_SECRET`, `AUTHDOG_OIDC_CLIENT_SECRET` | Client secret. Required |
| `--issuer <URL>` | `ISSUER` | Issuer. Defaults to the linked environment |
| `--scope <SCOPE>` | None | Scope to request |
| `--poll`, `--no-poll` | None | Wait for approval, or print the codes and exit |

The client must have the device grant enabled. To build this flow into your own tool, follow the [Node.js CLI quickstart](/docs/quickstarts/nodejs-cli).

## Any API route

### api

```bash
authdog api GET /v1/userinfo
authdog api POST /v1/tenants/<tenantId>/applications/<applicationId>/environments --data '{"name":"staging"}'
```

Calls one published `/v1` route with the saved session. After beta.3.

- Methods: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`. `--data` takes a JSON body and is allowed on `POST`, `PUT`, and `PATCH`.
- The path must start with `/v1`. Absolute URLs and `..` are rejected, so the session is never sent to another host.
- Secret fields in the response are replaced with `***` before printing. That includes `clientSecret`, `signingSecret`, `access_token`, `refresh_token`, `token`, `secret`, and `password`.
- A `401` exits with code `3`. Any other non-2xx response exits with code `4` after printing the redacted body.

The routes are listed in the [API reference](/docs/api).
