Skip to content
butverify docs
← butverify.dev

CLI commands

This file is generated from the shared bv command metadata used by CLI handlers and help. Run task docs:generate after changing the CLI surface.

The bv CLI is a single Go binary. It supports the global flags below and the subcommands that follow.

Global flags

  • --json — emit a single JSON document on stdout instead of human-readable text.
  • --api-url URL — override the control-plane endpoint.
  • --token TOK — override the bearer token.
  • --help, -h — show usage.
  • --version, -v — print the CLI version.

bv login [--api-url URL] [--gh-token TOK] [--token TOK]

Resolve and persist a butverify installation token.

Default flow: exchange a GitHub user token via POST /v1/auth/login. Token sources are —gh-token, GH_TOKEN, GITHUB_TOKEN, the gh CLI, or a TTY prompt.

Direct flow: pass an installation token via —token, BV_TOKEN, the global —token flag, or piped stdin to skip the exchange.

Flags:

  • --api-url URL — control-plane base URL.
  • --gh-token TOK — GitHub user token for the exchange flow.
  • --token TOK — butverify installation token for the direct-token flow.

bv logout

Clear saved authentication and switch default mode to local.

bv mode [local|remote]

Print or set the default publish mode.

Fresh installs default to local. A successful bv login switches the default to remote.

bv push [--mode local|remote] [--upload-id ID] [--ttl-seconds N] [--image-quality N] [--include-hidden] [--skip-gitleaks-check] <dir>

Bundle a directory and publish it in local or remote mode.

Local mode serves the filtered publish bundle on 127.0.0.1 until interrupted.

Remote mode uploads a tar bundle as a new private site. Pass —upload-id to retry the same logical upload idempotently.

Image optimization recompresses JPEGs with —image-quality and recompresses PNGs losslessly when smaller. Persist a default by setting image_quality in the bv config JSON.

Flags:

  • --mode local|remote — override the configured publish mode.
  • --upload-id ID — explicit upload_id for idempotent retry.
  • --ttl-seconds N — site TTL in seconds; 0 uses the server default.
  • --image-quality N — image optimization quality; JPEG uses this value and PNG is recompressed losslessly when smaller; 0 uses config/default.
  • --include-hidden — include dot-files in the bundle.
  • --skip-gitleaks-check — skip the pre-upload gitleaks secret scan.

bv ls [--expired]

List sites for the authenticated tenant.

By default, expired sites are hidden. Pass —expired to include them.

The EXPIRES column shows each site’s expiry as an absolute timestamp in the user’s local timezone, plus a humanized magnitude in parentheses. Pinned sites and sites without an expiry render as an em dash.

Flags:

  • --expired — also include expired sites in the listing.

bv rm <site-id>

Soft-delete a site.

bv cat <site-id> <path>

Print a single file from a site to stdout.

bv get <site-id> <dest>

Download a site’s files into a destination directory.

bv manifest <site-id>

Print the site’s manifest.json.

bv pin <site-id>

Pin a site to disable TTL-based expiry.

bv unpin <site-id>

Unpin a site and re-stamp the default TTL.

bv report --from <out.json|-> [--out DIR] [--push] [--upload-id ID] [--ttl-seconds N] [--image-quality N] [--mode local|remote]

Render a static report site from JSON.

Without —push, the rendered site is written to —out or ./bv-report-out. With —push, the rendered directory is published through the standard push flow.

Image optimization recompresses JPEGs with —image-quality and recompresses PNGs losslessly when smaller. Persist a default by setting image_quality in the bv config JSON.

Flags:

  • --from PATH|- — input JSON file or stdin.
  • --out DIR — output directory.
  • --push — after rendering, push the directory as a new site.
  • --upload-id ID — explicit upload_id for idempotent —push retry.
  • --ttl-seconds N — site TTL in seconds; 0 uses the server default.
  • --image-quality N — image optimization quality; JPEG uses this value and PNG is recompressed losslessly when smaller; 0 uses config/default.
  • --mode local|remote — publish mode for —push.

bv dashboard --from <data.csv|-> [--out DIR] [--title T] [--subtitle T] [--max-table-rows N] [--push] [--upload-id ID] [--ttl-seconds N] [--image-quality N] [--mode local|remote]

Render a static dashboard site from CSV.

With —push, image optimization recompresses JPEGs with —image-quality and recompresses PNGs losslessly when smaller. Persist a default by setting image_quality in the bv config JSON.

