Skip to main content

Quickstart for Agents

A dense, copy-pasteable guide for AI agents and scripts. Every snippet runs verbatim. For the full flag list see the CLI Reference; for config file fields see the Configuration Reference.

Requirements​

  • Node.js 22 or later.
  • A package.json at the project root.

Install​

pnpm (recommended):

pnpm add -D nadle

npm:

npm install -D nadle

yarn:

yarn add -D nadle

Verify:

nadle --version

Minimal config​

Create nadle.config.ts at the project root:

import { tasks } from "nadle";

tasks
	.register("hello", async () => {
		console.log("Hello from Nadle!");
	})
	.config({ group: "Greetings", description: "Say hello" });

Register, depend, and run​

tasks.register(name, fn) defines a task; .config({ ... }) attaches metadata. Use dependsOn to order tasks — dependencies run first.

import { tasks } from "nadle";

tasks
	.register("build", async () => {
		console.log("Building...");
	})
	.config({ group: "CI", description: "Build the project" });

tasks
	.register("test", async () => {
		console.log("Testing...");
	})
	.config({ group: "CI", description: "Run tests", dependsOn: ["build"] });

Run a task (dependencies run automatically):

nadle test

Run several tasks in order:

nadle build test

Common invocations​

# Run one or more tasks (positional, in order)
nadle build test

# List every available task
nadle --list          # alias: nadle -l

# Show what would run without executing
nadle --dry-run test  # alias: nadle -m test

# Run only the tasks affected by changes since a git ref
nadle --since main test

# Statically explain why a task runs, what depends on it, and its inputs
nadle --explain test

# Print a summary of executed tasks at the end of the run
nadle --summary build test

# Use the compact, plain reporter built for agents and scripts
nadle --reporter agent build

# Print the task dependency graph instead of executing
nadle --graph

Next steps​