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 loginOpens 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 logoutDeletes credentials.json. It does not revoke the session on the server.
status
authdog statusReports whether a session is stored and where the credentials file lives. It makes no network call and prints no token.
whoami
authdog whoamiCalls 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
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
authdog unlinkRemoves .authdog/project.json. Your session stays.
init
authdog init
authdog init --framework nextjs --pm pnpm --env-file .env --dry-runDetects 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 pullWrites .authdog/config.json with four sections: sessionConfig, redirectUris, oidcClients, and webhooks. Secrets are redacted.
config diff
authdog config diffCompares 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 patchApplies 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/authdogWith 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 statusRead-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-inRuns 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 --allRegisters 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 listPrints the config path for each client.
mcp uninstall
authdog mcp uninstall --client cursor
authdog mcp uninstall --allRemoves 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> --pollRuns 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.--datatakes a JSON body and is allowed onPOST,PUT, andPATCH. - 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 includesclientSecret,signingSecret,access_token,refresh_token,token,secret, andpassword. - A
401exits with code3. Any other non-2xx response exits with code4after printing the redacted body.
The routes are listed in the API reference.