Authdog

CLI command reference

Last updated Nov 17, 2026
View as Markdown

Every authdog command, grouped by the job it does. Install and sign-in are covered in the CLI overview. 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.

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

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

authdog logout

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

status

authdog status

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

whoami

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

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.

authdog unlink

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

init

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.

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

authdog config pull

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

config diff

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

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

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

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.

Support and go-live

impersonate

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.

deploy status

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

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

authdog mcp install
authdog mcp install --client claude
authdog mcp install --all

Registers the Authdog 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

authdog mcp list

Prints the config path for each client.

mcp uninstall

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 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

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.

Any API route

api

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.

Learn more