nap

Not Another Perl tool — an all-in-one Perl developer toolkit written in Rust.

Like Bun for JavaScript or uv for Python, nap replaces a dozen separate tools with a single fast binary: package manager, test runner, formatter, linter, REPL, documentation generator, and more.

$ nap install           # install from cpanfile (or lockfile)
$ nap test              # parallel tests with native TAP parser
$ nap fmt               # format with perltidy
$ nap lint              # lint with perlcritic
$ nap repl              # interactive Perl session
$ nap doc               # generate HTML docs and open in browser
$ nap audit             # check deps for known CVEs
$ nap check             # fmt --check + lint + test in one shot

Installation

Requires Rust and a Perl installation (5.38, 5.40, or 5.42).

# Build from source
cargo install --path .

# Or build against a specific Perl
NAP_PERL=/path/to/perl cargo install --path .

For full functionality, install these CPAN modules in your target Perl:

cpanm --notest Module::CPANfile Perl::Tidy Perl::Critic App::perlimports

Shell completions

# Bash
eval "$(nap completions bash)"

# Zsh
eval "$(nap completions zsh)"

# Fish
nap completions fish | source

Quick start

# Create a new project
nap new my-app

# Or from a framework template
nap new my-api --template mojo
nap new my-web --template dancer

# Enter the project
cd my-app

# Add dependencies
nap add Moo
nap add Test::Fatal --test

# Install everything
nap install

# Run tests
nap test

# Format and lint
nap fmt
nap lint

# Generate docs
nap doc

Commands

Command	Description	Details
init	Initialize a project in the current directory
new	Create a project from a template	--template mojo|dancer|catalyst|module|gh:user/repo
install	Install dependencies	Uses lockfile if present
add	Add a dependency to cpanfile	--test, --dev for phase targeting
remove	Remove a dependency from cpanfile
update	Update deps to latest compatible versions
outdated	Show deps with newer versions on CPAN
tree	Show dependency tree by phase
lock	Generate deterministic lockfile	SHA256 hashes from MetaCPAN
sync	Install from lockfile exactly
fmt	Format with Perl::Tidy	--check for CI
lint	Lint with Perl::Critic	-s severity 1-5
imports	Manage imports with perlimports	--check for CI
check	Run fmt --check + lint + test	Single CI command
test	Run tests with native TAP parser	Full prove parity
run	Execute a Perl script	Adds -Ilib automatically
repl	Interactive Perl REPL	Readline, multi-line, heredocs
doc	Generate HTML documentation	Powered by perldoc-open
info	Show module info from MetaCPAN	Author, version, deps
search	Search MetaCPAN
audit	Check deps for known CVEs	Uses CPANSA database
bundle	Bundle project + deps for deployment	--archive, -O, --single-file
cache	Manage download cache	cache info, cache clean
completions	Generate shell completions	bash, zsh, fish, powershell

Configuration

cpanfile

nap uses the standard cpanfile format for declaring dependencies:

requires 'Moo', '2.0';
requires 'JSON::XS';

on 'test' => sub {
    requires 'Test::More', '0.98';
};

nap.toml

Optional project-level configuration:

[project]
name = "My-Project"

[workspace]
members = ["packages/*"]

[fmt]
perltidy_profile = ".perltidyrc"

[lint]
severity = 3

[test]
jobs = 8

See docs/WORKSPACE.md for monorepo support.

How it works

nap embeds a real Perl interpreter via FFI — it doesn't shell out to perl for formatting, linting, config parsing, or the REPL. This means:

• Fast: no process spawning overhead for each operation
• Correct: uses the real Perl::Tidy, Perl::Critic, Module::CPANfile
• Parallel: with MULTIPLICITY, multiple interpreters run in parallel for fmt/lint/imports

For dependency resolution, nap uses the PubGrub SAT solver (same algorithm as Dart's pub) with a BFS crawl of MetaCPAN's API.

Security

• SHA256 checksum verification on all tarball downloads
• Path traversal and symlink protection in tarball extraction
• Download URLs validated against trusted CPAN hosts (HTTPS only)
• Template input sanitization prevents shell injection
• HTTP timeouts prevent indefinite hangs

See docs/ARCHITECTURE.md for the full technical deep-dive.

Perl version support

nap supports all currently maintained Perl versions:

Version	Support
5.42	Full
5.40	Full
5.38	Security only (until Jul 2026)

See docs/PERL_VERSION_SUPPORT.md for policy details.

Documentation

• Architecture — how nap works under the hood
• Perl interop — the embedded interpreter and C shim
• Testing — TAP parser, prove parity, watch mode
• REPL — interactive Perl with heredoc support
• Templates — extensible project scaffolding
• Lockfile — deterministic dependency locking
• Bundle — deployment packaging
• Audit — CVE scanning via CPANSA
• Workspace — monorepo support
• Troubleshooting — common issues and fixes
• Perl Version Support — support policy

Contributing

nap is MIT licensed. See ATTRIBUTION.md for credits.

# Clone and build
git clone --recurse-submodules <repo-url>
cargo build

# Run tests (single-threaded for non-MULTIPLICITY Perl)
cargo test -- --test-threads=1

# Run network integration tests
cargo test -- --ignored

License

MIT — see LICENSE.