CLI reference

This is a complete reference for all Viv commands and flags.

Commands

viv submit

Begin a non-interactive debugging analysis. This is the primary command for analyzing a failing test case.

viv submit \
  --artifact-path <path> \
  --code-directory <path> \
  [options]

Flag	Description
--artifact-path, -a	(Required) Path to the logs directory from the failing test case.
--code-directory, -c	Path to a code directory. Can be specified multiple times for multiple code roots. Defaults to the current directory if no -c, -f, or -F flags are given.
--filelist, -f	Path to a VCS-style filelist (.f file) with paths resolved relative to the current working directory (or --filelist-cwd if specified). Can be specified multiple times.
--filelist-relative, -F	Path to a VCS-style filelist (.f file) with paths resolved relative to the filelist's own directory. Can be specified multiple times.
--filelist-cwd	Override the working directory used to resolve relative paths in -f/--filelist entries.
--filelist-path-map	Remap file path prefixes in filelists. Format: /old/path:/new/path. The first matching mapping wins. Can be specified multiple times. Requires -f or -F.
--viv-md	Path to explicit VIV.md file(s) for context (can be specified multiple times). This supplements any VIV.md auto-discovered in code directories and in ~/.viv/VIV.md, and is useful when VIV.md cannot be placed in the code directory itself. This file does not need to be named VIV.md.
--spec	Path to specification files or directories (PDF, markdown, text). Can be specified multiple times. Directories are recursively enumerated. Short navigational files (TOCs, indexes) are inlined into the agent's prompt.
--guidance, -g	Additional guidance text passed directly to the agent (e.g., a hint about where the bug might be).
--guidance-file	Path to a file containing guidance text.
--no-guidance	Skip the guidance prompt entirely.
--wave-server-logs <path>	Path to write waveform server (Rascal) logs for debugging.
--export-markdown	Path to write a Markdown-formatted report of the results.
--log-file, -l	Write analysis log to the given file (overwrites existing file; creates directories as needed).
--quiet / --no-quiet	Only show the latest tool call instead of all tool calls. Default: show all (i.e., --no-quiet). Can also be set via quiet in config.json.
--exit-on-finish / --no-exit-on-finish	Exit immediately after analysis completes instead of entering chat. Requires --log-file or --export-markdown so results are captured. Can also be set via exit_on_finish in config.json.
--effort <fast|balanced|thorough>	Reasoning effort mode. Controls how much the model "thinks" before responding. Overrides reasoning_effort in config.json. See Reasoning effort.
--lang <en|ko>	Output language for the bug description and fix steps. The agent loop itself still reasons in English to preserve reasoning quality; only the final summary artifacts switch language. Overrides language in config.json.
--debug-log <path>	Path to write an IP-scrubbed debug log for customer support diagnostics. Records tool calls, truncation events, and agent events with all user data redacted.
--max-timeout <seconds>	Maximum timeout in seconds for waveform server requests (default: 30). Increase for large waveform files in non-interactive mode. Values below 30 are clamped to 30.
--disable-lsp	Disable the SV language server (slang-server).
--verbose	Enable verbose output, including full configuration details.

viv swarm

Run a parallel multi-hypothesis investigation. Viv automatically generates 3–5 hypotheses about the failure (always covering RTL bugs, testbench bugs, and spec ambiguity), then spawns one investigator agent per hypothesis. After all investigators finish, a synthesizer reads their reports and produces a unified bug description and debugging narrative.

viv swarm \
  --artifact-path <path> \
  --code-directory <path> \
  [options]

