VeriProof CLI

Use the CLI to configure applications, manage application keys, check a deployment, inspect session evidence, test rules before release, and keep application definitions in source control. The CLI supports Managed SaaS and Customer-managed Azure.

Requirements

• Python 3.10 or later
• An active VeriProof customer account with CLI access

Install

Download the approved CLI from your customer portal. You do not need a GitLab account, package credential, or package-source URL.

1. Sign in to your VeriProof customer portal.
2. Open Tools and SDKs.
3. Choose VeriProof CLI. Customer Administrators see the CLI selected for them.
4. Select the CLI download shown for the approved version.
5. Choose PowerShell or Bash and run the install commands.
6. Open a new terminal.
7. Run the commands under Sign in and verify.

The portal downloads the approved veriproof-cli wheel. The shown pipx command keeps the CLI separate from application Python environments.

Confirm the installation:

veriproof --version
veriproof --help

The install commands add the CLI command to your terminal path. Opening a new terminal applies that change before you run veriproof.

Configure a deployment

Sign in and verify in Tools and SDKs already provides these commands with your current portal address. Do not enter an API or ingest URL.

veriproof profile add production https://my.veriproof.app
veriproof auth login
veriproof doctor

For Customer-managed Azure, use that deployment’s portal URL:

veriproof profile add enterprise https://veriproof.contoso.com
veriproof --profile enterprise auth login
veriproof --profile enterprise doctor

The CLI requires HTTPS. It reads the deployment’s public service addresses and OAuth settings from /.well-known/veriproof-configuration. The profile file contains no credentials.

profile add selects the saved profile. Use --profile NAME for one command, or set VERIPROOF_PROFILE for the current shell or automation process.

veriproof profile list
veriproof --profile enterprise profile show
veriproof --profile enterprise profile refresh

Run profile refresh after a deployment administrator changes a service address or OAuth registration. If its OAuth binding changed, the CLI clears the saved sign-in credential and asks you to sign in again.

Sign in

veriproof auth login opens the identity provider configured for the selected deployment. For a remote or headless terminal, use the OAuth device-code flow:

veriproof auth login --device-code --no-browser

Open the displayed portal URL in a browser, enter the short code, and approve access. Device-code sign-in does not open a callback listener on the terminal host.

For regular browser sign-in, the callback listener accepts one response on 127.0.0.1 and then closes. The browser confirms the selected profile. VeriProof stores the refresh credential in the operating-system credential store, not the profile file.

veriproof auth status
veriproof auth logout

auth status checks the deployment and shows your email, user ID, tenant, and role. A saved credential alone does not confirm an active sign-in.

Sign in from a pipeline

A pipeline signs in as a service principal instead of a person. Store its client ID and secret as pipeline secrets. The CLI requests a short-lived token for each command and stores nothing:

export VERIPROOF_CLIENT_ID="<service principal client ID>"
export VERIPROOF_CLIENT_SECRET="<client secret>"
veriproof --profile production policy test --application <APPLICATION_ID>

With a Microsoft Entra workload identity, set VERIPROOF_CLIENT_ASSERTION to the Entra access token instead of VERIPROOF_CLIENT_SECRET. A service principal acts with its own role and group scope.

Work with applications and evidence

veriproof init
veriproof apps list
veriproof apps list --all
veriproof apps get <APPLICATION_ID>
veriproof apps create "loan-review-agent" --environment production
veriproof keys list <APPLICATION_ID>
veriproof keys create <APPLICATION_ID>
veriproof keys create <APPLICATION_ID> --human-review-access
veriproof sessions list --application-id <APPLICATION_ID>
veriproof sessions list --application-id <APPLICATION_ID> --all
veriproof sessions get <SESSION_ID>
veriproof sessions export <SESSION_ID> --output evidence.zip

Application-key creation and rotation show a new secret once. Store it in your approved secret manager. Session export does not replace an existing file unless you pass --force.

Add --human-review-access to keys create or keys rotate to issue a key that can confirm the application outcome after human review. keys create --verified-outcomes issues a verifier key for independently verified business outcomes; the two options cannot be combined. Both need tenant key management permission (Administrator). Without it the command exits with code 4 and shows the server’s message. The output states whether the new key has human-review access.

veriproof init writes project configuration in the current folder. Review the generated file before you commit it. It does not store a sign-in credential or application key.

Rotate or revoke a key

Check the previous secret’s expiry before rotating a running application’s key. Coordinate the change so you can store the replacement and update every application instance within the available window.

