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](/docs/cli/commands).

## Stable output

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

```bash
authdog link --json
```

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

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

```json
{
  "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:

```bash
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:

```bash
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](/docs/api) for provisioning and config. [Machine identity](/docs/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.

```bash
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.

```bash
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:

```bash
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.

```bash
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](/docs/ai/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:

```bash
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.

```bash
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.
