CLI reference¶

Every veska subcommand, generated from the command tree. Run veska <command> --help for the same information at the terminal.

`veska`¶

Veska code intelligence CLI

Veska code intelligence CLI.

New here? → run "veska init" to set up (use -y for non-interactive runs).

`veska backup`¶

Manage veska backups

`veska backup create`¶

Create a backup of the veska database and supporting files

veska backup create [flags]

Flags:

      --output-dir string   directory to write the backup tarball (default: $VESKA_HOME/backups)

`veska backup list`¶

List backup tarballs in the backup directory, newest first

veska backup list [flags]

Flags:

      --backup-dir string   directory to list (default: $VESKA_HOME/backups, falling back to ~/.veska-backups when empty)
      --json                emit JSON

`veska backup prune`¶

Apply the backup retention policy, deleting old backups

veska backup prune [flags]

Flags:

      --backup-dir string   directory to prune (default: $VESKA_HOME/backups)

`veska backup verify`¶

Verify the integrity of a backup tarball

veska backup verify <path> [flags]

Flags:

      --json   output result as JSON envelope

`veska blast`¶

Compute blast radius for a symbol, or --dirty/--diff for staged/working-tree/ranged changes

Compute the blast radius (callers/callees/both) of a symbol - 'if I change this, what breaks?' or 'what does this transitively reach?'. Use BEFORE editing an exported symbol, or when scoping a refactor. Walks cross_repo_edges in both directions so a library symbol's consumers in workspace repos are surfaced. Pass node_id (exact) or symbol (resolved via eng_find_symbol). For working-tree changes use eng_get_diff_blast_radius; for in-progress staged edits use eng_get_dirty_blast_radius.

veska blast [<symbol-or-node-id> | --diff [<ref_a>..<ref_b>]] [flags]

Flags:

      --diff               seed from a git diff: bare = working-tree vs HEAD; with a positional ref range (e.g. main..HEAD) = that range
      --direction string   out|in|both (aliases: callees|callers) - callees, callers, or both (default "both")
      --dirty              seed from the staged overlay (uncommitted, pre-commit changes)
      --json               emit JSON (eng_get_blast_radius shape)
      --repo string        repo id, short_id, or alias (default: fan out across registered repos)

`veska calls`¶

Walk CALLS edges from a symbol (wraps eng_get_call_chain)

Walk CALLS edges from a symbol. Use this - not search - when the question is 'what does this reach' (direction=out, default) or 'what calls this' (direction=in). Surfaces cross_repo_edges into other registered repos so library-symbol callers in a multi-repo workspace are visible without separate queries. Pass node_id (exact) or symbol (resolved via eng_find_symbol; ambiguity is rejected). NOTE: empty edges on a function/method seed carry one of two degraded_reasons hints: 'chained_selectors_unresolved' (parser limit - chained selector call sites like rootCmd.AddCommand(...).Execute() or s.field.M() are not yet modeled) or 'external_callees_only' (index boundary - callees are stdlib or unregistered modules, NOT a parser bug). Fall back to eng_get_blast_radius, eng_search_semantic, or eng_find_symbol.

veska calls <symbol-or-node-id> [flags]

Flags:

      --depth int           BFS depth limit (0 = daemon default)
      --direction string    out|in|both (aliases: callees|callers) - outgoing callees, incoming callers, or both (default "out")
      --expand-cross-repo   follow CALLS edges into other registered repos (default true)
      --json                emit JSON (eng_get_call_chain shape)
      --repo string         repo id, short_id, or alias (default: fan out across registered repos)

`veska changed`¶

Symbol-grain diff between two git refs (wraps eng_find_changed_symbols)

Show added/removed/modified symbols between two refs. Positional args match git diff ergonomics:

veska changed # HEAD~1..HEAD (default) veska changed v1.2.0 # v1.2.0..HEAD veska changed v1.2.0 v1.3.0 # v1.2.0..v1.3.0

The --ref-a/--ref-b flags remain accepted and take precedence over positional args.

veska changed [ref-a [ref-b]] [flags]

Flags:

      --json           emit JSON (eng_find_changed_symbols shape)
      --ref-a string   base ref (default: HEAD~1)
      --ref-b string   head ref (default: HEAD)
      --repo string    repo id, short_id, or alias

`veska clones`¶

Find duplicate code: exact byte-identical clones, or --near fuzzy clusters (wraps eng_find_clones)

Default: list groups of >=2 symbols whose source text is byte-for-byte identical (literal copy-paste), via content_hash equality - deterministic, no embeddings. With --near: cluster symbols whose persisted SIMILAR_TO similarity exceeds a threshold above auto-link's 'related' cutoff (fuzzy near-duplicates - renamed copies, drifted variants), reading scores auto-link already stored. For 'what else looks like this ONE symbol?', use veska similar <symbol>. Note: --near needs SIMILAR_TO edges carrying scores; reindex a repo promoted before scoring landed.

veska clones [flags]

