verdictan doctor

verdictan doctor runs four checks on your local setup and the API, and reports ok, warn, or fail for each. Run it after you install the CLI, after you change the API URL or profile, or when a managed gateway does not start.

Run a diagnostic check

Run the command in the directory that contains your policy-config.yaml:

verdictan doctor

The command always runs all four checks, in the same order, and then prints a summary:

  ✓ api_connectivity: API reachable at https://api.verdictan.com
  ✓ config_file: valid YAML at policy-config.yaml
  ✓ state_directory: state directory writable at /home/user/.verdictan/supervisor
  ! proxy_liveness: no proxy instances registered

All checks passed.

Each line starts with ✓ for ok, ! for warn, or ✗ for fail. A warning does not make the command fail. Read each warning and decide if it applies to your setup. For example, no proxy instances registered is expected when you run a gateway without the local supervisor. It does not mean that your gateway listener is stopped.

A clean result does not prove that a model request can complete. Send a test request, as in the quickstart, to check the full path.

Usage

verdictan doctor [--config <path>] [--api-url <url>] [--profile <name>] [--state-dir <path>] [--json]

Options

Flag	Description
--config <path>	File for the config_file check. The default is policy-config.yaml in the working directory. The command also reads this file as the CLI config file for the api_connectivity check.
--api-url <url>	API base URL for the api_connectivity check.
--profile <name>	Profile that supplies the API URL and the stored session. The default is default.
--state-dir <path>	Directory for the state_directory and proxy_liveness checks. The default is ~/.verdictan/supervisor.
--json	Print the results as a JSON array. Each item has name, status, and message.

Checks

Check	What it does	warn when	fail when
api_connectivity	Calls GET /v1/health on the resolved API URL.	No API credential is configured. The command skips the request.	The CLI config does not resolve, or the request fails.
config_file	Reads the file and parses it as YAML.	The file does not exist.	The file cannot be read, or it is not valid YAML.
state_directory	Writes a .doctor-probe file in the state directory, then deletes it.	HOME is not set, or the directory does not exist.	The path is not a directory, or the command cannot write to it.
proxy_liveness	Reads the local supervisor state and counts instances with the running lifecycle.	There is no supervisor state, no registered instance, or no running instance.	Never.

The api_connectivity check looks for a credential in VERDICTAN_API_TOKEN, the CLI config file, and the stored profile session. It does not check that the credential is valid. The API serves /v1/health without authentication, so ok only shows that the API is reachable. Run verdictan auth whoami to check the credential.

The config_file check parses YAML syntax only. It does not check the policy schema. Use verdictan config validate or verdictan policy lint for that.

The proxy_liveness check reads supervisor records. It does not send a request to a gateway listener. Its message has the form <running>/<total> proxy instances running.

Examples

# Run the checks for the default profile
verdictan doctor

# Check a config file in another directory and print JSON
verdictan doctor --config ./configs/policy-config.yaml --json

# Check a different supervisor state directory
verdictan doctor --state-dir /srv/verdictan/supervisor

JSON output for the first example, without a credential and without a supervisor state directory:

[
  {
    "name": "api_connectivity",
    "status": "warn",
    "message": "no API token configured; skipping connectivity check"
  },
  {
    "name": "config_file",
    "status": "ok",
    "message": "valid YAML at policy-config.yaml"
  },
  {
    "name": "state_directory",
    "status": "warn",
    "message": "state directory does not exist: /home/user/.verdictan/supervisor"
  },
  {
    "name": "proxy_liveness",
    "status": "warn",
    "message": "no proxy instances registered"
  }
]

Limits and failure behavior

• In text mode, when one or more checks have the fail status, the command prints Some checks failed. Review the output above. It then stops with Error: one or more required checks failed and exit code 2.
• Warnings do not change the exit code.
• With --json, the command exits with 0 even when a check fails. Read the status field of each item in your automation.
• --config has two uses. A path that does not exist gives warn for config_file, and fail for api_connectivity with failed to resolve config: ... failed to read config file <path>. A file with invalid YAML fails both checks.
• The command does not accept --api-token. Set VERDICTAN_API_TOKEN, or sign in with verdictan auth login.

Next steps

• Troubleshooting: find the cause of a failed check.
• verdictan auth: sign in, and check the identity when api_connectivity warns.
• verdictan config validate: validate the config schema after the YAML check passes.
• verdictan gateway run: start a local gateway.