Skip to content

cli.md

Latest commit

 

History

History
496 lines (403 loc) · 23.1 KB

cli.md

File metadata and controls

496 lines (403 loc) · 23.1 KB
Raw

Command-line reference

repodna is the command-line interface. Every command prints help with --help, and repodna --help lists them all. In upcoming releases, running repodna without arguments also displays help and exits successfully. Invalid arguments and unknown commands remain errors (exit code 2).

repodna <command> [options] [target]

Targets

Most commands take one target (default: the current directory). A target can be:

Target Example What happens
A directory . or ~/src/project Analyzed in place; nothing in it is modified.
A Git URL https://github.com/owner/repo Cloned into a temporary directory, analyzed, and deleted.
An archive project.zip, project.tar.gz Extracted with safety limits into a temporary directory.
An artifact file repodna.json, export.repodna Read as an existing analysis; nothing is analyzed.
A stored repository polyglot or its identifier The latest stored analysis is used; nothing is analyzed.

A directory is analyzed again every time, which is quick when little has changed because results for unchanged files come from the per-file cache. To read a stored analysis instead, give a view command (show, report, card, and so on) the repository's name from repodna list, or its identifier; it says which analysis it uses:

Using the stored analysis of polyglot from 2026-09-25 (revision 540e92db6965). Pass a path to analyze again.

Options shared by most commands

Global options:

Option Meaning
--color auto|always|never When to use color. NO_COLOR is respected in auto mode.
-q, --quiet Print only results and errors, without progress.
--config FILE Read this configuration file after your user configuration.
--no-user-config Ignore your user configuration file.
--no-project-config Ignore the repository's own repodna.toml.

Options that control how an analysis runs (accepted by every command that may analyze):

Option Meaning
--profile NAME quick, standard (default), deep, history-only, architecture-only, dependencies-only, or security-only. See the analysis engine.
--no-store Do not store the analysis locally (this also skips the cache).
--no-cache Do not reuse per-file results from earlier runs.
--plugin NAME Enable a plugin for this run (repeatable).
--plugin-dir DIR Also search this directory for plugins (repeatable).
--anonymize Replace contributor names with pseudonyms.
--no-commit-messages Do not keep commit subjects in the artifact.
--threads N Worker threads (0 means one per CPU).
--max-commits N Analyze at most this many commits.
--clone-depth N Clone URLs with at most this many commits of history.
--allow-private-hosts Allow cloning from hosts on private networks.
--allow-insecure-urls Allow cloning over unencrypted http:// and git://.
--reproducible Record zero durations; with SOURCE_DATE_EPOCH set, repeated runs produce identical artifacts.

Privacy presets, used by --privacy on the commands that print or write output:

Preset What is removed
local Nothing beyond what is never stored: secret values and absolute paths.
share Also commit messages, the text of marker comments (such as TODO notes), and command output.
public Also contributor names (replaced by pseudonyms), remote URLs, and symbol names.

See privacy for details.

Analyze

repodna analyze (alias scan)

Analyzes a repository, stores the result, and prints a summary.

repodna analyze                       # the current directory
repodna analyze ~/src/project --profile deep
repodna analyze https://github.com/sanskarIN/RepoDNA
repodna analyze . --output repodna-report   # also write a report bundle
repodna analyze . --format json > repodna.json
repodna analyze . --format markdown > REPORT.md
Option Meaning
--format text|json|markdown What to print: a summary (default), the complete artifact, or the full report.
-o, --output DIR Also write a report bundle into this directory.
--privacy PRESET Privacy preset for printed and written output (default local).
--force Write into an existing directory that RepoDNA did not create.

Progress goes to standard error, so --format json > file captures only the artifact. Press Ctrl+C to cancel; exit code 130 means the analysis was cancelled.

repodna ci

Analyzes a repository and summarizes it for continuous integration, optionally failing the job.

repodna ci --fail-on warning
repodna ci --format github --fail-on critical
repodna ci --format markdown --summary-file "$GITHUB_STEP_SUMMARY"
repodna ci --baseline main.json --new-only --fail-on warning
repodna ci --baseline main.json --format json > pr-impact.json
repodna ci --baseline main.json --new-only --format sarif > pr-code-scanning.sarif
Option Meaning
--fail-on never|info|attention|warning|critical Exit with code 5 when findings at or above this severity exist (default never).
--baseline FILE Compare with a baseline artifact, for example one from the base branch.
--new-only With --baseline, fail only on findings the baseline does not have.
--format text|markdown|json|github|sarif github prints GitHub Actions annotations plus a text summary; sarif writes SARIF 2.1.0 JSON.
--summary-file FILE Also write the Markdown summary to this file.

