fallow: codebase intelligence for TypeScript and JavaScript

fallow coverage groups the paid Runtime Coverage workflow commands:

fallow coverage setup              # resumable first-run flow
fallow coverage analyze --cloud --repo owner/repo
fallow coverage upload-inventory   # push a static function inventory
fallow coverage upload-source-maps           # upload build source maps for bundled code

setup is the guided first-run path: license check, sidecar install, recipe generation, health handoff. It is intentionally resumable: run it once to bootstrap, follow the generated recipe, then run it again after traffic has been captured. analyze is the focused agent/CLI loop. Local mode reads a V8 or Istanbul artifact from disk. Cloud mode is explicit opt-in only and pulls the latest runtime facts for a repo before merging them with the current local AST/static analysis. upload-inventory is the CI step that unlocks the Untracked filter in the dashboard by pairing the runtime V8/Istanbul data (what actually ran) with the AST view of every function that exists. coverage upload-source-maps is the CI step for bundled/minified apps. It uploads build .map files so cloud runtime coverage can resolve bundle paths back to original source files.

`setup`

The setup flow performs four steps:

check license state
locate or install fallow-cov
write a framework-specific collection recipe to docs/collect-coverage.md
if coverage already exists, hand off directly to fallow health --runtime-coverage <path>

fallow coverage setup
fallow coverage setup --non-interactive
fallow coverage setup --yes
fallow coverage setup --yes --json
fallow coverage setup --yes --json --explain

Flags

Flag	Description
`-y, --yes`	Accept prompts automatically. Useful for local setup when you want fallow to continue without confirmation prompts.
`--non-interactive`	Print instructions instead of prompting. Useful in CI, remote shells, or agent workflows.
`--json`	Emit deterministic agent-readable setup instructions as JSON. Implies `--non-interactive` and does not prompt, write files, install packages, activate a license, or make network calls. Workspace projects emit a `members[]` array with one entry per runtime-bearing workspace (each with its own `framework_detected`, `runtime_targets`, `files_to_edit`, `snippets`, `dockerfile_snippet`); the top-level fields mirror the first emitted runtime member.
`--explain`	With `--json`, include a `_meta` block with field definitions, enum values, warning semantics, and this docs URL.

What setup detects automatically

fallow coverage setup inspects package.json, lockfiles, and scripts to tailor the instructions:

Detection	Purpose
Framework	Chooses a recipe for Next.js, NestJS, Nuxt, SvelteKit, Astro, Remix, Vite browser apps, plain Node services, or a generic fallback. When both a Node-server framework (Elysia, Hono, Fastify, Express, Koa, `@trpc/server`) and Vite appear in the same `package.json`, the Node-server framework wins so the recipe targets the API rather than the bundled client.
Workspace topology	Walks `workspaces` (npm/pnpm/yarn/bun) and emits one recipe per runtime-bearing member. Library-only workspaces (no `start`/`preview`/`dev` script and no Node-server dependency) are skipped. The top-level `runtime_targets` array is the union (`["node"]`, `["browser"]`, or `["node", "browser"]`) across all members.
Package manager	Uses `packageManager`, lockfiles, or both to choose install commands for npm, pnpm, yarn, or bun.
Coverage artifact	Detects existing `coverage/coverage-final.json`, `.nyc_output/coverage-final.json`, or JSON-containing V8 directories.
Sidecar binary	Resolves `FALLOW_COV_BIN`, `FALLOW_COV_BINARY_PATH`, project-local shims, package-manager bin lookups, `~/.fallow/bin/fallow-cov`, and `PATH`.

If the project does not match a built-in framework recipe, fallow still writes a fallback docs/collect-coverage.md with a link to the public coverage docs for manual setup.

Agent-readable JSON

fallow coverage setup --yes --json is the agent-driven entry point. The payload is deterministic, side-effect-free, and stable across reruns. Add --explain when the consumer needs in-payload documentation: it adds optional _meta.field_definitions, _meta.enums, _meta.warnings, and _meta.docs_url keys without changing schema_version. On a workspace monorepo (Elysia API at root + two Vite browser apps in dashboard/ and site/):

