[!IMPORTANT] Dawnfall is local-first and free. No servers, no accounts, no telemetry. Everything runs on your machine.

[!WARNING] Dawnfall is under active development. Flags and output may change. Not recommended for production CI pipelines yet.

Table of Contents

• Why Dawnfall?
• Features
• Installation
• Quick Start
• How It Works
• Development Setup

Why Dawnfall?

You work on projects with package.json scripts, pyproject.toml commands, deno.json tasks, or Cargo.toml scripts. Remembering which project has which command is a hassle. cd into each directory and run npm run build manually? There's a better way.

Dawnfall scans your entire project tree, discovers every runnable command, and presents them in an interactive TUI. Pick what you want, choose a mode: parallel, sequential, or copy to clipboard: and let Dawnfall handle the rest. No more digging through package.json files.

Features

• 🔍 Auto-discovery: scans package.json, pyproject.toml, deno.json, composer.json, Cargo.toml, project.godot — plugin-driven, easy to extend
• ⚡ Parallel & Sequential: run commands all at once or one by one
• 📋 Copy modes: copy commands as multi-line list or single chain (shell-aware separators, directory prefix for monorepos)
• 📦 Cache: --use-cache saves scan results for instant re-runs
• 📂 Monorepo aware: scans every package in the tree and exposes turbo.json pipeline/tasks
• 🛡️ Destructive guard: confirms before running clean/reset/delete commands
• 🌐 Remote repos: clone + scan GitHub repos on the fly (dawnfall --remote owner/repo)
• ⚙️ Configurable: .dawnfall/config.json for cache settings and .dawnfall/profiles.json for launch profiles

Installation

Global install (recommended)

npm install -g dawnfall

Then run from any project:

cd my-project
dawnfall

Run without installing

npx dawnfall

From source (development)

git clone https://github.com/divyanshudhruv/dawnfall.git
cd dawnfall
npm install
npm run build
npm link

Quick Start

cd my-project
dawnfall          # if installed globally
npx dawnfall      # without installing

Pick commands from the interactive list, choose a mode, and go.

| Flag | What it does | | --------------------------- | --------------------------------------------- | | dawnfall | Scan + select + run interactively | | dawnfall --use-cache | Load/save scan results from cache | | dawnfall --fresh | Force full re-scan | | dawnfall --no-write | Run without creating any files or directories (ephemeral) | | dawnfall --json | Output results as JSON | | dawnfall --version / -v | Show version | | dawnfall --help / -h | Show help | | dawnfall --remote owner/repo | Clone GitHub repo + scan + show commands (view-only, ephemeral) | | dawnfall clean | Delete the .dawnfall directory (cache, workflow, profiles) |

For the full reference, see docs/commands.md.

How It Works

Local flow

flowchart TD
    A[Start] --> B{Cache?}
    B -->|Yes, fresh| C[Load from .dawnfall/cache.json]
    B -->|No/stale| D[Run scanners]
    D --> E[Save to cache]
    C --> F[Select commands]
    E --> F
    F --> G{Mode}
    G -->|Parallel| H[Spawn all at once]
    G -->|Sequential| I[Run one by one]
    G -->|Copy listed| J[Clipboard: multi-line]
    G -->|Copy chained| K[Clipboard: && chain]
    H --> L[Execute]
    I --> L
    J --> L
    K --> L
    L --> M[Show results]

Remote repo flow

sequenceDiagram
    participant U as dawnfall --remote owner/repo
    participant T as Temp dir
    participant G as GitHub
    participant S as Scanners
    G-->>T: git clone
    T->>S: scan cloned repo
    S->>U: show available commands
    U->>T: delete temp dir

Tips

• .dawnfall/config.json: enable cache by default and set its TTL
• .dawnfall/profiles.json: define launch profiles to skip command selection entirely
• dawnfall --use-cache: use for fast re-runs; combine with --fresh to force re-scan
• dawnfall --json: pipe output to other tools: dawnfall --json | jq '.[].name'
• dawnfall clean: delete the .dawnfall directory for a clean slate; combine with --fresh (dawnfall clean && dawnfall --fresh) to skip profile and workflow re-run prompts and force a full re-scan
• Background processes: in Parallel mode, long-running commands (dev, watch, serve) auto-background and are shown as (background); in Sequential mode they are skipped as (long-running)
• NO_COLOR: set NO_COLOR=1 to disable colored output
• Monorepos: every package in the tree is scanned; turbo.json pipeline and tasks appear as runnable commands
• Remote repos: pass --remote owner/repo to clone and scan without leaving the terminal. It is view-only: it lists the repo's available commands but never runs or selects them, and never touches your cache, workflow, or recent-projects list. The temp clone is deleted when Dawnfall exits, including on Ctrl+C

Development Setup

git clone https://github.com/divyanshudhruv/dawnfall.git
cd dawnfall
npm install

Build and test:

npm run build          # build the CLI (tsup)
npm test               # run vitest test suite
npm run typecheck      # TypeScript type checking
npm run lint           # Biome lint
npm run format         # Biome format
npm run dev            # watch mode for development

Before contributing, see CONTRIBUTING.md.

The test suite creates temp directories for filesystem tests: no clean-up needed.