Flags:

  • --from PATH|- — input CSV file or stdin.
  • --out DIR — output directory.
  • --title T — page title.
  • --subtitle T — page subtitle.
  • --max-table-rows N — cap rows shown in the HTML table; 0 means no cap.
  • --push — after rendering, push the directory as a new site.
  • --upload-id ID — explicit upload_id for idempotent —push retry.
  • --ttl-seconds N — site TTL in seconds; 0 uses the server default.
  • --image-quality N — image optimization quality; JPEG uses this value and PNG is recompressed losslessly when smaller; 0 uses config/default.
  • --mode local|remote — publish mode for —push.

bv evidence (--schema | --from <evidence.json|-> [--out DIR] [--push] [--upload-id ID] [--ttl-seconds N] [--image-quality N] [--mode local|remote])

Render a static evidence/gallery site from JSON.

Use —schema to print the JSON Schema for the input without rendering.

Manifest metadata may include issue_url, issue_id, and issue_title at the top level for the work-management item the whole gallery proves, or under an individual item when a capture maps to a specific Jira/Linear/GitHub issue.

Rendered evidence pages include a viewer-side stacked/carousel layout switcher.

With —push, image optimization recompresses JPEGs with —image-quality and recompresses PNGs losslessly when smaller. Persist a default by setting image_quality in the bv config JSON.

Flags:

  • --from PATH|- — input JSON file or stdin.
  • --out DIR — output directory.
  • --push — after rendering, push the directory as a new site.
  • --schema — print the JSON Schema for the evidence input and exit.
  • --upload-id ID — explicit upload_id for idempotent —push retry.
  • --ttl-seconds N — site TTL in seconds; 0 uses the server default.
  • --image-quality N — image optimization quality; JPEG uses this value and PNG is recompressed losslessly when smaller; 0 uses config/default.
  • --mode local|remote — publish mode for —push.
  • --enable-reviews — opt the site into the review/annotation system (paid plan required).

bv agent-init [--project] [--force] [--uninstall] [--enable-hook|--no-hook]

Install the /butverify agent skills for the current agent environment.

v1 installs the Claude Code /butverify:prove-it and /butverify:review skills, plus a deprecated /butverify alias. Future versions may install additional skills, hooks, or MCP servers.

Flags:

  • --project — install into ./.claude/skills/butverify/ instead of $HOME/.claude/skills/butverify/.
  • --force — overwrite an existing install.
  • --uninstall — remove the deterministic install file set.
  • --enable-hook — install Claude Code SessionStart and Stop hooks that surface unacknowledged reviews (skip the TTY prompt).
  • --no-hook — skip hook installation regardless of TTY state.

Examples:

  • bv agent-init
  • bv agent-init --project

bv install-skill [--project] [--force] [--uninstall] [--enable-hook|--no-hook] <agent>

Install the /butverify agent skills (prove-it + review).

Supported agent in v1: claude.

Installs three skill files under /.claude/skills/butverify/: SKILL.md (deprecated alias), prove-it/SKILL.md, review/SKILL.md.

On a TTY, prompts to enable session-start and session-end hooks that surface unacknowledged reviews. —enable-hook forces yes (useful for CI); —no-hook forces no.

Flags:

  • --project — install into ./.claude/skills// instead of $HOME/.claude/skills//.
  • --force — overwrite an existing install.
  • --uninstall — remove the deterministic install file set.
  • --enable-hook — install Claude Code SessionStart and Stop hooks that surface unacknowledged reviews (skip the TTY prompt).
  • --no-hook — skip hook installation regardless of TTY state.

Examples:

  • bv install-skill claude
  • bv install-skill claude --project
  • bv install-skill claude --enable-hook

bv review <list|get|acknowledge|request> [args...]

Manage reviews on review-enabled evidence sites.

bv review list [—site ] [—unacknowledged] [—format json|ids] — list reviews for the calling tenant.

bv review get — print a single review with all annotations.

bv review acknowledge — mark a review acknowledged (idempotent).

bv review request —to — invite a GitHub user to review the site.

Examples:

  • bv review list --unacknowledged
  • bv review list --unacknowledged --format=ids
  • bv review get rev_abc
  • bv review acknowledge rev_abc
  • bv review request abcd1234 --to ryanh

bv whoami

Print the resolved tenant for the configured token.

bv version

Print the CLI version.

Exit codes

codemeaning
0success
1API or runtime error
2invalid arguments