Skip to content

Configuring CLI Targets

The Verdict CLI is used both for local policy development and for administering live Verdict instances (status, policy, fact, authorize, query). You can point server commands at a target instance using local defaults, saved connection profiles, per-project bindings, environment variables, or command-line flags.

Local development

Section titled “Local development”

When no profile or environment variable is active, server commands connect to http://localhost:4891 by default:

verdict status

If you have an active profile or environment variables configured for another environment, pass --local to force a command to target http://localhost:4891:

verdict policy publish policy.vd --local
verdict authorize User:alice read Document:handbook --local

Passing --local ignores saved profiles, .verdict/profile.json, and environment variables (VERDICT_PROFILE, VERDICT_HOST, VERDICT_API_KEY). --local cannot be combined with --profile or --endpoint (or --host), though you can still pass --api-key if your local server enforces authentication.

Profiles and project bindings

Section titled “Profiles and project bindings”

For servers you connect to regularly, save named connection profiles in your user configuration with verdict profile add:

# Unauthenticated local or dev server
verdict profile add development --endpoint http://localhost:4891 --no-auth


# Authenticated server (prompts interactively for the API key)
verdict profile add staging --endpoint https://verdict.staging.example.com


# Read the API key from standard input
printf '%s\n' "$STAGING_API_KEY" | verdict profile add staging \
  --endpoint https://verdict.staging.example.com \
  --api-key-stdin \
  --force

Selecting a project or global profile

Section titled “Selecting a project or global profile”

Saving a profile with profile add records its endpoint and credentials without changing the active target. Use verdict profile use to activate a profile either for your current repository or as your user-wide default:

# Bind the current repository to a profile (writes gitignored .verdict/profile.json)
verdict profile use development --project


# Or set a user-wide default profile across all directories
verdict profile use development

Running verdict profile use <name> --project writes the selection to .verdict/profile.json and adds /profile.json to .verdict/.gitignore so individual developer selections are not committed to version control.

For verdict policy publish, you can also set server.profile in verdict.config.json to pin a default publication profile when --profile, VERDICT_PROFILE, and --local are omitted.

One-off target overrides

Section titled “One-off target overrides”

To run a single command against a different saved profile, pass --profile <name>:

verdict status --profile staging

You can also pass --endpoint and --api-key directly on any server command:

verdict status --endpoint https://verdict.staging.example.com --api-key "$STAGING_API_KEY"

Stored profile credentials are bound to the profile’s normalized endpoint URL. If you override the URL with --endpoint or VERDICT_HOST, the CLI does not forward a stored profile API key to the new URL.

Environment variables and CI/CD

Section titled “Environment variables and CI/CD”

In non-interactive shells and CI/CD pipelines, configure the target server with VERDICT_HOST and VERDICT_API_KEY (or VERDICT_PROFILE when referencing a preconfigured profile):

export VERDICT_HOST="https://verdict.production.example.com"
export VERDICT_API_KEY="$PROD_VERDICT_API_KEY"


verdict policy publish policy.vd

VERDICT_HOST and VERDICT_API_KEY take precedence over project bindings and saved profile settings, allowing deployment jobs to run standard CLI commands without extra flags.

Inspecting the active target

Section titled “Inspecting the active target”

Run verdict config show at any time to verify which profile, endpoint, and credential source the CLI will use in the current directory:

verdict config show
Profile: development (project)
Endpoint: http://localhost:4891 (profile)
API key: none (none)
Configuration directory: /home/alice/.config/verdict
Project selection: /workspace/app/.verdict/profile.json

verdict config show reports whether an API key is configured (set or none) and which source won (flag, environment, project, default-profile, profile, local, default, or none) without printing secret values.

See CLI configuration for the full precedence table and on-disk storage contracts.

Next steps

Section titled “Next steps”