{
  "schema_version": "1",
  "framework_detected": "plain_node",
  "package_manager": "bun",
  "runtime_targets": ["node", "browser"],
  "members": [
    {
      "name": "fallow-cloud",
      "path": ".",
      "framework_detected": "plain_node",
      "runtime_targets": ["node"],
      "files_to_edit": [{"path": "src/index.ts", "reason": "..."}],
      "snippets": [{"label": "Node entrypoint", "path": "src/index.ts", "content": "..."}],
      "dockerfile_snippet": "ENV FALLOW_TRANSPORT=fs\nENV FALLOW_WRITE_TO_DIR=/tmp/fallow-coverage",
      "warnings": []
    },
    {
      "name": "fallow-dashboard",
      "path": "dashboard",
      "framework_detected": "vite",
      "runtime_targets": ["browser"],
      "files_to_edit": [{"path": "dashboard/src/main.ts", "reason": "..."}],
      "snippets": [{"label": "Vite browser entry", "path": "dashboard/src/main.ts", "content": "..."}],
      "dockerfile_snippet": null,
      "warnings": []
    }
  ],
  "config_written": null,
  "commands": ["bun add @fallow-cli/beacon", "bun add -d @fallow-cli/fallow-cov"],
  "files_to_edit": [{"path": "src/index.ts", "reason": "..."}],
  "snippets": [{"label": "Node entrypoint", "path": "src/index.ts", "content": "..."}],
  "dockerfile_snippet": "ENV FALLOW_TRANSPORT=fs\nENV FALLOW_WRITE_TO_DIR=/tmp/fallow-coverage",
  "next_steps": [...],
  "warnings": []
}

framework_detected uses canonical ids (nextjs, nestjs, nuxt, sveltekit, astro, remix, vite, plain_node, unknown). Top-level fields mirror the first emitted runtime member (the root when the root itself is a runtime app, otherwise the first runtime workspace), so on a browser-rooted monorepo with a Node child agents should read each member’s dockerfile_snippet rather than the top-level one. Single-app projects emit a members array of length 1 (path "."), so consumers can treat members[] uniformly. Aggregator-only repos (workspaces whose only runtime indicator is a Turbo/Nx-style dev script delegating to children, plus build-only library packages) are not runtime-bearing and emit an empty payload: framework_detected: "unknown", runtime_targets: [], members: [], plus a warnings entry of "No runtime workspace members were detected; emitted install commands only.". Agents can branch on members.length === 0 (or framework_detected === "unknown") to detect this case and skip the snippet-application step.

Generated recipe

The generated docs/collect-coverage.md recipe typically looks like:

Remove any old dump directory: rm -rf ./coverage
Build the app
Start the app with NODE_V8_COVERAGE=./coverage ...
Exercise the routes or jobs you care about
Stop the app and run: fallow coverage setup

Framework-aware script selection means fallow prefers existing build, start, or preview scripts when they exist and falls back to common framework commands otherwise.

Typical flow

fallow license activate --trial --email you@company.com
fallow coverage setup

# Follow docs/collect-coverage.md, then:
fallow coverage setup

On the second run, if coverage is present, setup runs the actual analysis for you:

fallow health --runtime-coverage ./coverage

`analyze`

Use local mode when you have a coverage artifact on disk:

fallow coverage analyze --runtime-coverage ./coverage --format json

Use cloud mode when you want the latest fallow.cloud runtime context for a repo:

FALLOW_API_KEY=fallow_live_... \
  fallow coverage analyze --cloud --repo owner/repo --format json

FALLOW_API_KEY alone never selects cloud mode. You must pass --cloud, --runtime-coverage-cloud, or set FALLOW_RUNTIME_COVERAGE_SOURCE=cloud.

Analyze flags

Flag	Description
`--runtime-coverage <PATH>`	Local V8 directory, V8 JSON file, or Istanbul coverage map. Mutually exclusive with cloud mode.
`--cloud`, `--runtime-coverage-cloud`	Explicitly fetch cloud runtime facts from `/v1/coverage/:repo/runtime-context`.
`--repo <OWNER/REPO>`	Repository to fetch in cloud mode. Falls back to `$FALLOW_REPO`, then parsed `origin`. Slashes are URL-encoded as one route segment.
`--api-key <KEY>`	Fallow cloud bearer token. Falls back to `$FALLOW_API_KEY`, but only after explicit cloud opt-in.
`--api-endpoint <URL>`	Override the API base URL. Useful for staging and on-prem deployments.
`--coverage-period <DAYS>`	Cloud observation window, 1 through 90 days. Default: 30.
`--project-id <ID>`	Optional monorepo/project discriminator.
`--environment <NAME>`	Optional cloud environment filter.
`--commit-sha <SHA>`	Optional cloud commit filter.
`--top <N>`	Show only the top N runtime findings, hot paths, blast-radius entries, and importance entries. Truncation happens before rendering, so it propagates to JSON, human, and cloud-merge output equally.
`--blast-radius`	Show the first-class blast-radius section in human output. JSON always includes `runtime_coverage.blast_radius` whenever runtime coverage analysis runs.
`--importance`	Show the first-class importance section in human output. JSON always includes `runtime_coverage.importance` whenever runtime coverage analysis runs.
`--production`	Run analyze in production mode, matching `fallow health --production`. Filters out test files and dev-only code paths before merging runtime data.
`--min-invocations-hot <N>`	Hot-path classification threshold. Functions invoked at least N times during the captured window are classified as hot. Default: 100. Mirrors the same flag on `fallow health --runtime-coverage`.
`--min-observation-volume <N>`	Minimum total trace volume before high-confidence `safe_to_delete` / `review_required` verdicts. Below this the sidecar caps confidence at `medium`. Default: 5000.
`--low-traffic-threshold <RATIO>`	Fraction of total trace count below which an invoked function is classified `low_traffic` rather than `active`. Decimal form (`0.001` = 0.1%). Default: 0.001.
`--explain`	With `--format json`, attach a top-level `_meta` block with field definitions, enum values (`data_source`, `test_coverage`, `v8_tracking`, `action_type`, etc.), warning-code documentation, and the docs URL.

