CLI

The tracevault CLI captures AI session traces, streams them to the server as they happen, and verifies commit compliance.

Installation

# Via Cargo
cargo install tracevault-cli

# Via Homebrew
brew install softwaremill/tracevault/tracevault

Quick Start

1. Log in

Authenticate with your TraceVault server using the device authorization flow:

tracevault login --server-url https://your-server.example.com

The CLI prints an authentication URL in a banner and attempts to open it in your default browser. Approve the device on the opened page; the CLI is polling the server and finishes automatically once it sees the approval.

Credentials are saved to ~/.tracevault/credentials.json.

Running in Docker / CI / remote SSH

In a headless environment there's no browser to open. The CLI detects this automatically (Docker via /.dockerenv, CI via CI / GITHUB_ACTIONS, Linux without DISPLAY / WAYLAND_DISPLAY) and skips the auto-open step — just copy the URL from the banner into a browser on your workstation.

You can also force that behaviour explicitly:

# flag form
tracevault login --server-url https://your-server.example.com --no-browser

# or env var, e.g. baked into a Dockerfile
export TRACEVAULT_NO_BROWSER=1
tracevault login --server-url https://your-server.example.com

For fully unattended environments (long-lived CI jobs, container bootstrapping), prefer an API key over the interactive device flow:

export TRACEVAULT_SERVER_URL=https://your-server.example.com
export TRACEVAULT_API_KEY=your-api-key

2. Initialize a repository

Run this in any Git repository you want to trace:

tracevault init

This creates a .tracevault/ directory, installs Claude Code hooks, and sets up git pre-push and post-commit hooks. If you're authenticated, it also registers the repository with the server.

You can pass the server URL directly if not yet logged in:

tracevault init --server-url https://your-server.example.com

Choosing where Claude Code hooks are installed

By default, hooks are written to .claude/settings.json (the shared file your team typically commits). If you'd rather keep TraceVault hooks personal, install them into .claude/settings.local.json instead:

tracevault init --claude-settings local

When --claude-settings is omitted, tracevault init prompts you interactively (if running on a terminal) and falls back to shared in non-interactive environments like CI. The .gitignore entry is adjusted accordingly so a committed settings.json is never accidentally ignored when you choose local.

3. Work normally

Once initialized, TraceVault works in the background. AI coding sessions are captured automatically via hooks. Commits are pushed to the server via the post-commit hook. Before each git push, policies are checked automatically via the pre-push hook.

4. Verify commits

Check that commits are registered and cryptographically sealed on the server:

# Verify specific commits
tracevault verify --commits abc1234,def5678

# Verify a range
tracevault verify --range abc1234..def5678

Verify shows the policy check result, signature status, and chain integrity for each commit. Exits with code 1 if any commit fails verification — useful for CI/CD gates.

Commands