Flag	Description
--artifact-path, -a	(Required) Path to the logs directory from the failing test case.
--code-directory, -c	Path to a code directory. Can be specified multiple times.
--filelist, -f	Path to a VCS-style filelist (.f file) with paths resolved relative to the current working directory (or --filelist-cwd if specified). Can be specified multiple times.
--filelist-relative, -F	Path to a VCS-style filelist (.f file) with paths resolved relative to the filelist's own directory. Can be specified multiple times.
--filelist-cwd	Override the working directory used to resolve relative paths in -f/--filelist entries.
--filelist-path-map	Remap file path prefixes in filelists. Format: /old/path:/new/path. The first matching mapping wins. Can be specified multiple times. Requires -f or -F.
--viv-md	Path to explicit VIV.md file(s) for context (can be specified multiple times). Supplements any VIV.md auto-discovered in code directories and ~/.viv/VIV.md.
--spec	Path to specification files or directories (PDF, markdown, text). Can be specified multiple times. Directories are recursively enumerated.
--guidance, -g	A hint about the failure. This becomes one of the hypotheses investigated.
--guidance-file	Path to a file containing guidance text.
--no-guidance	Skip the guidance prompt entirely.
--wave-server-logs <path>	Path to write waveform server (Rascal) logs for debugging.
--export-markdown	Path to write a Markdown-formatted report of the results.
--log-file, -l	Write analysis log to the given file (overwrites existing file; creates directories as needed).
--exit-on-finish / --no-exit-on-finish	Exit immediately after analysis completes instead of entering chat. Requires --log-file or --export-markdown. Can also be set via exit_on_finish in config.json.
--effort <fast|balanced|thorough>	Reasoning effort mode. Overrides reasoning_effort in config.json. See Reasoning effort.
--lang <en|ko>	Output language for the synthesized bug description and fix steps. Investigators and the synthesizer still reason in English; only the final summary artifacts switch language. Overrides language in config.json.
--debug-log <path>	Path to write an IP-scrubbed debug log for customer support diagnostics.
--max-timeout <seconds>	Maximum timeout in seconds for waveform server requests (default: 30). Increase for large waveform files.
--disable-lsp	Disable the SV language server (slang-server).
--verbose	Enable verbose output.

How it differs from viv submit:

• viv submit runs a single agent that investigates one path at a time.
• viv swarm runs 3–5 agents in parallel, each exploring a different hypothesis. This is more thorough but uses more API tokens.

The RTL investigator focuses primarily on design code, and the testbench investigator focuses primarily on testbench/scoreboard code, so the investigations are largely uncorrelated.

After the swarm finishes, the chat phase works the same as viv submit — you can ask follow-up questions, and the chat has access to all investigator findings.

viv chat

Start an interactive chat session with access to your code and artifacts, without running the automated analysis first. Useful for asking questions about your design or testbench directly.

viv chat \
  --artifact-path <path> \
  --code-directory <path> \
  [options]

Flag	Description
--artifact-path, -a	(Required) Path to the logs directory.
--code-directory, -c	Path to a code directory. Can be specified multiple times.
--filelist, -f	Path to a VCS-style filelist (.f file) with paths resolved relative to the current working directory (or --filelist-cwd). Can be specified multiple times.
--filelist-relative, -F	Path to a VCS-style filelist with paths resolved relative to the filelist's own directory. Can be specified multiple times.
--filelist-cwd	Override the working directory for resolving relative paths in -f/--filelist entries.
--filelist-path-map	Remap file path prefixes in filelists. Format: /old/path:/new/path. Can be specified multiple times. Requires -f or -F.
--viv-md	Path to explicit VIV.md file(s) for context (can be specified multiple times). Supplements any VIV.md auto-discovered in code directories and ~/.viv/VIV.md.
--quiet / --no-quiet	Only show the latest tool call instead of all tool calls. Default: show all.
--verbose	Enable verbose output.

viv history

Browse and resume previous debugging sessions. Opens an interactive list of past analyses, sorted by most recent. Select an entry to view its results and continue chatting with full conversation context.

viv history

Analysis results are saved automatically and can be browsed and resumed from this command.

viv init

Generate a VIV.md file for your project. This creates a markdown document describing your repository's structure, which helps Viv debug more efficiently.

viv init \
  --code-directory <path> \
  [options]

Flag	Description
--artifact-path, -a	Path to logs directory (helps Viv understand log file formats).
--code-directory, -c	Path to a code directory. Can be specified multiple times.
--verbose	Enable verbose output.

See Writing a VIV.md for guidance on getting the most out of VIV.md.

viv health

Check system health, including waveform reader availability and configuration status.

viv health [--json]

Flag	Description
--json	Output machine-readable JSON. Always exits with code 0 when this flag is set.

viv license

