projd

projd scans a software project directory and prints a structured project report.

projd scan .
projd scan . --format terminal
projd scan . --format terminal --details
projd scan . --format terminal --style table
projd scan . --format terminal --style compact
projd scan . --format terminal --style plain
projd scan . --format terminal --style cinematic
projd tui .
projd tui . --snapshot
projd scan . --format terminal --no-unicode
projd scan . --format terminal --width 60 --color never
projd scan . --output report.md
projd scan . --format json
projd scan . --format json --output scan.json
projd scan . --output report.md --overwrite
projd scan ~/code --recursive
projd scan ~/code --recursive --include-kind cargo,npm
projd scan ~/code --recursive --format json
projd scan . --format html -o report.html
projd scan ~/code --recursive --format html -o monorepo.html
projd discover .
projd discover ~/code --include-kind cargo,npm
projd discover . --expand-workspaces
projd discover . --nested-vcs
projd discover . --format json
projd completion zsh
projd completion bash
projd completion zsh --print

When stdout is an interactive terminal, projd scan renders a table-first terminal report. When stdout is redirected or --output is used, Markdown and JSON remain stable for automation.

Terminal output has four styles:

• table: default human-readable report with structured tables.
• compact: table columns without box borders, useful for CI logs.
• plain: legacy line-oriented output with stable ASCII-friendly formatting.
• cinematic: static sci-fi HUD report for high-signal terminal screenshots and demos.

cinematic is intentionally static. It keeps the same scanner data and respects --color, --no-unicode, and --width, while rendering a neon-noir style header, signal matrix, language spectrum, telemetry grid, and alert feed.

projd tui <path> opens a full-screen live terminal HUD built with Ratatui and Crossterm. It animates the health core, signal matrix, language spectrum, telemetry grid, and alert feed from the same scan model. Keyboard controls are: q/Esc to quit, r to rescan, and Tab to rotate panel focus. Use projd tui <path> --snapshot to render one deterministic frame to stdout for tests, demos, or non-interactive terminals.

Shell completions are installed on demand:

projd completion zsh

This writes ~/.zfunc/_projd. If completion is not active yet, make sure your zsh config includes:

fpath=(~/.zfunc $fpath)
autoload -Uz compinit
compinit

Bash users can write:

projd completion bash

This writes ~/.local/share/bash-completion/completions/projd. Use projd completion <shell> --print when you need to inspect or redirect the generated script yourself.

The report aggregates repeated build systems, dependency ecosystems, code line statistics, and test commands so workspace scans stay compact.

The terminal report also shows source-control state, license type, and known CI providers detected by projd-core. Source control covers git, hg, svn, fossil, and bzr. Git, hg, and svn fill branch / revision / last-commit / dirty via the corresponding CLI; fossil and bzr currently only tag the kind.

projd-core now provides a shared project health summary with a grade, score, risk level, and signal evidence. The CLI renders that same model in terminal, Markdown, and JSON output so future GUI views do not need separate health logic.

By default, repeated risks are grouped by code and severity. Use --details to expand detail tables for CI files, dependency manifests, license paths, test sources, and individual risk findings.

Color output is semantic: headings, status values, bars, lockfile counts, and risk severities use different colors when --color enables ANSI output.

The scanner implementation lives in projd-core so the CLI and GUI share the same project model.

HTML report

projd scan and projd scan --recursive both support --format html, which emits a self-contained HTML document (embedded CSS, inline SVG charts, no JS, no external assets). Drop it on a static host, email it, or open it locally.

projd scan . --format html -o report.html
projd scan ~/code --recursive --format html -o monorepo.html

The report respects prefers-color-scheme, so it follows the OS dark/light theme automatically. Multi-project reports collapse each project into a <details> block; clicking expands the full per-project body.

Privacy: HTML reports embed scanned filesystem paths, VCS branch/revision, and (when --detailed-contributors is set) contributor names and emails. Treat the file the same way you would the JSON output.

VCS activity

Git repositories also report activity metrics: days since the last commit, commits in the last 90 days, contributor count, and the first commit date. A new Activity health signal labels the project active, stale, or dormant against 90-day / 365-day thresholds. Recursive scan output adds a Last Commit column showing relative age (12d, 6mo, 2y).

By default contributor names and emails are NOT collected; only the count is reported. Pass --detailed-contributors to opt in to a per-author breakdown (name, email, commit count). The flag is global to scan — it also applies under --recursive.

Recursive scanning

projd scan <path> --recursive first runs the discover engine and then scans every found root, producing a MultiProjectScan with one ProjectScan per root and an aggregated summary (by_kind, by_grade, by_risk_level, files_scanned). Terminal output prints a single compact table; pass --details to expand each root's full report. Markdown and JSON include all per-root data so downstream tools can iterate the roots array.

The single-project scan path also runs a cheap multi-root check and emits two new risks when applicable: multiple-vcs-roots-found (the scanned path actually contains more than one independent project) and nested-vcs-root (vendored or submodule VCS detected inside).

--style cinematic and the tui subcommand reject --recursive; the multi-project visualization will land in the desktop GUI rather than the TUI.

Discovering multiple projects

projd discover <path> walks a directory tree and lists every project root it finds (different VCS, build systems, documentation sites, datasets). Termination is driven by detected root kinds rather than depth, so pointing it at a folder that contains many independent repositories returns one entry per repository instead of aggregating them.

projd discover .
projd discover ~/code
projd discover . --include-kind cargo,npm,mdbook
projd discover . --min-confidence strong
projd discover . --expand-workspaces
projd discover . --nested-vcs
projd discover . --format json --output discover.json

Defaults:

• Cargo / npm / Gradle workspaces are reported as one root. Pass --expand-workspaces to also list each member.
• A VCS root stops descent at its own directory. Pass --nested-vcs to keep looking for vendored submodules or third-party repositories underneath it.
• --min-confidence defaults to medium, so documentation roots (mdBook, MkDocs, Jekyll, Sphinx, Docusaurus, Hugo, Gatsby, Astro, DocFx) are reported alongside strong build / VCS roots. Use strong to limit results to build and VCS roots only.
• --max-depth is a safety cap (default 8) for pathological filesystem structures; it is not the primary stop rule.