dirule

Dirule

Dirule is a local-first CLI for bringing order to file and directory names. Define naming rules once, preview how they affect a project or folder, then apply the changes after review.

It is meant for the cleanup people keep repeating: organizing personal files, keeping project paths consistent, or checking naming conventions in CI. For configured project rules, matching language servers can update source references when paths are renamed. Dirule shows those edits in the plan and records them so undo can restore the original paths and document text. Quick sorting and renaming operations remain path-only.

See Dirule in action

The animation plays directly in the README. Watch the full-quality MP4 or browse the screenshots for individual examples.

What it does

• Match paths with ordered glob rules and named captures.
• Build destination paths with templates and built-in case transformations.
• Sort files by extension or category, with support for user-defined categories.
• Check naming conventions without changing files.
• Use configured language servers to preview and apply source-reference updates alongside project-rule renames.
• Run naming checks in other repositories with the reusable GitHub Actions workflow.
• Preview changes, detect conflicts, and refuse to overwrite existing paths.
• Record applied changes so runs can be inspected and safely undone.
• Save and reuse global presets across projects.

Development status

Dirule is under active development. The current release is v0.5.0; configuration and command behavior may change before a stable 1.0 release. See the changelog for release contents.

Install

Install the published crates.io package with Cargo:

cargo install --locked dirule

Or install a specific GitHub release:

cargo install --locked --git https://github.com/Slyverr/dirule --tag v0.5.0 dirule

For local development, run cargo install --path crates/dirule --locked from a checkout. NixOS users can install from the flake. Release installers, checksums, platform details, and shell completions are in the installation guide.

Quick start

If Dirule is not installed yet, see Install. From the directory you want to manage, create a starter config, preview the changes, and apply them:

dirule init
dirule validate
dirule plan
dirule apply
dirule check

validate checks the config without scanning files. plan previews proposed changes and check verifies that no changes or conflicts remain; neither changes paths. apply shows the plan again and asks for confirmation. Use --yes only when an automated run should skip that prompt; it does not bypass safety checks. A check run before applying will exit with status 1 if the target still needs changes.

Define naming rules

Rules live in the project's dirule.toml. Put specific rules before general rules because the first matching rule owns each original path.

version = "1.5"
target = "."

[[rules]]
name = "Archive invoices"
match = "Invoices/<year>-<vendor>-<title>.pdf"
kind = "file"
to = "template:Archive/${year}/${vendor|kebab-case}/${title|kebab-case}.pdf"

[[rules]]
name = "Normalize other filenames"
match = "**/*"
kind = "file"
to = "builtin:kebab-case"

The glob captures <year>, <vendor>, and <title> provide values for the destination template. Built-in transformations include snake-case, kebab-case, camel-case, and pascal-case; project-specific acronyms can be listed in the config. Use ignore for paths Dirule must always skip, and .diruleignore for additional project-local exclusions. Dirule also respects VCS ignore rules. The configuration guide covers matching, targets, transformations, and exclusions.

See the project naming example for a copyable rules config.

Sort common files

For a one-off sort, use a quick operation instead of creating a project config. These commands preview by default:

dirule categories list
dirule sort --target ~/Downloads
dirule sort images videos audio documents --target ~/Downloads
dirule sort pdf png --target ~/Downloads
dirule sort images --target ~/Downloads --apply
dirule rename kebab-case --target ~/Downloads

A bare sort previews every category in the effective catalog, including custom categories and built-in overrides. It scans direct files by default; add --recursive for nested files. Built-in categories group common extensions into destinations such as media/images/ and documents/. Add categories or customize those defaults with categories.toml. Quick operations use the same conflict checks and undo history as configured rules. See Usage for custom categories and more examples.

For a ready-to-adapt categories.toml, see the custom download categories example.

Ask a model (experimental)

dirule ask "..." sends one request to a configured model. Run dirule ask in a terminal to start a conversation with follow-up turns, or pipe one request to it for scripting. The assistant can inspect and preview Dirule operations, and can create a config or apply a change after you approve the exact proposal. It does not read file contents or save conversation transcripts. See the Ask guide for provider setup, data handling, and session commands.

Check in CI

Commit dirule.toml with the project and run:

dirule check --format json --color never

The command does not rename anything. It exits 0 when paths comply, 1 when a rename or conflict is found, and 2 when Dirule cannot complete the check. The CI guide includes a reusable GitHub Actions workflow and a pre-commit hook. For rules that report violations without renaming, see the check-only rules example.

Review and undo

Each successful apply prints a run ID. Inspect or undo that run with:

dirule runs list
dirule runs show RUN_ID
dirule undo RUN_ID

The journal does not copy renamed files. When LSP updates references, it stores the complete before-and-after text of changed source documents so undo can restore them. It is recovery history, not a general backup. Dirule verifies paths before undoing and will not overwrite a file that has changed or appeared since the run. See Usage for run details.

Use with coding agents

Dirule includes an Agent Skill that helps compatible coding agents configure and use Dirule in a project or personal folder. Run the Skills CLI with npx or Bun's bunx:

npx skills add Slyverr/dirule --skill dirule
# or
bunx skills add Slyverr/dirule --skill dirule

Add -g to make the skill available globally for your agent. The skill provides instructions; install Dirule itself separately using the installation guide.

Help and contributions

For bugs, questions, or feature ideas, open a GitHub issue. Contributions are welcome; see Contributing for development checks and project conventions.

License

Dirule is licensed under the MIT License.