Cloud analysis emits the same runtime_coverage JSON block as local mode. Its summary includes data_source: "cloud", last_received_at, and capture_quality derived from the pulled runtime window. Cloud functions that cannot be matched to the local AST/static index are omitted from findings and reported through a cloud_functions_unmatched warning. Each finding’s actions[].type uses the canonical kebab-case vocabulary: delete-cold-code is emitted on verdict=safe_to_delete, review-runtime on verdict=review_required. The sidecar may emit additional protocol-specific identifiers, so consumers should treat unknown values as forward-compat extensions rather than schema violations.

Sidecar installation

If fallow-cov is missing, setup tells you exactly what it checked and suggests the correct install command for your package manager, for example:

pnpm add -D @fallow-cli/fallow-cov

You can also bypass auto-discovery by setting either explicit-override env var to a binary path. Resolution order is FALLOW_COV_BIN first, then FALLOW_COV_BINARY_PATH, then project-local auto-discovery. Both fail hard with a clear error if the configured path does not exist (they never silently fall through to the next step). FALLOW_COV_BINARY_PATH exists for air-gapped enterprise installs, Linux distro-packaged sidecars, and Docker multi-user setups where ~/.fallow/bin is not writable.

Sidecar signature verification

Every sidecar spawn runs an Ed25519 signature check against the compiled-in public key. The sidecar binary must ship with an adjacent <binary>.sig file. A missing, wrong-length, or invalid signature fails hard with exit code 4 rather than executing an unverified binary. There is no warn-and-run mode and no opt-out env var. If verification fails, install the signed distribution:

pnpm add -D @fallow-cli/fallow-cov

`upload-inventory`

fallow coverage upload-inventory walks every JS/TS source in the project and POSTs a static function inventory (one row per declaration, expression, arrow, or method) to fallow cloud. The server computes inventory − runtime-seen = untracked for the matching git SHA, which lights up the dashboard’s Untracked filter. This is the only fallow subcommand that does network I/O outside of fallow license. check, dupes, and health stay offline.

fallow coverage upload-inventory \
  --api-key $FALLOW_API_KEY \
  --project-id acme/web

Defaults and inference

Flag	Default
`--api-key`	`$FALLOW_API_KEY`
`--api-endpoint`	`$FALLOW_API_URL` or `https://api.fallow.cloud`
`--project-id`	`$GITHUB_REPOSITORY`, then `$CI_PROJECT_PATH`, then `git remote get-url origin` parsed to `owner/repo`
`--git-sha`	`git rev-parse HEAD`

Flags

Flag	Description
`--api-key <KEY>`	Fallow cloud bearer token. Prefer `$FALLOW_API_KEY` on shared CI runners: passing secrets on the command line may be visible to other processes via `ps` and can leak into shell history or process audit logs.
`--api-endpoint <URL>`	Override the base URL. Useful for staging and on-prem deployments.
`--project-id <OWNER/REPO>`	Project identifier, `owner/repo` form.
`--git-sha <SHA>`	Commit SHA this inventory is keyed to. Max 64 chars; `[A-Za-z0-9._-]` only.
`--allow-dirty`	Silence the warning when the working tree has uncommitted changes.
`--exclude-paths <GLOB>`	Additional globs to skip, applied after the configured fallow ignore rules. Repeatable.
`--path-prefix <PREFIX>`	Prefix prepended to every emitted `filePath` so the static inventory matches the path shape the runtime beacon reports. Required for containerized deployments: the beacon reports V8’s absolute path inside the container (e.g. `/app/src/foo.ts`) while the walker emits repo-relative paths (`src/foo.ts`) by default. Must start with `/` and use POSIX separators. Common values: `/app` (typical Dockerfile), `/workspace` (Buildpacks / Cloud Run), `/usr/src/app` (older Node images), `/var/task` (Lambda), `/home/runner/work/<repo>/<repo>` (GitHub Actions).
`--with-callers`	Also upload importer edges (which modules import each declaration) alongside the inventory, so the dashboard can surface caller reach for untracked code. The inventory rows also carry per-function complexity and per-file churn.
`--dry-run`	Print what would be uploaded and exit. No network call.
`--ignore-upload-errors`	Treat upload failures as warnings (exit 0). Validation errors still fail hard.

