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 or .tar.gz file 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 found in code directories and is useful when VIV.md cannot be placed in the code directory itself. This file does not need to be named VIV.md.
--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.
--garrulous	Show all tool calls in the UI (default: only show the latest).
--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 or .tar.gz file 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 found in code directories.
--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.
--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 or .tar.gz file.
--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 found in code directories.
--garrulous	Show all tool calls in the UI (default: only show the latest).
--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.

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

See the MCP server setup section of the overview for more details.

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.

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

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

Export the current analysis to a Markdown file.

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.

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