Suppressed findings never fail the job. With --baseline --new-only --format github, only introduced active findings are emitted as GitHub annotations. Unchanged findings do not consume the 50-annotation limit, and severity filtering still applies. Without --new-only, annotations include all active findings at or above the chosen severity. See examples/ci for a complete workflow.

SARIF export: --format sarif emits an offline SARIF 2.1.0 document for explicit import into code-scanning tools. It exports active findings that have a valid repository-relative file location; repository-wide findings without a safe source file are omitted rather than assigned invented locations. A file-evidence line is included only when known. Severity maps to SARIF error (critical), warning (warning), and note (attention/info). Suppressions remain excluded, and --baseline --new-only restricts results to introduced active findings. The existing --fail-on exit policy still applies independently of the export format. All output stays local unless the user explicitly uploads it. SARIF titles and paths can contain sensitive repository context; inspect before upload. This exporter does not automatically upload reports or claim code-scanning compatibility beyond its documented SARIF subset.

With --baseline and --format json, RepoDNA retains the existing summary, failed, and failing fields and adds a structured changes object. Availability: changes.architecture.fileOwners ships in the published v1.5.0 stable CLI and versioned GitHub Action. The other documented baseline-delta fields predate this addition. For a step-by-step example and compatibility notes, see reviewing changes:

  • changes.files.added, removed, and modified: alphabetically ordered, repository-relative paths (not merely counts). A file is reported as modified only when both snapshots contain content hashes and those hashes differ; missing hashes are unknown, not evidence of modification. When an imported artifact repeats a path with conflicting or missing hashes, that path's hash is treated as unknown, regardless of record order. A rename appears as a removed path plus an added path, not as an inferred modification.
  • changes.findings.introduced and resolved: stable-ID, deduplicated records with id, rule, lower-case severity, title, and paths, ordered by descending severity and then finding ID. Since v1.5.0, duplicate IDs in imported artifacts use the highest-severity active variant (then a deterministic rule/title/path tie-break), including for --new-only --fail-on and baseline-limited workflow annotations. This prevents input order from masking a higher-severity introduced finding.
  • changes.architecture.touchedModules: modules owning files that differ between the two snapshots (using the most specific module directory boundary).
  • changes.architecture.fileOwners: a path-sorted record for each added, removed or modified file, containing path, baselineModule and currentModule. Module IDs are the closest analyzed boundaries in each snapshot. An added file has a null baselineModule, and a removed file has a null currentModule; null may also indicate no matching module. A modified file can show a module boundary change even when its repository-relative path is unchanged. The root module only owns files directly at the repository root.
  • changes.architecture.directDependents: modules directly depending on those touched modules in either analyzed snapshot; not transitive impact.
  • changes.architecture.moduleEdges.added and removed: deterministic from / to dependency relationships observed in one module graph but not the other (changes to edge weight alone are not reported).

The changes.architecture section is omitted when architecture data is unavailable in either snapshot. Module paths in removed files are resolved using the baseline; new files use the current analysis. A changed module is not evidence that its dependents require changes, or that the entire dependency graph was discovered.

For human-readable pull-request reviews, use repodna ci --baseline main.json --format markdown or supply --summary-file "$GITHUB_STEP_SUMMARY" with any CI format. The Markdown summary now contains a Baseline impact section showing file changes, introduced/resolved findings, touched modules, immediate dependents, and module edge changes when architecture was analyzed. Introduced and resolved findings include one associated file path when available and a count of additional paths. This is a review hint, not a verified evidence line; use structured JSON for the complete path list. Each detail list includes at most 10 entries plus an omitted-count indicator; repository-controlled text is escaped, and individual entries are clipped to 180 characters. The ordinary summary remains unchanged when no baseline is provided. This output may still contain private paths and finding titles: do not post it publicly without reviewing its contents. Since v1.5.0, the Markdown baseline impact also includes up to 10 per-file module-ownership entries.

An active finding that was suppressed in the baseline counts as introduced if it becomes active, including for --new-only --fail-on. Without a baseline the changes field is omitted. These outputs are deterministic snapshots, not proof that a change caused a finding. Paths and titles may be sensitive; review the JSON before posting it to a public PR or attaching it to a report.

Explore in the terminal