veriproof keys rotate <APPLICATION_ID> <KEY_ID>
veriproof keys rotate <APPLICATION_ID> <KEY_ID> --human-review-access

The key ID stays the same. Do not revoke it after rotation; that would also disable the new secret. Revoke a key only when the application no longer needs it:

veriproof keys revoke <APPLICATION_ID> <KEY_ID>

Test rules before release

veriproof policy test replays an application’s or group’s saved rule tests against the current rules and, optionally, a candidate:

• the positive, negative, and boundary tests recorded when each rule’s readiness was checked;
• the saved rule test datasets of recorded sessions, for every rule the candidate changes.

veriproof policy test --application <APPLICATION_ID>
veriproof policy test --application <APPLICATION_ID> --candidate <RULE_DRAFT_ID> --fail-on-change
veriproof policy test --group claims --definition claims-group.json --junit results/rules.xml

Each result shows the rule, the test case, and the expected and actual outcome: Allow, Warn, Transform, Escalate, or Deny. A rule test expects the outcome it was written for. A recorded session expects what the current rule decides, so a change means the candidate would decide that session differently.

A run only reads rules and recorded sessions. It never changes a rule, a deployment, or enforcement. Runs are bounded; when a run stops early, the result says what it covered. You need policy workspace access to the application or group. The latest run appears with the application’s policy rules in the portal.

See Test rules in CI for GitHub Actions and Azure DevOps examples.

Export and import definitions

Keep an application’s or group’s governance definition in source control as a veriproof.configuration/v1 document:

veriproof config export --application <APPLICATION_ID> --out refund-assistant.json
veriproof config export --group <GROUP_ID> --out claims-group.json
veriproof config import refund-assistant.json --dry-run
veriproof config import refund-assistant.json

config export writes to standard output unless you pass --out, and doesn’t replace an existing file unless you pass --force. config import targets the application or group recorded in the document. Pass --application or --group to import it somewhere else.

Import prints each change by section. Rules are saved as drafts for a person to deploy. Changes that would start, stop, or replace enforcement are listed as needs_person, and production changes become approval_requested. The command exits with code 1 when a section failed or your role doesn’t permit it. See Service principals for what a document contains and how import applies it.

Verify exported evidence

To verify an exported evidence pack without calling the VeriProof API, first install the separate public veriproof-verify tool. Then run:

veriproof verify evidence.zip

See Verify exported evidence for signed downloads and platform instructions.

veriproof doctor is read-only. It checks local profile and credential configuration, then checks the selected deployment’s tenant proof provider and API health. JSON output labels each check as local or deployment.

Help, output, and exit codes

Run veriproof --help or veriproof COMMAND --help for command-specific arguments and options. Use veriproof --version to print the installed version.

Human-readable lists use named columns and preserve complete stable IDs. Use --json for structured output. The option can appear before or after a subcommand. JSON failures are written to standard error. Each error includes a stable category and code, whether a retry can help, the HTTP status when available, and a correlation ID. Keep that ID with your diagnostic notes. Remove credentials and evidence content before sharing those notes.

Credential safety

• Download the CLI only from Tools and SDKs in your VeriProof portal.
• Use VERIPROOF_ACCESS_TOKEN only with a short-lived token in controlled automation.
• Store VERIPROOF_CLIENT_SECRET in your pipeline’s secret store. Give each pipeline its own service principal, limited to the groups it manages.
• Customer-managed Azure deployments can enable workload identity. Set VERIPROOF_AZURE_WORKLOAD_TOKEN to a short-lived Azure access token. The CLI exchanges it for a tenant-bound VeriProof token and does not store either token.
• Do not put refresh credentials or application keys in the profile file.
• Review build logs when a command can return a new application-key secret.

Update or remove the CLI

Tools and SDKs always shows the approved CLI version. To update, open the page again, download the current package, and run its install command. pipx install --force replaces the installed CLI.

When retiring a workstation, sign out of each saved profile before removing it. Then uninstall the CLI:

veriproof --profile organization auth logout
veriproof profile remove organization
python -m pipx uninstall veriproof-cli

Replace organization with the profile name shown by veriproof profile list. Removing portal access prevents future downloads but does not remove installed files.

Shell completion

The CLI can generate completion scripts for Bash, Zsh, and Fish. Bash users can add this line to ~/.bashrc:

eval "$(_VERIPROOF_COMPLETE=bash_source veriproof)"

See Agent integration troubleshooting for sign-in, discovery, and connectivity errors.