Function naming

Inventory entries use names that match oxc-coverage-instrument byte-for-byte so the runtime join succeeds. Precedence:

Parent context (method key, variable binding, property key, export default).
The function’s own id (function foo() {}, named function expression).
(anonymous_N) where N is a file-scoped monotonic counter.

TypeScript declaration files (*.d.ts, *.d.mts, *.d.cts, *.d.tsx) and overload signatures with no body are intentionally skipped: they have no runtime footprint, so including them would pollute the dashboard with permanently untracked entries.

Path prefix (containerized deployments)

The runtime beacon reports V8’s filePath as it sees it at runtime. In a container, that is the path inside the image (e.g. /app/src/foo.ts when the Dockerfile sets WORKDIR /app). The static inventory walker, running in CI against the checkout, emits repo-relative paths (src/foo.ts) by default. The server joins runtime and inventory on the exact (filePath, functionName) pair; if the two sides don’t share a prefix shape, the Untracked filter never lights up and the dashboard surfaces a mismatched state. The fix: pass --path-prefix matching your deployed WORKDIR:

fallow coverage upload-inventory --path-prefix /app

Common values by deployment target:

Target	Prefix
Docker image with `WORKDIR /app` (most Node services)	`/app`
Cloud Run / Buildpacks	`/workspace`
Older official Node images	`/usr/src/app`
AWS Lambda	`/var/task`
GitHub Actions default checkout	`/home/runner/work/<repo>/<repo>`

After upload, the server samples up to 100 recent runtime rows and reports the overlap with the inventory. The CLI prints a yellow warning if overlap < 50% with an example mismatch, and the dashboard renders a configuration-needed state on the repo detail page until the prefix is corrected.

Exit codes

Code	Meaning	When it fires
`0`	ok	Upload succeeded, or `--dry-run`, or `--ignore-upload-errors` downgraded a transient failure.
`7`	network	DNS, TLS, connect, or transport failure.
`10`	validation	Missing API key, unresolvable project-id, zero functions in walk.
`11`	payload too large	Inventory exceeds the server’s 200,000-function cap. Scope with `--exclude-paths`.
`12`	auth rejected	401 / 403 from the server. Rotate the token or widen its scope.
`13`	server error	5xx after retries, or other non-2xx status.

Example CI job (GitHub Actions)

- name: Upload function inventory to fallow cloud
  run: |
    npx fallow coverage upload-inventory
  env:
    FALLOW_API_KEY: ${{ secrets.FALLOW_API_KEY }}

Dry-run output

fallow coverage upload-inventory (dry run)
  project-id:    acme/web
  git-sha:       a1b2c3d4e5f6...
  functions:     14,280
  endpoint:      https://api.fallow.cloud/v1/coverage/acme/web/inventory

first 5 of 14,280 entries:
  src/index.ts:1   bootstrap
  src/index.ts:12  (anonymous_1)
  src/user.ts:3    createUser
  src/user.ts:18   default
  src/user.ts:42   (anonymous_5)
  ... and 14,275 more

`coverage upload-source-maps`

fallow coverage upload-source-maps scans a build output directory for source maps and POSTs each map to fallow cloud under the current repo and git SHA. The production beacon reports coverage against deployed bundles; uploaded source maps let the cloud resolver remap those bundle positions back to original source files.

FALLOW_API_KEY=fallow_live_... \
  fallow coverage upload-source-maps --dir dist --repo my-app --git-sha "$GITHUB_SHA"

Source-map defaults

