Authdog

CLI in CI and agents

Last updated Nov 17, 2026
View as Markdown

The CLI is built to be driven by scripts and coding agents as well as by people. Every command takes the same global options, prints one JSON document on request, and reports failure through its exit code. This page covers the parts that matter when nobody is at the keyboard. Commands and flags are in the command reference.

Stable output

Add --json (or -o json) to any command. The command prints one JSON document to stdout. Every document carries schemaVersion and ok.

authdog link --json
{
  "schemaVersion": 1,
  "ok": true,
  "projectFile": ".authdog/project.json",
  "tenantId": "…",
  "applicationId": "…",
  "environmentId": "…"
}

A failure has the same shape, with the reason in error:

{
  "schemaVersion": 1,
  "ok": false,
  "error": "multiple tenants; pass --tenant-id"
}

In text mode, errors go to stderr with an error: prefix and stdout stays empty. Parse stdout in JSON mode and branch on the exit code.

Code Meaning What a script should do
0 Success Continue
1 Unexpected error Stop and surface stderr
2 Usage or validation error Fix the arguments. Retrying will not help
3 Not signed in, or the session expired A person has to run authdog login
4 The API returned an error Read the body. Retry only when it is transient

Run without prompts

--non-interactive makes a command fail instead of asking a question. Pass everything it would have asked for:

authdog init \
  --non-interactive \
  --framework express \
  --pm npm \
  --json

init links the directory first when it is not linked. In a job, link explicitly so the target is never guessed:

authdog link \
  --tenant-id "$AUTHDOG_TENANT_ID" \
  --application-id "$AUTHDOG_APPLICATION_ID" \
  --environment-id "$AUTHDOG_ENVIRONMENT_ID" \
  --non-interactive

Or commit .authdog/project.json and skip the step. The file has no secrets.

Two more rules apply in non-interactive runs:

  • init fails when it cannot detect the framework. Pass --framework.
  • impersonate requires --reason.

Sessions in CI

authdog login needs a browser on the same machine, because the redirect lands on 127.0.0.1. There is no token flag and no headless login, and a session is not refreshed once it expires. That shapes what works in a pipeline:

  • Commands with no session work anywhere. webhooks verify, mcp install, doctor, unlink, and --help need no login.
  • Runners you control can reuse a session. Sign in once on the machine, and point jobs at that directory with AUTHDOG_CONFIG_DIR. When the session expires, commands exit with code 3 until someone signs in again.
  • Hosted, short-lived runners should call the API directly. Use a scoped token with the REST API for provisioning and config. Machine identity explains which kind of token fits. The CLI session is a person's session and is the wrong credential for an unattended job.

Keep AUTHDOG_CONFIG_DIR out of the repository and out of build artifacts. credentials.json is a bearer credential for your account.

export AUTHDOG_CONFIG_DIR="$HOME/.authdog-ci"
authdog status --json

Review config changes in a pull request

config pull writes .authdog/config.json. Commit it, and a change to redirect URIs or session settings becomes a diff someone can review.

authdog config pull
git add .authdog/config.json

In the pipeline, check that the file still matches the environment, and preview what a merge would apply:

authdog config diff --json
authdog config patch --dry-run --json

config diff sets matches to false when a section drifted. It still exits 0, so test the field. config patch applies sessionConfig and redirectUris only, and refuses a file that contains a secret.

Give a coding agent access

Two things help an agent set up Authdog on its own: the CLI for the repository, and the MCP server for the account.

authdog mcp install --client claude
authdog doctor --mcp

mcp install writes the server URL into the agent's config. The agent signs in through the browser on first use, as you. The CLI writes no token. See Authdog MCP server for the tools and the rules an agent should follow.

A setup an agent can run end to end, once you have signed in:

authdog whoami --json
authdog link --tenant-id <uuid> --application-id <uuid> --environment-id <uuid> --json
authdog init --non-interactive --framework express --pm npm --dry-run --json
authdog init --non-interactive --framework express --pm npm --json
authdog doctor --json

Tell the agent to run the --dry-run step and show you the plan before the real one. init never overwrites an existing env key or integration file, so a second run is safe.

Things to keep away from an agent's context:

  • The contents of credentials.json. No command prints it, and the agent has no reason to read it.
  • Secrets printed once by agent rp-init and agent onboard. Run those yourself, or have the process that needs the secret read it from the environment.
  • authdog api output is redacted, but the session behind it can do anything your account can. Treat a mutation through api like a mutation in the console, and have the agent ask first.

Check a machine before a run

doctor is the cheap first step in a script. It needs no session. In JSON mode it prints a top-level ok, which is false when any check failed, and a checks array with name, ok, and detail for each one.

authdog doctor --json

Read the credentials and userinfo rows to tell a missing or expired session from a network problem before the real commands run.

Learn more