Manage your Viv license.

viv license info    # Show current license details
viv license add     # Interactively install a license

viv mcp

Manage Model Context Protocol (MCP) server connections. MCP servers provide Viv with access to third-party data sources during analysis. Both the current Streamable HTTP transport and the legacy HTTP+SSE transport are supported; viv mcp add auto-detects which one a given server speaks.

viv mcp add <server-url>      # Connect a new MCP server
viv mcp list                   # List connected servers (shows transport per server)
viv mcp remove <server-id>    # Disconnect a server

viv mcp add probes the server's transport (Streamable HTTP or legacy SSE) and persists the choice; you don't need to specify it. See the MCP server setup section of the overview for more details.

viv knowledge

Viv's project knowledge store persists across sessions, helping the agent remember specification file locations, block-to-spec mappings, and codebase facts. Viv's knowledge should work without much manual intervention. However, we provide the following commands to manage the knowledge store.

viv knowledge list                    # Summary table of all projects
viv knowledge list --project myproj   # Detailed table for a specific project
viv knowledge list -c /path/to/code   # Resolve project from directory, show details
viv knowledge list spec               # All projects, specs only (hides zero-count)
viv knowledge status                  # Show knowledge store health and counts
viv knowledge add-spec <path>         # Manually add a specification file
viv knowledge remove-spec <path|hash> # Remove a spec by file path or hash prefix
viv knowledge reset                   # Clear all knowledge for the current project

When run without --project, viv knowledge list shows a summary table of all projects with counts for specs, mappings, and facts. Use --project <name> to see a detailed table for a single project, with columns for ID, type, age, confidence, source (core/extended), and description. Passing -c <dir> without --project resolves the project from that directory.

remove-spec accepts either a file path or a hash prefix. If the hash prefix is ambiguous (matches multiple entries), Viv will ask you to provide more characters. When given a file path, Viv resolves the spec's absolute path and matches it by hash.

Relative paths passed to add-spec and remove-spec are resolved against the current working directory, not the project root. If your cwd at removal time differs from the cwd at insertion time, pass an absolute path — or, more conveniently, pass a hash prefix from viv knowledge list.

Both add-spec and remove-spec automatically detect the correct project by checking which project's known code roots contain the spec file. This means you can run these commands from any directory — you don't need to cd into the project first. The --project flag still takes precedence if specified, and Viv falls back to CWD-based detection if no project's roots match.

The knowledge store is enabled by default. See Knowledge store in the configuration reference for details and storage options.

viv version

Print the current Viv version.

viv version

viv help

Show help information and a list of available commands.

viv help

Global flags

These flags can be used with any command:

Flag	Description
--config <path>	Path to a config.json file (replaces $HOME/.viv/config.json).
--license <path>	Path to a license file (replaces $HOME/.viv/license).
--api-key <key>	API key value passed directly on the command line.
--api-key-file <path>	Path to a file containing the API key.
--theme <dark|light>	Color theme. Default: auto-detected from terminal.
--effort <fast|balanced|thorough>	Reasoning effort mode. Overrides reasoning_effort in config.json. See Reasoning effort.
--lang <en|ko>	Output language for the bug description and fix steps. Overrides language in config.json.
--project <name>	Explicit project name for the knowledge store. Overrides automatic detection from git remote.

note

--api-key and --api-key-file are mutually exclusive. Use one or the other, not both.

Interactive mode

Running viv with no arguments launches an interactive menu where you can select from available actions (Submit, Generate VIV.md, Manage MCP servers, etc.) and follow guided prompts.

viv

Chat phase

After viv submit or viv swarm completes, Viv enters an interactive chat phase where you can ask follow-up questions. You can also enter chat directly with viv chat.

Exiting chat

To exit the chat phase, type any of the following: exit, /exit, quit, /quit, :q, :quit, or :exit. You can also press Ctrl+C. (After viv submit or viv swarm, Esc from the chat input reopens the results viewer rather than exiting; use Ctrl+C to quit. In viv chat, where there are no results to return to, Esc still exits.)

Slash commands

During the chat phase (after viv submit completes, or in viv chat), you can type slash commands to trigger special actions.

/analyze [hypothesis]

