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 \
--jsoninit 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-interactiveOr commit .authdog/project.json and skip the step. The file has no secrets.
Two more rules apply in non-interactive runs:
initfails when it cannot detect the framework. Pass--framework.impersonaterequires--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--helpneed 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 code3until 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 --jsonReview 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.jsonIn 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 --jsonconfig 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 --mcpmcp 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 --jsonTell 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-initandagent onboard. Run those yourself, or have the process that needs the secret read it from the environment. authdog apioutput is redacted, but the session behind it can do anything your account can. Treat a mutation throughapilike 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 --jsonRead the credentials and userinfo rows to tell a missing or expired session from a network problem before the real commands run.