These commands print one part of an analysis. Each accepts a target, --format text|markdown|json (json prints the relevant part of the artifact), and --privacy.

Command Shows
repodna architecture Modules, dependencies between them, layers, cycles, and entry points
repodna dependencies Declared dependencies, lockfiles, and dependency signals
repodna history Commits, contributors, releases, activity, and quiet periods
repodna hotspots Files that change often and are complex, and why
repodna timeline Time Machine snapshots, epochs, events, and the project story
repodna findings Findings with their evidence

repodna findings also takes --severity info|attention|warning|critical (show that severity and above), --rule PREFIX (for example --rule security.), and --include-suppressed.

repodna show

Prints any sections of the report in the terminal.

repodna show --list
repodna show --section summary,tests,build
repodna show polyglot --section architecture --format markdown

--format is text or markdown; for JSON, use repodna report --format json. The sections are:

Identifier Section
cover Project DNA
summary Executive summary
identity Repository identity
languages Language map
structure Project structure
architecture Architecture
dependencies Dependencies
hotspots Code hotspots
complexity Complexity signals
duplication Duplication signals
tests Tests
build Build information
documentation Documentation
security Security signals
history Git history
contributors Contributor analytics
time-machine Codebase Time Machine
evolution Architectural evolution
findings Major findings
onboarding Onboarding guide
evidence Evidence appendix
metrics Raw metrics appendix
metadata Tool and version metadata

Reports and sharing

repodna report

Writes a report bundle (a directory with every format) or one format.

repodna report                                   # ./repodna-report/
repodna report ~/src/project -o project-report
repodna report --format html -o report.html
repodna report --format markdown --sections summary,architecture,findings
repodna report --format csv --table hotspots -o hotspots.csv
repodna report --format html --theme dark --privacy public -o public.html
Option Meaning
--format bundle|html|markdown|json|csv Default bundle.
-o, --output PATH A directory for bundles (default repodna-report), otherwise a file (default: standard output).
--theme professional|minimal|technical|dark HTML theme.
--privacy PRESET Privacy preset.
--sections IDS Comma-separated sections to include (default: all).
--no-branding Omit the RepoDNA credit line.
--table NAME CSV table: files, findings (default), metrics, hotspots, dependencies, contributors, or languages.
--force Replace files or write into a directory RepoDNA did not create.

A bundle contains index.html (a self-contained interactive page), report.md, repodna.json, dna-card.svg, dna-card.png, and a data/ directory with CSV tables. See reports.

repodna card

Writes the Project DNA card.

repodna card                          # dna-card.svg
repodna card --format png --dark -o dna-card-dark.png
repodna card --privacy public --no-branding

Options: --format svg|png (PNG is rendered at twice the size), --dark, --no-branding, -o FILE, --privacy, --force. See DNA cards.

repodna badge

Writes SVG badges and prints the Markdown to paste into a README.

repodna badge                          # all badges into ./badges/
repodna badge --kind languages -o docs/badges

--kind is all (default), dna, languages, architecture, activity, or tests.

repodna onboarding

Writes a developer onboarding guide as Markdown files.

repodna onboarding -o docs/onboarding

The guide (default directory repodna-onboarding) has a README.md and one file each for the overview, setup, architecture, important files, testing, dependencies, and recent changes.

repodna compare

Compares two or more repositories or analyses.

repodna compare ~/src/service-a ~/src/service-b
repodna compare before.repodna after.repodna --format html -o compare.html

Options: --format text|markdown|json|html, -o FILE, --theme, --privacy (applied to every analysis), --force.

repodna export and repodna import

export writes a stored analysis as a portable .repodna file (default privacy preset share); import stores an artifact on another machine.

repodna export polyglot                       # repodna-polyglot-<date>.repodna
repodna export . --privacy public -o public.repodna
repodna import public.repodna

Imported analyses are listed with the location imported:<name>.

AI explanations

repodna explain

Explains a repository with an optional AI provider. It is off until you configure a provider; see AI.

repodna explain --dry-run                      # show what would be sent; nothing is sent
repodna explain
repodna explain --about architecture
repodna explain --module crates/repodna-engine
repodna explain --hotspot src/app.rs
repodna explain --ask "Where is authentication handled?"
repodna explain --format json -o explanation.json
Option Meaning
--about repository|architecture|history|dependencies|onboarding What to explain.
--module PATH, --hotspot PATH, --ask QUESTION Explain one module, one file, or answer a question.
--dry-run Print the prompt, the evidence, and the size estimate without contacting any provider.
--allow-remote-ai Allow a provider that sends evidence off this machine, for this run.
--fresh Ask again instead of reusing a cached explanation.
--format text|markdown|json json includes provenance.
-o FILE, --force Write to a file.

