User Guide

1. Installation

Windows users can download a ready-to-run desktop app — no Python install required. macOS, Linux, and developers who want to run from source can download the CLI source package.

1.1 Setup

Windows (.exe)

1. Double-click VerifiablyApp.exe. It opens a setup page in your browser.
2. Enter your licence key (from your trial or purchase email) and your LLM provider API key (BYOK), then optionally a folder or GitHub URL to start analysing immediately.

From source (.zip)

1. Unzip the downloaded verifiably-cli.zip archive.
2. Requires Python 3.10+. From the unzipped verifiably-cli folder, install the CLI into your environment:

3. Run verifiably init-config and enter your licence key (from your trial or purchase email) plus your own LLM provider API key (BYOK).
4. Analyse a codebase and open the results in your browser:

2. What Verifii Produces

Verifii analyses a code repository and produces a structured, sourced description of what the code actually does. The output is a set of expert views, each aimed at a different audience, plus a browsable documentation site. Every claim links to an exact file and line number.

3. Navigating Your Results

When you open a project, you land on the project hub. From there you can access all views: the six role views, the documentation sections, and the Q&A interface.

3.1 Role Views

Role views are the primary output of a Verifii analysis. Each one runs an agentic investigation — reading source files, following dependencies, and reasoning over the findings — then produces a structured report for a specific audience.

How to use it: Pick the role that matches your question. Each view is independently generated — the Security view reads actual source code before rating any finding; it does not just list claims.

3.2 Architecture

The Architecture section shows how the codebase is structured: which modules exist, how they depend on each other, and which files are most central. It includes a Mermaid dependency diagram generated directly from the import graph.

In-degree is the key metric — it counts how many other files import a given file. High in-degree means high blast radius. A change to a file with in-degree 12 affects 12 other modules. Verifii flags these as Zones of Pain.

How to use it: Use the Architecture view to understand risk before making changes, and to identify where to focus a refactor.

3.3 The Spec vs Reality Report

This is the most important section for closing the gap between what the documentation claims and what the code actually does. It compares a README or specification document against the code and produces a per-feature verdict.

Coverage score (e.g. ████████░░ 13/16): how many features from the spec have confirmed code implementations.

Three sub-sections within the report:

• Hidden Behaviours — things the code does that the spec never mentioned. Implicit engineering decisions: security contracts, edge-case handling, undocumented constraints.
• Security Observations — behaviours with security implications not in the spec. Undocumented security contracts sourced to file:line, rated HIGH / MEDIUM / LOW.
• Questions for the Engineering Team — open questions that Verifii cannot answer from code alone.

3.4 Q&A

From any project page you can ask free-form questions about the codebase — for example: "How does authentication work?" or "Where are database transactions handled?". Verifii runs an agentic search across the findings and source files and returns a sourced answer with file:line citations.

How to use it: Use Q&A for targeted lookups when you know the question but not where to look in the report.

4. Use Cases

Verifii is built for people who have been given a system to understand. These are the most common situations.

5. Deployment & Data Privacy

Where your code goes during analysis is the most important question to answer before adopting any code intelligence tool. Verifii is designed from the ground up so that the answer is always: it stays on your machine.

What verifiablyai.com is

The live demos at verifiablyai.com/projects are public open-source repositories we have analysed ourselves — requests, joda-money, spring-boot and others. They are a showcase of what Verifii produces, not a platform for customer code. We run the CLI on our own machine and publish the findings.

Verifii does not offer hosted analysis of private repositories. The product is the CLI and the self-hosted platform.

6. Architecture

This section explains exactly how Verifii works under the hood — what calls are made, where your code goes, and how the analysis intelligence is delivered without your code ever leaving your machine.

6.1 The analysis pipeline

When you run verifiably analyze, the following happens entirely on your machine:

1. File discovery — the CLI walks the directory, classifies files (source, test, config), builds an AST for each source file using tree-sitter
2. Dependency graph — imports and call relationships are extracted, files are sorted in dependency-first order so each analysis gets the context of its dependencies
3. Prompt fetch — the CLI calls the Verifii gate API with your license token to fetch the analysis prompt for the current file type. Your code is not in this call.
4. LLM call — the CLI sends the file content and fetched prompt directly to your LLM provider using your own API key. Verifii is not in this path.
5. Claim extraction — the LLM returns structured JSON: a list of claims, each with text, category, confidence, and file:line citation
6. Verification pass — a second LLM call checks each claim against the cited source lines. Claims that fail verification are marked not_determined rather than published
7. Cross-cutting pass — after all files are analysed, a final pass looks for contradictions across files: "File A claims X, File B shows the opposite"
8. Results saved locally — findings are written to your local project registry. Nothing is sent to Verifii.

6.2 The checkpoint gate

The analysis intelligence — the prompts that instruct the LLM what to extract and how to reason — is Verifii's core IP. The checkpoint gate delivers prompts at runtime without baking them into the CLI binary.

6.3 Session tokens and revocation

Every session token is bound to the machine that requested it (a hash of hostname, OS, and CPU). Tokens expire after 2 hours and are signed with HMAC-SHA256. If a license key is revoked, the next session request returns LICENSE_REVOKED and analysis cannot proceed.

This means Verifii can revoke access instantly — no waiting for a binary to expire or a cache to clear.

6.4 Viewing results locally

After analysis, findings are saved to your local project registry (~/verifiably_projects/). Run verifiably web to start the full web interface at localhost:8000 — the same interface as verifiablyai.com, running entirely on your machine. Or use the --serve flag to launch it automatically:

6.5 Self-hosted deployment

The self-hosted option runs the entire Verifii stack — the same CLI, the same web application, and a local gate API — on your own infrastructure. Engineers push findings from their machines to the internal Verifii server. The team browses results at an internal URL. The gate API runs locally so no internet connection is required after initial setup.

7. Reading a Claim

A claim is the atomic unit of Verifii analysis. Everything in the report is built from claims. Understanding what a claim is helps you assess confidence in any finding.

Confidence levels

• high — The behaviour is unambiguous from the code. No interpretation required.
• medium — The behaviour is likely but depends on a condition or context not fully resolved.
• low — The behaviour is inferred. Treat it as a hypothesis to verify manually.

8. Frequently Asked Questions