# projd
`projd` scans a software project directory and prints a structured project
report.
```bash
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 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:
```bash
projd completion zsh
```
This writes `~/.zfunc/_projd`. If completion is not active yet, make sure your
zsh config includes:
```bash
fpath=(~/.zfunc $fpath)
autoload -Uz compinit
compinit
```
Bash users can write:
```bash
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.
## 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.
```bash
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.