Local storage

Command What it does
repodna list (alias ls) Lists stored repositories (--format text|json).
repodna clean TARGET Shows which stored analyses would be deleted; --yes deletes them. --all cleans every repository and --keep N keeps the newest N analyses of each.
repodna cache stats Shows storage and cache sizes.
repodna cache clear Clears the per-file analysis cache and cached explanations.
repodna cache repair Checks the database, sets a damaged one aside, and rebuilds the index from stored artifacts.
repodna cache reset --yes Removes the SQLite index and analysis cache, and clears cached explanations. Saved analysis JSON files are kept; repodna cache repair restores their index. 
repodna clean polyglot --keep 3          # dry run
repodna clean polyglot --keep 3 --yes

repodna cache reset --yes                # resets index, retains saved JSON
repodna cache repair                     # re-indexes saved JSON analyses
repodna clean --all --yes                # intentionally deletes saved analyses

Important: A cache reset is not an analysis deletion operation. Previously saved analysis artifacts remain on disk even while repodna list reports no indexed scans. Use clean for deliberate removal of saved analyses; cache clear only clears caches.

Repositories themselves are never touched. Storage locations are described in privacy.

Setup and diagnostics

Command What it does
repodna init [DIR] Writes a commented repodna.toml into a repository (--force replaces an existing one).
repodna config path Prints the path of your user configuration file.
repodna config init Creates your user configuration from a commented template.
repodna config show [DIR] Prints the effective configuration for a repository and where each value came from.
repodna config validate [DIR] Checks every configuration layer.
repodna plugins list Lists discovered plugins and whether they are enabled.
repodna plugins show NAME Shows a plugin's manifest and permissions.
repodna plugins enable NAME / disable NAME Changes your user configuration.
repodna plugins check DIR Validates a plugin directory without running it.
repodna plugins path Prints the user plugin directory.
repodna doctor Checks the installation, storage, Git, configuration, and plugins (--json). --export FILE also writes a diagnostics bundle for bug reports; see below.
repodna version Prints version information (--json).
repodna schema [artifact|config] Prints the JSON Schema of the artifact or of the configuration file.
repodna completions SHELL Prints a completion script for bash, elvish, fish, powershell, or zsh.

repodna doctor --export diagnostics.zip writes a ZIP file with the results of the checks, the environment (versions, operating system, and the environment variables RepoDNA reads), the effective configuration in the current directory, and summaries of storage and plugins. It contains no source code, file contents, analysis results, or names of stored repositories, and your home directory is shown as ~. Read it before you attach it to an issue; --no-project-config leaves out the current directory's repodna.toml. Like other outputs, it replaces an existing file only if RepoDNA wrote it, unless you pass --force.

repodna completions bash > ~/.local/share/bash-completion/completions/repodna
repodna completions zsh > "${fpath[1]}/_repodna"
repodna completions fish > ~/.config/fish/completions/repodna.fish

Web interface

repodna serve

Serves the web interface and a local API on 127.0.0.1 only.

repodna serve                 # http://127.0.0.1:7878
repodna serve --port 0        # pick a free port
repodna serve --no-scan       # browse stored analyses only

It prints a sign-in link that contains a session token; open that link. Options: --port PORT (default 7878), --web-dir DIR (serve the interface from a directory instead of the built-in files), --no-scan (do not allow starting analyses from the browser), and the analysis options above, which apply to analyses started from the browser. See the web interface.

Exit codes

Code Meaning
0 Success
1 Unexpected internal error
2 Invalid command-line usage
3 Input not found, unreadable, or unsupported
4 Invalid configuration
5 CI policy violated (findings at or above --fail-on)
6 Local storage could not be read or written
7 An external tool or service failed (Git, the network, an AI provider)
130 Cancelled (Ctrl+C)

Errors are printed with a hint: line when RepoDNA knows what to do next.

Environment variables

Variable Effect
REPODNA_HOME One directory for storage and the user configuration (useful for portable installs, CI, and tests).
REPODNA_GIT The Git executable to use (default: git on PATH).
NO_COLOR Disables color in auto mode.
SOURCE_DATE_EPOCH Used as the analysis time, so that repeated analyses of the same revision can produce identical artifacts (with --reproducible).