The Authdog CLI is the terminal client for your Authdog account. It signs you in through the browser, links a repository to one environment, writes the SDK env vars, and runs console operations from the shell. The binary is `authdog`. The source is at [github.com/authdog/cli](https://github.com/authdog/cli).

Use it when you would otherwise copy ids and keys out of the console by hand, or when a script or a coding agent has to do the setup.

## Install

Prebuilt binaries are served from `cli.auth.dog`, which resolves the newest published GitHub Release for your OS and architecture.

```bash
curl -fsSL https://cli.auth.dog/install | bash
```

On Windows, in PowerShell:

```powershell
iwr -useb https://cli.auth.dog/install.ps1 | iex
```

The installer puts `authdog` in `$HOME/.local/bin` on Linux and macOS, and in `%LOCALAPPDATA%\Programs\authdog` on Windows. Make sure that directory is on `PATH`, then check the install:

```bash
authdog --version
```

| Installer setting | What it does |
| --- | --- |
| `INSTALL_DIR` | Install to another directory |
| `AUTHDOG_CLI_VERSION` | Install one release tag, for example `0.1.0-beta.3`. Tags are bare semver with no leading `v` |
| `AUTHDOG_CLI_YES=1` | Skip the confirmation prompt |
| `AUTHDOG_CLI_USE_MUSL=1` | Install the musl build on Linux (x86_64 and aarch64) |

Environment variables in front of `curl` do not reach `bash`. Put them in front of `bash`, or use the `?version=` query for a pinned tag:

```bash
curl -fsSL https://cli.auth.dog/install | AUTHDOG_CLI_VERSION=0.1.0-beta.3 bash
curl -fsSL 'https://cli.auth.dog/install?version=0.1.0-beta.3' | bash
```

Builds exist for Linux (x86_64, aarch64, i686, armv7, and musl for x86_64 and aarch64), macOS (Intel and Apple silicon), and Windows x86_64.

## Quick start

Run these from the root of the app you want to protect.

```bash
authdog login
authdog init
authdog whoami
```

1. `login` opens the hosted sign-in page in your browser and stores the session on this machine.
2. `init` detects the framework, links the directory to a tenant, project, and environment, writes the env vars, and installs the SDK.
3. `whoami` confirms which account the session belongs to.

To see what `init` would do before it touches anything:

```bash
authdog init --dry-run
```

`init` links to a project and environment that already exist. Create them in the [console](https://console.authdog.com) first, or through the [MCP server](/docs/ai/mcp-server).

## Sign in

`authdog login` opens the hosted sign-in page and listens on `http://127.0.0.1` on a free port for the redirect. If the browser never comes back, check for a VPN, firewall, or proxy that blocks loopback.

The session is saved as `credentials.json` in the CLI config directory, with file mode `0600` on Linux and macOS.

| OS | Config directory |
| --- | --- |
| Linux | `$XDG_CONFIG_HOME/authdog-cli`, or `~/.config/authdog-cli` |
| macOS | `~/Library/Application Support/com.Authdog.authdog-cli` |
| Windows | `%APPDATA%\Authdog\authdog-cli` |

Set `AUTHDOG_CONFIG_DIR` to use another directory. That is how you keep a second account, or a CI job, apart from your own session.

Sessions are not refreshed in the background. When one expires, the command exits with code `3` and you run `authdog login` again.

`authdog status` tells you whether a session is stored and where. `authdog logout` deletes the file. Neither command prints a token.

## Link a project

Most commands act on one environment. The link tells them which one.

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

With no flags, `link` fills in the tenant, project, and environment when your account has exactly one of each. When there is more than one, it stops and names the flag to pass. It does not show a picker. You can copy the ids from the console, or list them with the [MCP server](/docs/ai/mcp-server).

`link` writes `.authdog/project.json`:

```json
{
  "schemaVersion": 1,
  "tenantId": "…",
  "applicationId": "…",
  "environmentId": "…",
  "apiOrigin": "https://api.authdog.com",
  "identityOrigin": "https://identity.authdog.com",
  "linkedAt": "2026-10-09T00:00:00Z"
}
```

The file holds ids and origins only. It has no secrets, so you can commit it and everyone on the team gets the same link. `authdog unlink` removes the file and leaves your session alone.

## What init writes

`init` reads `package.json` and `pyproject.toml` to pick a framework. Pass `--framework` to choose one yourself.

| Framework | Package it installs | Env vars it writes | File it creates |
| --- | --- | --- | --- |
| `nextjs` | `@authdog/nextjs` | `NEXT_PUBLIC_PK_AUTHDOG`, `NEXT_PUBLIC_AUTHDOG_CLIENT_ID` | `app/authdog-provider.tsx` |
| `react` | `@authdog/react` | `PK_AUTHDOG`, `AUTHDOG_CLIENT_ID` | None |
| `javascript` | `@authdog/javascript` | `PK_AUTHDOG`, `AUTHDOG_CLIENT_ID` | None |
| `express` | `@authdog/express` | `PK_AUTHDOG`, `AUTHDOG_CLIENT_ID` | `authdog.express.ts` |
| `fastapi` | `authdog` (Python) | `PK_AUTHDOG`, `AUTHDOG_CLIENT_ID` | None |

Three rules keep it from damaging a repo you already have:

- Env vars go to `.env.local` unless you pass `--env-file`. A key that is already in the file is left as it is.
- An integration file is created only when it does not exist. An existing file is reported as `skip-exists`.
- The client id line is written only when the environment has an OIDC client.

The package manager comes from the lockfile: `bun.lock`, then `pnpm-lock.yaml`, then `yarn.lock`, otherwise npm. Python projects use uv when `uv.lock` is present, otherwise pip.

The values come from the same SDK config the console shows. `PK_AUTHDOG` is the environment public key (`pk_...`). It is publishable. `AUTHDOG_CLIENT_ID` is the OIDC client id, which is a different value.

### Next.js

The [Next.js quickstart](/docs/quickstarts?sdk=nextjs) uses the `@authdog/nextjs-app` package and reads the public key twice, as `NEXT_PUBLIC_PK_AUTHDOG` in the browser and `PK_AUTHDOG` in server middleware. `init` installs a different package name and writes only the `NEXT_PUBLIC_` copy. Until those match, let `init` do the linking and install the package yourself:

```bash
authdog init --framework nextjs --skip-install
npm install @authdog/nextjs-app
```

Then add `PK_AUTHDOG` to `.env.local` with the same value as `NEXT_PUBLIC_PK_AUTHDOG`.

## Global options

These work on every command and can go anywhere on the command line.

| Option | What it does |
| --- | --- |
| `--json`, `-o json` | Print one JSON document instead of text |
| `--non-interactive` | Fail instead of prompting |
| `--yes` | Accept defaults, and confirm commands that ask for consent |
| `--api-origin <URL>` | API base URL. Default `https://api.authdog.com` |
| `--project-file <PATH>` | Link manifest. Default `.authdog/project.json` |
| `-h`, `--help` | Print help |
| `-V`, `--version` | Print the version |

## Environment variables

| Variable | Purpose |
| --- | --- |
| `AUTHDOG_CONFIG_DIR` | Directory for `credentials.json` |
| `AUTHDOG_API_ORIGIN` | API base URL. Same as `--api-origin` |
| `AUTHDOG_IDENTITY_ORIGIN` | Identity host used for sign-in. Default `https://identity.authdog.com` |
| `AUTHDOG_CONSOLE_ENVIRONMENT_ID` | Environment that `login` signs in to. Set it only when you point the CLI at another Authdog deployment |

## Exit codes

| Code | Meaning |
| --- | --- |
| `0` | Success |
| `1` | Unexpected error |
| `2` | Usage or validation error |
| `3` | Not signed in, or the session expired |
| `4` | The API returned an error |

## Release status

The installer delivers the newest published release, which is `0.1.0-beta.3`. This documentation follows the `main` branch of the CLI repository. These parts are on `main` and are not in `0.1.0-beta.3`:

| Command | In `0.1.0-beta.3` |
| --- | --- |
| `api` | Not available |
| `agent onboard` | Not available |
| `mcp install --client`, `mcp install --all` | Cursor only |
| `mcp uninstall` | Accepted, removes nothing |
| `config diff` | Placeholder output |
| `webhooks listen --tunnel` | Not available |
| `impersonate revoke --grant-id` | Not available |
| `init --pm` | Not available. The lockfile decides |

Run `authdog --help` to see what your binary supports. To get the newer commands before the next release, build from source with Zig 0.16: `zig build -Doptimize=ReleaseSafe`.

## Next steps

- [Command reference](/docs/cli/commands): every command and flag.
- [CI and coding agents](/docs/cli/automation): JSON output, non-interactive runs, and MCP registration.
- [Quickstarts](/docs/quickstarts): finish the integration for your framework.
