Viewing: docs.fallow.tools

CLI reference for fallow init. Generate a .fallowrc.json, .fallowrc.jsonc, or fallow.toml configuration file with schema support for editor autocomplete.

Create a configuration file for your project. The generated config includes a $schema field so your editor can provide autocomplete and validation.

Most projects dont need a config file. Fallow works out of the box by auto-detecting entry points and frameworks. Only create one if you need custom entry points, rules, or ignore patterns.

Fallows init command auto-detects your project setup and tailors the generated config accordingly:

TypeScript: Detects tsconfig.json and enables TypeScript-aware defaults
Monorepo: Detects workspace configurations (npm, yarn, pnpm) and includes workspace patterns
Frameworks: Detects installed frameworks (Next.js, Remix, Vite, etc.) and adds appropriate entry point patterns

fallow init

Options

Flag	Description
`--toml`	Generate `fallow.toml` instead of `.fallowrc.json`
`--agents`	Scaffold a starter `AGENTS.md` guide for coding agents, prefilled from detected project info
`--hooks`	Scaffold a pre-commit git hook that runs fallow on changed files. Alias for `fallow hooks install --target git`
`--branch <REF>`	Fallback base branch for the hook when no upstream is set (requires `--hooks`, default: `main`)
`--decline`	Record that this project deliberately stays unconfigured, so the first-contact setup hint and the `setup` next-step stop appearing. Writes no config file; idempotent

Agent guide scaffold

fallow init --agents writes a short starter AGENTS.md with project-overview, architecture, command, fallow workflow, and agent-rule prompts, plus a task-to-command matrix that routes common agent intents (deleting unused code, committing, prioritizing refactors, consolidating duplication) to the right fallow command. The matrix is the same one exposed as task_matrix in fallow schema. It refuses to overwrite an existing AGENTS.md, and it is guidance for agents, not a readiness score. When the project shape is reliably detectable, the scaffold prefills:

Install from the packageManager field in package.json, or pnpm install when pnpm-workspace.yaml is present
Test with the detected test framework (Vitest, Jest, or Playwright), but only when exactly one is present
Typecheck or lint with tsc --noEmit when tsconfig.json exists
Module boundaries with the workspace patterns for monorepos

Anything ambiguous stays blank rather than guessed: fallow never sniffs a package manager from lockfiles, leaves the test line empty when several frameworks are installed, and labels the workspace tool only when the packageManager field or pnpm-workspace.yaml proves it. Prefilled command lines carry an HTML provenance comment so you know to confirm them.

fallow init --agents

fallow agent install writes the same guide together with the skill, the MCP registration, and the commit/push gate for every harness it detects.

Pre-commit hook

Use the hooks namespace to scaffold a git hook that runs fallow audit against the base branch before each commit:

fallow hooks install --target git

fallow init --hooks remains available as a project-initialization shortcut. Fallow detects your hook manager and writes to the right location:

Husky adds to .husky/pre-commit
Lefthook adds to lefthook.yml
Bare hooks writes .git/hooks/pre-commit

The generated hook:

Includes a binary guard (command -v fallow) so commits still work when fallow isnt installed
Resolves the base ref at commit time: git merge-base @{upstream} HEAD when an upstream is set, falling back to the configured branch (or main) otherwise. Feature branches forked from a non-default integration branch (next-release / hotfix / LTS) compare against the right base, not against their own remote tracking branch
Runs fallow audit --base "$BASE" --quiet, which combines dead-code, complexity, and duplication analysis
Defaults to gate=new-only, so inherited findings on touched files do not block the commit; only findings introduced by the changeset fail the gate. Set [audit] gate = "all" in fallow.toml to fail on every finding in changed files
Returns exit code 1 on verdict: "fail" (default audit semantics); no --fail-on-issues is needed
Prints git commit --no-verify as the bypass option in the success message

Want to gate Claude Code or Codex agent commits as well? Use fallow hooks install --target agent for the agent enforcement path. The two hooks are complementary: fallow hooks install --target git catches human commits, fallow hooks install --target agent catches agent commits.

Custom base branch

By default, the hook compares against the merge-base of the current branchs upstream and HEAD, falling back to main when no upstream is set. Override the fallback with --branch:

fallow hooks install --target git --branch develop

Gitignore

fallow init automatically adds .fallow/ to your projects .gitignore. The .fallow/ directory contains machine-local data (parse cache, regression baselines, snapshots) that should not be committed.

If .gitignore exists and already contains .fallow/, nothing changes
If .gitignore exists without it, the entry is appended
If .gitignore doesnt exist, it is created

Output

The generated config includes a $schema field for IDE autocomplete. Editors like VS Code will provide inline validation and suggestions automatically.

By default, creates .fallowrc.json:

{
  "$schema": "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json",
  "rules": {}
}

With --toml, creates fallow.toml.

Configuration overview

Full reference for all configuration options.

Quickstart

Get started with fallow in under a minute.

Commands

fallow init

Options

Agent guide scaffold

Pre-commit hook

Custom base branch

Gitignore

Output

See also

Configuration overview

Quickstart

On this page