Flags:

      --branch string     branch (default: repo's active branch)
      --json              emit JSON (eng_find_clones shape)
      --min-score float   with --near: minimum similarity score (0 = default calibrated for the elected embedder; lower for more recall)
      --near              fuzzy near-duplicate clusters from SIMILAR_TO edges (default: exact clones)
      --repo string       repo id, short_id, or alias

`veska completion`¶

Generate the autocompletion script for the specified shell

Generate the autocompletion script for veska for the specified shell. See each sub-command's help for details on how to use the generated script.

`veska completion bash`¶

Generate the autocompletion script for bash

Generate the autocompletion script for the bash shell.

This script depends on the 'bash-completion' package. If it is not installed already, you can install it via your OS's package manager.

To load completions in your current shell session:

source <(veska completion bash)

To load completions for every new session, execute once:

Linux:¶

veska completion bash > /etc/bash_completion.d/veska

macOS:¶

veska completion bash > $(brew --prefix)/etc/bash_completion.d/veska

You will need to start a new shell for this setup to take effect.

veska completion bash

Flags:

      --no-descriptions   disable completion descriptions

`veska completion fish`¶

Generate the autocompletion script for fish

Generate the autocompletion script for the fish shell.

To load completions in your current shell session:

veska completion fish | source

To load completions for every new session, execute once:

veska completion fish > ~/.config/fish/completions/veska.fish

You will need to start a new shell for this setup to take effect.

veska completion fish [flags]

Flags:

      --no-descriptions   disable completion descriptions

`veska completion powershell`¶

Generate the autocompletion script for powershell

Generate the autocompletion script for powershell.

To load completions in your current shell session:

veska completion powershell | Out-String | Invoke-Expression

To load completions for every new session, add the output of the above command to your powershell profile.

veska completion powershell [flags]

Flags:

      --no-descriptions   disable completion descriptions

`veska completion zsh`¶

Generate the autocompletion script for zsh

Generate the autocompletion script for the zsh shell.

If shell completion is not already enabled in your environment you will need to enable it. You can execute the following once:

echo "autoload -U compinit; compinit" >> ~/.zshrc

To load completions in your current shell session:

source <(veska completion zsh)

To load completions for every new session, execute once:

Linux:¶

veska completion zsh > "${fpath[1]}/_veska"

macOS:¶

veska completion zsh > $(brew --prefix)/share/zsh/site-functions/_veska

You will need to start a new shell for this setup to take effect.

veska completion zsh [flags]

Flags:

      --no-descriptions   disable completion descriptions

`veska config`¶

Manage veska configuration

`veska config reload`¶

Restart the daemon and re-promote every registered repo so new config takes effect

veska config reload

`veska config show`¶

Print the effective veska configuration (defaults + config.toml + env)

veska config show [flags]

Flags:

      --json   emit JSON instead of TOML

`veska context`¶

Bundle a symbol with its callers/callees/tests (wraps eng_get_context_pack)

Bundle a symbol's neighborhood (callers, callees, adjacent tests, recent commits, open findings, active task) into one token-bounded payload. Use at the START of a non-trivial change so you don't have to assemble surrounding context piecewise. Surfaces cross_repo_edges in both directions, so cross-repo callers/callees show up in the same response.

veska context <symbol> [flags]

Flags:

      --json            emit JSON (eng_get_context_pack shape)
      --repo string     repo id or short_id (default: the sole registered repo)
      --symbol string   symbol name (alternative to the positional arg)

`veska daemon`¶

Veska long-running daemon (MCP server + ingester + workers)

veska daemon

`veska daemon start`¶

Start the daemon (default action when no subcommand is given)

veska daemon start

`veska deps`¶

Inspect and index a repo's external dependencies

veska deps [flags]

Flags:

      --json          emit JSON (eng_list_dependencies shape)
      --limit int     maximum rows to print (0 = no limit) (default 25)
      --repo string   repo id or short_id (default: the sole registered repo)

`veska deps index`¶

Index a vendored Go module's symbols into the graph

veska deps index <module-path> [flags]

Flags:

      --repo string   repo id or short_id (default: the cwd-resolved repo)

`veska deps list`¶

List external modules the repo CALLS into, ranked by call-site count

List external modules the repo CALLS into, ranked by call-site count.

Note: a module imported but only referenced via struct literals / type assertions (no resolved package-qualified call) will not appear yet - this tracks the import-side backfill.

veska deps list [<id-or-path>] [flags]

Flags:

      --json          emit JSON (eng_list_dependencies shape)
      --limit int     maximum rows to print (0 = no limit) (default 25)
      --repo string   repo id or short_id (default: the sole registered repo)

`veska diff-gate`¶

Gate a candidate change: verify it resolves a finding within blast radius, emit pass/fail JSON (exits non-zero on FAIL)

Index a candidate change (base-ref..candidate-ref) against the indexed-HEAD graph and emit a deterministic, network-free pass/fail verdict: did it resolve its target finding, introduce no new structural findings (dead-code, contract-drift), and stay within the finding's blast radius? Emits JSON and exits non-zero on FAIL for CI gating.

Identify the target finding with --finding (the first column of veska findings list); its anchor and rule are derived for you. Power users / CI can pass --anchor + --rule directly instead.

veska diff-gate [flags]

Example:

# gate a fix for a finding you saw in `veska findings list`
  veska diff-gate --repo <id> --finding <finding_id> --base-ref HEAD~1 --candidate-ref HEAD

Flags:

      --anchor string          node id the target finding is anchored on (alternative to --finding)
      --base-ref string        git ref of the base the candidate is diffed against
      --branch string          branch (default "main")
      --candidate-ref string   git ref/worktree of the candidate change
      --finding string         target finding id from 'veska findings list'; derives --anchor and --rule
      --repo string            repo id (scopes the indexed-HEAD base graph)
      --repo-root string       repo working dir for git ref reads (default: cwd)
      --rule string            rule name of the target finding, e.g. dead-code (alternative to --finding)

`veska diff-gate api`¶

Gate a candidate change on breaking exported-signature changes, emit pass/fail JSON (exits non-zero on FAIL)

Index a candidate change (base-ref..candidate-ref) against the indexed-HEAD graph and FAIL when it changes the signature shape (name + parameters + result) of an EXPORTED symbol - a breaking public-surface change. Unexported signature changes and body-only edits pass. Scope is signature-shape only: symbol removal/rename is not detected, and exported is the name-based visibility flag, not reachability. Deterministic, network-free; emits JSON and exits non-zero on FAIL for CI gating.

veska diff-gate api [flags]

Example:

veska diff-gate api --repo <id> --base-ref HEAD~1 --candidate-ref HEAD

Flags:

      --base-ref string        git ref of the base the candidate is diffed against
      --branch string          branch (default "main")
      --candidate-ref string   git ref/worktree of the candidate change
      --repo string            repo id (scopes the indexed-HEAD base graph)
      --repo-root string       repo working dir for git ref reads (default: cwd)

`veska diff-gate clones`¶

Gate a candidate change on newly-introduced exact-clone duplication, emit pass/fail JSON (exits non-zero on FAIL)

Index a candidate change (base-ref..candidate-ref) against the indexed-HEAD graph and FAIL when it introduces a new exact-clone group - a byte-identical copy (content_hash equality) of code it did not already duplicate at base. Deterministic, network-free, embedding-free; emits JSON and exits non-zero on FAIL for CI gating.

veska diff-gate clones [flags]

Example:

veska diff-gate clones --repo <id> --base-ref HEAD~1 --candidate-ref HEAD

Flags:

      --base-ref string        git ref of the base the candidate is diffed against
      --branch string          branch (default "main")
      --candidate-ref string   git ref/worktree of the candidate change
      --repo string            repo id (scopes the indexed-HEAD base graph)
      --repo-root string       repo working dir for git ref reads (default: cwd)

`veska diff-gate cycles`¶

Gate a candidate change on newly-introduced dependency cycles, emit pass/fail JSON (exits non-zero on FAIL)

Index a candidate change (base-ref..candidate-ref) against the indexed-HEAD graph and FAIL when it introduces a net-new dependency cycle - a strongly-connected component of >=2 symbols (over CALLS/IMPORTS edges) absent at base. The candidate is re-promoted so cross-file edges resolve; only cycles touching the change set are judged. Node-level, deterministic, network-free; emits JSON and exits non-zero on FAIL for CI gating.

veska diff-gate cycles [flags]

Example:

veska diff-gate cycles --repo <id> --base-ref HEAD~1 --candidate-ref HEAD

Flags:

      --base-ref string        git ref of the base the candidate is diffed against
      --branch string          branch (default "main")
      --candidate-ref string   git ref/worktree of the candidate change
      --repo string            repo id (scopes the indexed-HEAD base graph)
      --repo-root string       repo working dir for git ref reads (default: cwd)

`veska diff-gate report`¶

Advisory PR impact/risk report (blast radius, change-risk, findings, untested) - always exits 0, never gates

Assemble an ADVISORY report for a candidate change (base-ref..candidate-ref): the diff's blast radius, each changed file's change-risk standing (recent-change-frequency × blast-radius), open findings on the touched files, and changed-but-untested symbols. Unlike the diff-gate subcommands this NEVER gates - it always exits 0 (findings/risk never block; an un-indexed repo or a failed section yields a noted report). The soft on-ramp before teams trust blocking gates. Emits JSON.

veska diff-gate report [flags]

Example:

veska diff-gate report --repo <id> --base-ref HEAD~1 --candidate-ref HEAD

Flags:

      --base-ref string        git ref of the base the candidate is diffed against
      --branch string          branch (default "main")
      --candidate-ref string   git ref/worktree of the candidate change
      --repo string            repo id (scopes the indexed-HEAD base graph)
      --repo-root string       repo working dir for git ref reads (default: cwd)

`veska diff-gate security`¶

Gate a candidate change on net-new secret/vulnerable-dependency findings, emit pass/fail JSON (exits non-zero on FAIL)

Scan a candidate change (base-ref..candidate-ref) and FAIL when it introduces a new secret_leak (scanned over the diff's added lines - any language) or a new vulnerable_dependency (manifest finding-delta by finding_id; go.mod today). A blanket gate: no target finding, no indexed graph required. Offline and deterministic; emits JSON and exits non-zero on FAIL for CI gating.

veska diff-gate security [flags]

Example:

veska diff-gate security --repo <id> --base-ref HEAD~1 --candidate-ref HEAD

Flags:

      --base-ref string        git ref of the base the candidate is diffed against
      --branch string          branch (default "main")
      --candidate-ref string   git ref/worktree of the candidate change
      --repo string            repo id (folded into finding keys)
      --repo-root string       repo working dir for git ref reads (default: cwd)

`veska diff-gate select-tests`¶

Select the tests whose covered nodes intersect a diff (emit go test -run per package); never gates

Select the tests whose covered nodes intersect a candidate change (base-ref..candidate-ref) and emit a runner-consumable go test -run selection per package. Covering tests are derived transitively from the latent *_test.go CALLS edges already in the index (no real coverage data) - a selection HEURISTIC that over-selects (the safe direction), not a guarantee. Changed test files force their whole package since their tests may not be indexed yet. NEVER gates: every selection outcome - including unknown-repo, repo-not-indexed, and bad-ref - exits 0 with a JSON envelope (an advisory reason lands in the error field); only a usage or infrastructure error exits non-zero. Always emits JSON.

veska diff-gate select-tests [flags]

Example:

veska diff-gate select-tests --repo <id> --base-ref HEAD~1 --candidate-ref HEAD

Flags:

      --base-ref string        git ref of the base the candidate is diffed against
      --branch string          branch (default "main")
      --candidate-ref string   git ref/worktree of the candidate change
      --repo string            repo id (scopes the indexed base graph)
      --repo-root string       repo working dir for git ref reads (default: cwd)

`veska diff-gate untested`¶

Gate a candidate change on changed prod symbols that no test reaches, emit pass/fail JSON (exits non-zero on FAIL)

Index a candidate change (base-ref..candidate-ref) and FAIL when a changed or added prod symbol has no test-file caller in the candidate after-state - a CALLS-edge coverage proxy, not real coverage data. The candidate is re-promoted so a test added in the same diff counts; only symbols in the change set are judged. Emits JSON and exits non-zero on FAIL for CI gating.

veska diff-gate untested [flags]

Example:

veska diff-gate untested --repo <id> --base-ref HEAD~1 --candidate-ref HEAD

Flags:

      --base-ref string        git ref of the base the candidate is diffed against
      --branch string          branch (default "main")
      --candidate-ref string   git ref/worktree of the candidate change
      --repo string            repo id (scopes the indexed-HEAD base graph)
      --repo-root string       repo working dir for git ref reads (default: cwd)

`veska doctor`¶

Health checks for the veska runtime

Health checks for the veska runtime.

With no subcommand, runs the 'status' rollup across all subsystems.

veska doctor [flags]

Flags:

      --json      output results as JSON
  -v, --verbose   include failed queue rows inline

`veska doctor backup`¶

Verify most recent backup archive and report its age

veska doctor backup [flags]

Flags:

      --json   output results as JSON

`veska doctor bundle`¶

Write a diagnostic tarball with all probe outputs and audit tail

veska doctor bundle [flags]

Flags:

      --json                output results as JSON
      --output-dir string   directory to write the tarball (default: system temp dir)

`veska doctor config`¶

Validate veska configuration values

veska doctor config [flags]

Flags:

      --json   output results as JSON

`veska doctor egress`¶

Verify daemon socket and control-plane connectivity

veska doctor egress [flags]

Flags:

      --json   output results as JSON

`veska doctor embedder`¶

Verify the elected embedding provider

veska doctor embedder [flags]

Flags:

      --json   output results as JSON

`veska doctor identity`¶

Report repo identity-tier convergence for shared-DB readiness

Report each registered repo's resolved identity tier (ADR-S0017) and warn on any that won't converge in a shared multi-contributor graph DB.

A tier is how a repo's identity (and therefore its node ids) is derived: module-hostpath go.mod github.com/org/repo - CONVERGES: two contributors indexing the same upstream get identical ids (the shareable tier) origin-url git remote URL - local-only (diverges across forks) module-bare bare module myapp - local-only (collision-prone) abs-root absolute checkout path - local-only

Non-converging is perfectly fine for single-user use; it only matters before sharing a DB. Advisory only - never folded into doctor status.

veska doctor identity [flags]

Flags:

      --json   output results as JSON

`veska doctor pipelines`¶

Report review-pipeline token usage against the configured caps

veska doctor pipelines [flags]

Flags:

      --json   output results as JSON

`veska doctor post_promotion_queue`¶

Inspect the post-promotion queue depth and failed rows

veska doctor post_promotion_queue [flags]

Flags:

      --json            output results as JSON
      --purge-orphans   delete failed rows whose repo_id is no longer registered

`veska doctor reset-crash-loop`¶

Clear broken marker and restart counter so the daemon can start again

veska doctor reset-crash-loop [flags]

Flags:

      --json   output results as JSON

`veska doctor savings`¶

Show inline-snippet token savings per period

Show inline-snippet token savings per period (today / 7d / all-time).

"Savings" is the ratio 1 - snippet_chars/file_chars: how much agent-side file-read traffic the inline snippets in eng_search_semantic results saved.

Warmup: a period reads "warming up" until it has recorded at least 20 eng_search_semantic calls. Below that the sample is too small to be meaningful - a single short snippet can drive the ratio negative - so only the running call count is shown, not a percentage. Once a period crosses 20 calls its row switches to a percentage.

The counter only advances on eng_search_semantic searches (not symbol/ context lookups), and those come from the MCP server the daemon runs. Until an MCP-aware editor is wired up - or eng_search_semantic is called directly several times - savings stays in warmup.

veska doctor savings [flags]

Flags:

      --aggregate   pool every repo into a single bucket instead of the per-repo breakdown
      --json        output results as JSON

`veska doctor service`¶

Check supervisor state and broken-marker presence

veska doctor service [flags]

Flags:

      --json   output results as JSON

`veska doctor status`¶

Overall health rollup across all subsystems

veska doctor status [flags]

Flags:

      --json      output results as JSON
  -v, --verbose   include failed queue rows inline

`veska doctor storage`¶

Report filesystem storage metrics for the veska data directory

veska doctor storage [flags]

Flags:

      --json   output results as JSON

`veska doctor wiki_render`¶

Report the age of the last successful wiki render

veska doctor wiki_render [flags]

Flags:

      --json   output results as JSON

`veska duplicates`¶

Whole-repo (or cross-repo) similar-code clusters for de-dupe triage (wraps eng_find_clusters)

List groups of >=2 similar symbols in one ranked pass across three tiers (tightest first): 'exact' (byte-identical copy-paste), 'structural' (same shape after renaming variables/literals - Type-2 clones), and 'near' (vector-similar above the elected embedder's calibrated threshold). A symbol appears at most once, at its tightest tier. No seed needed - point it at a repo (or --all-repos) and turn each cluster into a verify-and-dedupe task. Note: structural/near need structural_hash + scored SIMILAR_TO edges; reindex a graph promoted before they landed.

veska duplicates [flags]

Flags:

      --all-repos         cluster across every registered repo (cross-repo; exact+structural only)
      --branch string     branch (default: repo's active branch, or 'main' with --all-repos)
      --json              emit JSON (eng_find_clusters shape)
      --min-score float   near tier: minimum similarity score (0 = calibrated default; lower for more recall)
      --path string       restrict to nodes whose file_path starts with this prefix
      --repo string       repo id, short_id, or alias (ignored with --all-repos)
      --tiers string      comma-separated subset of exact,structural,near (default: all)

`veska entry-points`¶

List high-fan-in entry-point symbols (wraps eng_get_entry_points)

List the high-fan-in symbols ranked by inbound call count - the natural entry points to read first when learning a repo. Exported, tested symbols rank above unexported untested ones at equal inbound count.

veska entry-points [flags]

Flags:

      --include-tests   include Test/Benchmark/Example/Fuzz entries
      --json            emit JSON (eng_get_entry_points shape)
      --limit int       max rows (0 = service default)
      --repo string     repo id, short_id, or alias (default: cwd-resolved repo)

`veska file-nodes`¶

List every node defined in a file (wraps eng_get_file_nodes)

Return all nodes for a single source file. The path is repo-relative when --repo is given, otherwise absolute. Staged nodes take precedence when an uncommitted version exists.

veska file-nodes <path> [flags]

Flags:

      --branch string   branch (default: active branch)
      --json            emit JSON (eng_get_file_nodes shape)
      --repo string     repo id, short_id, or alias (path is repo-relative when set)

`veska findings`¶

List, inspect, close, or reopen promotion-check findings

`veska findings close`¶

Close a finding with a reason

veska findings close <finding_id> [flags]

Flags:

      --reason string   closing reason (required)

`veska findings list`¶

List findings (default state=open)

veska findings list [flags]

Flags:

      --all                  list findings across every registered repo
      --include-low          include low-severity findings (default hides auto-link noise)
      --include-suppressed   include findings hidden by an active suppression (shows a SUPPRESSED_BY column)
      --json                 emit JSON
      --limit int            maximum rows to print (0 = no limit) (default 25)
      --repo string          repo id or short_id (default: the sole registered repo)
      --rule string          filter by rule (e.g. vulnerable_dependency, dead-code, secret_leak, auto-link)
      --severity string      filter by severity
      --state string         filter by state (open|closed; default open)

`veska findings reopen`¶

Reopen a previously-closed finding

veska findings reopen <finding_id> [flags]

Flags:

      --branch string   branch
      --repo string     repo id or short_id

`veska findings show`¶

Show a single finding by id

veska findings show <finding_id> [flags]

Flags:

      --branch string        branch to scope the lookup (default: active)
      --json                 emit JSON
      --repo findings list   repo id (full or short) to scope the lookup; parity with findings list

`veska findings suppress`¶

Suppress a finding so it stops surfacing in list

veska findings suppress <finding_id> [flags]

Flags:

      --expires-at int   optional Unix timestamp at which the suppression expires
      --reason string    suppression reason (required)
      --scope string     scope; defaults to 'finding'

`veska findings suppressions`¶

List, inspect, or close finding suppressions

`veska findings suppressions close`¶

Close (expire now) an active suppression

veska findings suppressions close <suppression_id> [flags]

Flags:

      --repo string   repo id or short_id for audit attribution

`veska findings suppressions list`¶

List active suppressions

veska findings suppressions list [flags]

Flags:

      --branch string   filter by branch (omit to list across branches)
      --json            emit JSON
      --repo string     repo id or short_id (default: the sole registered repo)

`veska findings suppressions show`¶

Show a single suppression by id

veska findings suppressions show <suppression_id> [flags]

Flags:

      --json   emit JSON

`veska help`¶

Help about any command

Help provides help for any command in the application. Simply type veska help [path to command] for full details.

veska help [command]

`veska hook-runner`¶

Git hook shims installed by veska init

`veska hook-runner post-checkout`¶

Update active branch after a git checkout (installed by veska init)

veska hook-runner post-checkout

`veska hook-runner post-commit`¶

Notify daemon after a git commit (installed by veska init)

veska hook-runner post-commit

`veska hot-zones`¶

List files ranked by change risk (wraps eng_get_hot_zone)

List the top files by change risk = recent-change-frequency × blast-radius - the load-bearing files where a small edit fans out the most. Useful during PR review or onboarding.

veska hot-zones [flags]

Flags:

      --json          emit JSON (eng_get_hot_zone shape)
      --limit int     max files (0 = service default)
      --repo string   repo id, short_id, or alias (default: cwd-resolved repo)

`veska init`¶

First-run setup, or write per-agent instruction snippet with --agent

veska init [flags]

Flags:

      --agent string       write a per-agent instruction snippet to the current project (claude, codex, copilot, cursor, gemini, kiro, opencode)
      --no-vuln            skip the OSV vulnerability-scanner prompt and leave it disabled
      --update-gitignore   with --agent: also write a veska-managed block to .gitignore covering generated artifacts (off by default)
  -y, --yes                auto-accept all prompts (non-interactive mode)

`veska install`¶

Install optional models for veska

veska install

`veska install model2vec`¶

Download the model2vec static code embedder (potion-code-16M)

veska install model2vec

`veska mcp`¶

Veska MCP stdio shim (proxies editor to daemon socket)

veska mcp is the editor-facing shim. It reads newline-delimited JSON-RPC requests on stdin, forwards them to the daemon's MCP socket ($VESKA_HOME/mcp.sock), and writes responses back to stdout.

Protocol: flat JSON-RPC. The method IS the tool name; there is no "tools/call" envelope. Parameters go in the standard "params" field.

Example (from a shell, with the daemon running):

printf '{"jsonrpc":"2.0","id":1,"method":"eng_get_status","params":{}}\n' \ | veska-mcp

Editor integration: point your MCP client at this binary as a stdio command. Examples for Claude Desktop / Cursor / Continue / Zed live in README.md → "Editor integration".

veska mcp

`veska node`¶

Show a single node by id (wraps eng_get_node)

Look up one node by its content-hashed node_id (or 12-char display prefix). repo_id/branch are optional - the id is globally unique; pass both to apply the staging overlay.

veska node <node-id> [flags]

Flags:

      --branch string   branch (optional; pass with --repo to apply the staging overlay)
      --json            emit JSON (eng_get_node shape)
      --repo string     repo id, short_id, or alias (optional; node_id is globally unique)

`veska owner`¶

Find the owner of a file via CODEOWNERS or git blame (wraps eng_find_owner)

Resolve who owns a file - CODEOWNERS longest-match first, git-blame dominant-committer fallback. The argument may be a file path, a symbol, or a node_id (symbol/node resolve to their defining file).

veska owner <path-or-symbol> [flags]

Flags:

      --branch string   branch used when resolving a symbol/node to its file
      --json            emit JSON (eng_find_owner shape)
      --repo string     repo id, short_id, or alias (default: cwd-resolved repo)

`veska reindex`¶

Force a full cold-scan reparse of a repository

veska reindex [<repo-id-or-path>] [flags]

Flags:

      --repo string   repo id, short_id, alias or path (alias for the positional arg)

`veska related`¶

Find symbols similar to the code at a file:line (wraps eng_find_related)

Find symbols semantically similar to the code at a (file, line) anchor - a moat-pivot from a search hit, error trace, or editor cursor. Line is 1-indexed.

veska related <file:line> [flags]

Flags:

      --json          emit JSON (eng_find_related shape)
      --k int         neighbor count (0 = daemon default of 10)
      --repo string   repo id, short_id, or alias

`veska repo`¶

Manage git repositories tracked by veska

`veska repo add`¶

Register a git repository (local path or remote URL) and install hooks

veska repo add <path-or-url> [flags]

Flags:

      --wait   block until the cold scan completes; print live progress

`veska repo alias`¶

Bind a human-friendly name to a repo

Bind a human-friendly name to a repo.

The new name comes FIRST, the existing repo SECOND - same order as "git remote add ". (Note this is the reverse of "ln -s ".) If the arguments look swapped, the command detects it and prints a hint rather than failing silently.

veska repo alias <name> <repo-id-or-prefix-or-alias> [flags]

Example:

# Alias the repo whose id starts with "a1b2" to the name "lib":
  veska repo alias lib a1b2

  # Overwrite an existing alias:
  veska repo alias lib c3d4 --force

Flags:

      --force   overwrite an existing alias bound to a different repo

`veska repo current`¶

Show the repo the current directory belongs to (wraps eng_get_current_repo)

veska repo current [flags]

Flags:

      --json   emit JSON (eng_get_current_repo shape)

`veska repo list`¶

List registered git repositories

veska repo list [flags]

Flags:

      --include-external veska deps index   also show synthetic ext:<module> repos created by veska deps index

`veska repo remove`¶

Deregister a repository and remove hooks

veska repo remove [<id-or-path>] [flags]

Flags:

      --all       remove every registered repo (requires --yes or interactive confirmation)
      --dry-run   print what would be removed without changing the registry
      --missing   remove every repo whose root directory no longer exists
      --yes       skip interactive confirmation (required for --all in scripts)

`veska repo show`¶

Show a single registered repo (wraps eng_get_repo)

veska repo show <repo-id-or-short-id> [flags]

Flags:

      --json   emit JSON (eng_get_repo shape)

`veska repo unalias`¶

Remove a user-defined alias

veska repo unalias <name>

`veska restore`¶

Restore the veska database from a backup tarball

Restore the veska database from a backup tarball.

Provide an explicit , or use --latest to select the newest backup, or --pre-migration to select the newest auto-pre-migration snapshot. The daemon must be stopped before restoring.

veska restore [<path>] [flags]

Flags:

      --latest          restore the newest backup tarball in $VESKA_HOME/backups (falls back to ~/.veska-backups)
      --pre-migration   restore the newest auto-pre-migration snapshot

`veska savings`¶

Show inline-snippet token savings per period

Show inline-snippet token savings per period (today / 7d / all-time).

"Savings" is the ratio 1 - snippet_chars/file_chars: how much agent-side file-read traffic the inline snippets in eng_search_semantic results saved.

Warmup: a period reads "warming up" until it has recorded at least 20 eng_search_semantic calls. Below that the sample is too small to be meaningful - a single short snippet can drive the ratio negative - so only the running call count is shown, not a percentage. Once a period crosses 20 calls its row switches to a percentage.

The counter only advances on eng_search_semantic searches (not symbol/ context lookups), and those come from the MCP server the daemon runs. Until an MCP-aware editor is wired up - or eng_search_semantic is called directly several times - savings stays in warmup.

veska savings [flags]

Flags:

      --aggregate   pool every repo into a single bucket instead of the per-repo breakdown
      --json        output results as JSON

`veska search`¶

Semantic search; optionally clone+index a repo first

Natural-language search over embedded symbols (RRF-fused with FTS, lexical fallback when the embedder is offline). Best for behavior-shaped queries ('where do we validate session tokens'). Returns inline snippets so a follow-up Read is usually unnecessary. For known identifiers prefer eng_find_symbol (exact + deterministic); for 'what does this reach / who calls this' escalate to eng_get_call_chain / eng_get_blast_radius. With repo_id omitted (and cwd outside any registered repo) the query fanned out across every registered repo in parallel and is fused with a single GLOBAL RRF so a top hit in one repo competes fairly with a top hit in another; each result then carries 'repo_id' so callers can disambiguate. The returned score is intra-query RRF (~0.01–0.03 typical range); use rank, not absolute score, to compare hits.

The optional second argument (or --repo flag) selects the repo to search: - omitted - auto-detect from cwd (must be a registered repo) - local path - registered local repo (absolute or relative) - git URL - clones into the cache tier (~/.cache/veska/repos/), marks as ephemeral, indexes it, then searches

Examples: veska search "parse config" # search the repo containing cwd veska search "parse config" /path/to/myrepo # search a specific registered local repo veska search "parse config" --repo https://github.com/x # clone (ephemeral), index, search

veska search <query> [path-or-url] [flags]

Flags:

      --json          emit JSON (same shape as eng_search_semantic)
  -k, --limit int     max results to return (default 10)
      --repo string   repo target (path, URL, repo_id or short_id) - alias for the positional argument

`veska service`¶

Manage the veska daemon OS service (install, start, stop, …)

`veska service install`¶

Install the veska daemon as an OS service

veska service install [flags]

Flags:

      --dry-run   print what would be done without making changes

`veska service restart`¶

Restart the veska daemon OS service

veska service restart [flags]

Flags:

      --dry-run   print what would be done without making changes

`veska service start`¶

Start the veska daemon OS service

veska service start [flags]

Flags:

      --dry-run   print what would be done without making changes

`veska service status`¶

Show the current state of the veska daemon OS service

veska service status [flags]

Flags:

      --dry-run   print what would be done without making changes

`veska service stop`¶

Stop the veska daemon OS service

veska service stop [flags]

Flags:

      --dry-run   print what would be done without making changes

`veska service uninstall`¶

Uninstall the veska daemon OS service

veska service uninstall [flags]

Flags:

      --dry-run   print what would be done without making changes

`veska similar`¶

Find symbols nearest to a seed in vector space (wraps eng_search_similar)

Vector-nearest-neighbor search seeded by an existing symbol or node_id - 'what else looks like this?'. Use to find variants, near-duplicates, or refactor targets. The seed itself is excluded from results.

veska similar <symbol-or-node-id> [flags]

Flags:

      --json          emit JSON (eng_search_similar shape)
      --k int         neighbor count (0 = daemon default of 10)
      --repo string   repo id, short_id, or alias

`veska symbol`¶

Look up symbols by name (wraps eng_find_symbol)

Find symbols by unqualified name or symbol path.

Auto-resolves repo_id from the only registered repo when --repo is omitted; pass --repo to scope across multiple repos.

Unqualified names also match - 'Run' finds Server.Run, Command.Run, etc., with exact matches first.

veska symbol <name> [flags]

Flags:

      --json          emit JSON (eng_find_symbol shape)
      --repo string   repo id or short_id (default: the sole registered repo)

`veska todos`¶

List TODO/FIXME findings in the indexed source (wraps eng_find_todos)

List the TODO/FIXME findings the promotion checks harvested from the indexed source. Defaults to open TODOs; pass --include-closed to also show resolved ones.

veska todos [flags]

Flags:

      --include-closed   also show closed TODO findings
      --json             emit JSON (eng_find_todos shape)
      --repo string      repo id, short_id, or alias (default: cwd-resolved repo)

`veska upgrade`¶

Atomically replace the veska binary with a new build

veska upgrade <path> [flags]

Flags:

      --restart         restart the daemon service after swapping the binary
      --target string   binary path to replace (default: current executable)

`veska version`¶

Print veska version and build info

veska version

`veska wiki`¶

Regenerate the veska wiki pages (hot_zones + entry_points)

veska wiki [path|repo-id] [flags]

Flags:

      --all             regenerate the wiki for every registered repo
      --branch string   branch to regenerate (default: the repo's active branch)
      --repo string     repo ID to regenerate (default: the sole registered repo)

CLI reference¶

veska¶

veska backup¶

veska backup create¶

veska backup list¶

veska backup prune¶

veska backup verify¶

veska blast¶

veska calls¶

veska changed¶

veska clones¶

veska completion¶

veska completion bash¶

Linux:¶

macOS:¶

veska completion fish¶

veska completion powershell¶

veska completion zsh¶

Linux:¶

macOS:¶

veska config¶

veska config reload¶

veska config show¶

veska context¶

veska daemon¶

veska daemon start¶

veska deps¶

veska deps index¶

veska deps list¶

veska diff-gate¶

veska diff-gate api¶

veska diff-gate clones¶

veska diff-gate cycles¶

veska diff-gate report¶

veska diff-gate security¶

veska diff-gate select-tests¶

veska diff-gate untested¶

veska doctor¶

veska doctor backup¶

veska doctor bundle¶

veska doctor config¶

veska doctor egress¶

veska doctor embedder¶

veska doctor identity¶

veska doctor pipelines¶

veska doctor post_promotion_queue¶

veska doctor reset-crash-loop¶

veska doctor savings¶

veska doctor service¶

veska doctor status¶

veska doctor storage¶

veska doctor wiki_render¶

veska duplicates¶

veska entry-points¶

veska file-nodes¶

veska findings¶

veska findings close¶

veska findings list¶

veska findings reopen¶

veska findings show¶

veska findings suppress¶

veska findings suppressions¶

veska findings suppressions close¶

veska findings suppressions list¶

veska findings suppressions show¶

veska help¶

veska hook-runner¶

veska hook-runner post-checkout¶

veska hook-runner post-commit¶

veska hot-zones¶

veska init¶

veska install¶

veska install model2vec¶

veska mcp¶

veska node¶

veska owner¶

veska reindex¶

veska related¶

veska repo¶

veska repo add¶

`veska`¶

`veska backup`¶

`veska backup create`¶

`veska backup list`¶

`veska backup prune`¶

`veska backup verify`¶

`veska blast`¶

`veska calls`¶

`veska changed`¶

`veska clones`¶

`veska completion`¶

`veska completion bash`¶

`veska completion fish`¶

`veska completion powershell`¶

`veska completion zsh`¶

`veska config`¶

`veska config reload`¶

`veska config show`¶

`veska context`¶

`veska daemon`¶

`veska daemon start`¶

`veska deps`¶

`veska deps index`¶

`veska deps list`¶

`veska diff-gate`¶

`veska diff-gate api`¶

`veska diff-gate clones`¶

`veska diff-gate cycles`¶

`veska diff-gate report`¶

`veska diff-gate security`¶

`veska diff-gate select-tests`¶

`veska diff-gate untested`¶

`veska doctor`¶

`veska doctor backup`¶

`veska doctor bundle`¶

`veska doctor config`¶

`veska doctor egress`¶

`veska doctor embedder`¶

`veska doctor identity`¶

`veska doctor pipelines`¶

`veska doctor post_promotion_queue`¶

`veska doctor reset-crash-loop`¶

`veska doctor savings`¶

`veska doctor service`¶

`veska doctor status`¶

`veska doctor storage`¶

`veska doctor wiki_render`¶

`veska duplicates`¶

`veska entry-points`¶

`veska file-nodes`¶

`veska findings`¶

`veska findings close`¶

`veska findings list`¶

`veska findings reopen`¶

`veska findings show`¶

`veska findings suppress`¶

`veska findings suppressions`¶

`veska findings suppressions close`¶

`veska findings suppressions list`¶

`veska findings suppressions show`¶

`veska help`¶

`veska hook-runner`¶

`veska hook-runner post-checkout`¶

`veska hook-runner post-commit`¶

`veska hot-zones`¶

`veska init`¶

`veska install`¶

`veska install model2vec`¶

`veska mcp`¶

`veska node`¶

`veska owner`¶

`veska reindex`¶

`veska related`¶

`veska repo`¶

`veska repo add`¶

`veska repo alias`¶

`veska repo current`¶

`veska repo list`¶

`veska repo remove`¶

`veska repo show`¶