Re-run the full debugging analysis on the same artifact and code directories, without leaving the current session. Optionally provide a hypothesis to steer the investigation.

/analyze
/analyze the issue might be in the write-back stage

Viv will show a confirmation prompt with the paths it will analyze. After you confirm, a fresh analysis runs and the conversation continues with the new findings. Previous analyses from the same session are summarized and passed to the new run so Viv avoids re-investigating the same ground.

/wave-explore

Open the waveform viewer for the current artifact.

/export [path]

Export the current analysis to a Markdown file. Optionally provide a file path; defaults to bug.md in the current directory.

/export
/export ./reports/analysis.md

If export_template is set in config.json, the export is formatted by the LLM according to your template. See the configuration reference for details.

Non-interactive usage

--exit-on-finish

Use --exit-on-finish to make Viv exit immediately after analysis completes, skipping the interactive results view and chat phase. This is useful for batch workflows where you want to run Viv from an interactive terminal but don't need the chat.

At least one output sink is required so that results are captured: --log-file (-l) or --export-markdown.

# Exit after analysis, saving results to a log file
viv submit -a ./logs -c ./rtl -l ./output.log --exit-on-finish

# Exit after analysis, saving a Markdown report
viv submit -a ./logs -c ./rtl --export-markdown ./report.md --exit-on-finish

You can set this as the default in config.json with "exit_on_finish": true, and override it per-run with --no-exit-on-finish.

Headless mode

When Viv detects that it is running in a non-interactive environment (i.e., stdin is not a TTY), it automatically switches to headless mode. This works for both viv submit and viv swarm, and is designed for CI/CD pipelines and scripted workflows.

Behavior

• Progress messages are written to stderr so they don't interfere with the report output.
• The final Markdown report is written to stdout.
• Viv exits with code 0 on success and 1 on failure.
• Interactive prompts (guidance, chat) are skipped. Use --guidance or --guidance-file to provide hints non-interactively.
• For viv swarm, hypothesis generation and per-investigator progress are logged to stderr.
• Use --log-file (-l) to capture the full analysis log to a file in addition to the stdout report.

Example: CI pipeline usage

# Run Viv in a CI pipeline, capturing the report
viv submit \
  --artifact-path ./test-logs \
  --code-directory ./rtl \
  --code-directory ./tb \
  --no-guidance \
  > bug-report.md 2>viv-progress.log

# Or pass guidance non-interactively
echo "The failure is related to the AXI write channel" | \
  viv submit \
    --artifact-path ./test-logs \
    --code-directory ./rtl

Example: swarm in CI

# Run a parallel investigation in CI
viv swarm \
  --artifact-path ./test-logs \
  --code-directory ./rtl \
  --code-directory ./tb \
  --no-guidance \
  > swarm-report.md 2>swarm-progress.log

Example: export alongside headless output

# Save the report to a file and also export Markdown
viv submit \
  --artifact-path ./test-logs \
  --code-directory ./rtl \
  --export-markdown ./report.md \
  --no-guidance \
  > /dev/null

Reasoning effort

The --effort flag controls how much reasoning the LLM performs at each step. This maps to the model's native reasoning/thinking mechanism (e.g., OpenAI's reasoning.effort, Claude's thinking budget). Each mode sets per-task reasoning levels tuned for a different speed/quality tradeoff.

Mode	Behavior
fast	Minimal reasoning across all tasks. Faster and cheaper, but may miss nuances in complex bugs.
balanced	Uses Viv's default reasoning levels for each task type. Good for most debugging tasks.
thorough	Maximum reasoning across all tasks. Best for complex multi-signal bugs, but slower and more expensive.

When no --effort flag is provided, Viv uses its built-in defaults for each internal task type (equivalent to balanced).

# Run a quick, cheaper analysis
viv submit --effort fast --artifact-path ./logs --code-directory ./rtl

# Run a thorough analysis for a complex bug
viv submit --effort thorough --artifact-path ./logs --code-directory ./rtl

# Override via config.json instead of the CLI flag
# See the configuration reference for details

The --effort flag takes priority over the reasoning_effort setting in config.json. See the configuration reference for the config-based alternative.