Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.fallow.tools/llms.txt

Use this file to discover all available pages before exploring further.

Add a health badge to your README to show your project’s code health at a glance. 
fallow health --format badge > badge.svg
The badge displays the letter grade and numeric score in shields.io flat style:
zod: B (71)preact: B (76)svelte: B (73)vite: C (65)
Grades: A (≥85, green) · B (70–84, green) · C (55–69, yellow) · D (40–54, orange) · F (<40, red).

​
Hosting the badge

The SVG needs a stable URL for your README to reference. Three options, from simplest to most robust:

​
Option 1: Commit to your repo

Generate the badge and commit it directly: 
fallow health --format badge > .github/badges/health.svg
git add .github/badges/health.svg
git commit -m "chore: update health badge"
Then reference it in your README: 
![fallow health](./github/badges/health.svg)
This is the simplest approach but the badge only updates when you regenerate and commit. Add a step to your CI workflow that generates the badge and publishes it to a badges branch: 
- name: Generate health badge
  run: fallow health --format badge > badge.svg

- name: Publish badge
  uses: peaceiris/actions-gh-pages@v4
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: .
    publish_branch: badges
    keep_files: true
    include_files: badge.svg
Then reference the badge from the badges branch:
![fallow health](https://raw.githubusercontent.com/your-org/your-repo/badges/badge.svg)

​
Option 3: Shields.io endpoint

If you prefer dynamic badges via shields.io, generate a JSON endpoint file instead: 
fallow health --format json --score --quiet 2>/dev/null \
  | jq '{schemaVersion: 1, label: "fallow", message: "\(.health_score.grade) (\(.health_score.score | floor))", color: (if .health_score.score >= 85 then "brightgreen" elif .health_score.score >= 70 then "green" elif .health_score.score >= 55 then "yellow" elif .health_score.score >= 40 then "orange" else "red" end)}' \
  > health-badge.json
Host the JSON file (e.g., in a Gist or on the badges branch) and use the shields.io endpoint badge: 
![fallow health](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/your-org/your-repo/badges/health-badge.json)
This keeps the badge rendering on shields.io’s CDN and always shows the latest score.

​
Monorepo badges

For workspace packages, scope the badge with --workspace: 
fallow health --format badge --workspace my-package > badges/my-package.svg

​
Technical details

  • Self-contained SVG with embedded Verdana font metrics. No external requests
  • Unique element IDs per badge, so you can inline multiple badges on one page
  • --format badge automatically enables --score (no need to pass both)
  • Exit code 2 with an error message if the score cannot be computed
  • Also available via the FALLOW_FORMAT=badge environment variable