Authdog

Authdog CLI

Last updated Nov 17, 2026
View as Markdown

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.

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.

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

On Windows, in 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:

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:

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.

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:

authdog init --dry-run

init links to a project and environment that already exist. Create them in the console first, or through the 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.

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

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.

link writes .authdog/project.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 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:

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

Learn more