Flag	Default	Description
`--dir <PATH>`	`dist`	Directory scanned recursively. Relative paths resolve from the project root.
`--include <GLOB>`	`*/.map`	Include glob, matched relative to `--dir`.
`--exclude <GLOB>`	`/node_modules/`	Exclude glob, repeatable.
`--repo <NAME>`	`package.json` `repository.url`, then `git remote get-url origin` parsed to `owner/repo`	Repo identifier used in `/v1/coverage/:repo/source-maps`. Must match the beacon’s `projectId` (and the `--project-id` passed to `upload-inventory`); pass `--repo <bare-name>` explicitly if your beacon reports a bare name.
`--git-sha <SHA>`	`$GITHUB_SHA`, `$CI_COMMIT_SHA`, `$COMMIT_SHA`, then `git rev-parse HEAD`	Commit SHA the beacon will report for the deployed build. Must be 7-40 hex chars.
`--endpoint <URL>`	`$FALLOW_API_URL` or `https://api.fallow.cloud`	Override for staging or enterprise deployments.
`--strip-path <BOOL>`	`true`	Upload only the basename as `fileName`, e.g. `dist/assets/app.js.map` -> `app.js.map`. Set `--strip-path=false` when runtime coverage reports bundle paths with directories, e.g. `assets/app.js`.
`--dry-run`	`false`	Print what would upload without reading `FALLOW_API_KEY` or making network calls.
`--concurrency <N>`	`4`	Parallel upload fanout.
`--fail-fast`	`false`	Stop on the first failed map instead of uploading the rest and reporting a partial-failure summary.

The API key comes only from FALLOW_API_KEY; there is intentionally no --api-key flag, so secrets do not land in shell history or process lists. Set FALLOW_CA_BUNDLE=/path/to/bundle.pem when CI needs a custom PEM trust bundle for fallow cloud. The bundle replaces the default WebPKI roots, so private-CA environments should pass a complete bundle containing public roots plus the private CA. Relative bundle paths resolve from the process working directory. Uploads retry network failures, HTTP 429, and HTTP 502/503/504 up to three attempts. HTTP 429 honors Retry-After delta seconds and HTTP-date values, capped at 60 seconds. Setup or transport failures that prevent every map from uploading exit 7; mixed per-map failures still exit 1.

Source-map CI snippets

GitHub Actions
GitLab CI
CircleCI

- name: Build
  run: npm run build

- name: Upload source maps to fallow
  run: npx fallow coverage upload-source-maps --dir dist --git-sha "$GITHUB_SHA"
  env:
    FALLOW_API_KEY: ${{ secrets.FALLOW_API_KEY }}

upload_source_maps:
  stage: deploy
  script:
    - npm run build
    - npx fallow coverage upload-source-maps --dir dist --git-sha "$CI_COMMIT_SHA"
  variables:
    FALLOW_API_KEY: $FALLOW_API_KEY

- run: npm run build
- run:
    name: Upload source maps to fallow
    command: npx fallow coverage upload-source-maps --dir dist --git-sha "$CIRCLE_SHA1"

Source-map failure modes

Exit	Meaning
`0`	All maps uploaded, or dry-run completed.
`1`	Partial or full upload failure, including invalid JSON maps, auth rejection, rate limits, server errors, or exhausted network retries.
`2`	Bad invocation: missing `FALLOW_API_KEY`, unresolvable repo/SHA, missing directory, or zero maps found.

License commands

Start a trial, refresh a token, or inspect feature status.

Runtime coverage

Learn what runtime coverage adds and how it differs from static reachability.

Commands

fallow coverage

`setup`

Flags

What setup detects automatically

Agent-readable JSON

Generated recipe

Typical flow

`analyze`

Analyze flags

Sidecar installation

Sidecar signature verification

`upload-inventory`

Defaults and inference

Flags

Function naming

Path prefix (containerized deployments)

Exit codes

Example CI job (GitHub Actions)

Dry-run output

`coverage upload-source-maps`

Source-map defaults

Source-map CI snippets

Source-map failure modes

See also

License commands

Runtime coverage

​setup

​Flags

​What setup detects automatically

​Agent-readable JSON

​Generated recipe

​Typical flow

​analyze

​Analyze flags

​Sidecar installation

​Sidecar signature verification

​upload-inventory

​Defaults and inference

​Flags

​Function naming

​Path prefix (containerized deployments)

​Exit codes

​Example CI job (GitHub Actions)

​Dry-run output

​coverage upload-source-maps

​Source-map defaults

​Source-map CI snippets

​Source-map failure modes

​See also

License commands

Runtime coverage

`setup`

Flags

What setup detects automatically

Agent-readable JSON

Generated recipe

Typical flow

`analyze`

Analyze flags

Sidecar installation

Sidecar signature verification

`upload-inventory`

Defaults and inference

Flags

Function naming

Path prefix (containerized deployments)

Exit codes

Example CI job (GitHub Actions)

Dry-run output

`coverage upload-source-maps`

Source-map defaults

Source-map CI snippets

Source-map failure modes

See also