CLI configuration

When you run a server command (status, authorize, query, policy, or fact), the Verdict CLI resolves the target instance URL and API key from command-line flags, environment variables, saved connection profiles, and per-project configuration.

To save a reusable connection profile and bind it to your current project directory, run verdict profile add followed by verdict profile use:

verdict profile add development --endpoint http://localhost:4891 --no-auth
verdict profile use development --project
verdict config show --json

Saving a profile with profile add records its endpoint and credentials on disk, while profile use activates it (either for the current project with --project, or as your global default).

• Supplying an API key: For an authenticated server, omit --no-auth to enter the key at the interactive prompt, or pass --api-key-stdin to read the key from standard input. When running profile add --json, you must pass either --api-key-stdin or --no-auth.
• Inspecting the active connection: Run verdict config show at any time to see the resolved profile, instance URL, and the source of each setting. It reports whether an API key is present without printing the secret value.

Precedence

When multiple configuration sources are present, the CLI resolves each setting independently from highest to lowest priority:

Setting	Resolution order, highest priority first
Profile	--profile, VERDICT_PROFILE, project selection (.verdict/profile.json), global default profile
Instance URL	--endpoint (or --host), VERDICT_HOST, selected profile URL, http://localhost:4891
API key	VERDICT_API_KEY, --api-key, selected profile credential when its normalized URL matches the effective instance URL

Keep these resolution rules in mind when combining flags, environment variables, and profiles:

• Endpoint flags: If both --endpoint and --host are passed, --endpoint wins.
• Explicit profile selection: Passing --profile or setting VERDICT_PROFILE bypasses .verdict/profile.json discovery. Selecting a profile name that does not exist fails immediately rather than falling back to another profile.
• URL-scoped credentials: A profile’s stored API key is bound to its full normalized instance URL (including any path prefix). If you override the URL with --endpoint or VERDICT_HOST to point to a different origin or path, the CLI will not forward the profile’s stored API key to that new URL.
• Policy publication config: verdict policy publish can also use the server.profile field from its project configuration file when --profile, VERDICT_PROFILE, and --local are omitted. Because verdict config show evaluates only its own command invocation and does not load the policy publication file, pass explicit connection flags when you need both commands to target the same profile.

Local connections

Passing --local targets http://localhost:4891 directly without reading saved profiles or environment credentials (VERDICT_PROFILE, VERDICT_HOST, VERDICT_API_KEY).

--local cannot be combined with --endpoint, --host, or --profile. You can still pass an explicit --api-key flag alongside --local when testing a local server started with API key authentication.

Stored configuration

Global configuration directory

The CLI stores saved profiles and credentials in VERDICT_CONFIG_DIR when set. Otherwise, it uses the platform default:

• macOS and Linux: $XDG_CONFIG_HOME/verdict, or ~/.config/verdict when XDG_CONFIG_HOME is unset.
• Windows: %APPDATA%/verdict, or ~/AppData/Roaming/verdict as a fallback.

Inside that directory, the CLI maintains two files:

• config.json stores profile names, endpoint URLs, credential references, and the global default profile name.
• credentials.json stores the referenced API keys on disk (not in an operating-system keychain). Profile updates create the configuration directory with mode 0700 and both JSON files with mode 0600.

Project profile selection

Per-project profile selection is stored in .verdict/profile.json. When looking for a project profile, the CLI walks upward from the current working directory and stops after checking a Git repository root, your home directory, or the filesystem root.

• verdict profile use <name> --project updates the nearest .verdict/profile.json (or creates one at the project root) and adds /profile.json to .verdict/.gitignore so local profile choices are not committed by default.
• verdict profile unset --project removes the project selection.
• Omitting --project with profile use or profile unset updates the global default profile in config.json.
• verdict profile delete <name> deletes the profile, removes its stored credential, and clears the global default if it matched that profile. Any .verdict/profile.json file that still references a deleted profile must be updated with profile use --project or cleared with profile unset --project.

See the profile commands reference for command flags and JSON output schemas, and the configuration source for the implementation of these resolution rules.