dazzlecmd 0.4.1

Unified CLI for the DazzleTools collection - many tools, one command

DazzleCMD (dz)

Many tools, one command.

A unified CLI that aggregates many small standalone tools into a single discoverable, version-tracked interface. Instead of remembering where dozens of scripts live or hunting through folders, just use dz <tool> [args].

Why DazzleCMD?

Have you ever accumulated a collection of small utilities and handy scripts over the years -- spread across multiple folders, computers, some on network drives, some local, most not on GitHub -- and found yourself constantly forgetting where things live or what they're called?

Or maybe you've written a quick Python script to solve a problem, used it a few times, then couldn't find it six months later when you needed it again? Or you have tools that are useful but too small to justify their own GitHub repo, but also too valuable to leave scattered and unversioned?

Enter dz...

DazzleCMD provides a single entry point for all your tools. Each tool keeps its own structure and versioning. Dazzlecmd simply provides the discovery and dispatch layer. Tools that grow complex enough can "graduate" to their own repos (which can in turn be nested internal to "dz" as git submodules). Tools that stay small stay organized, easy to find, and simple to track.

Features

• Unified Dispatch: Run any tool with dz <tool> [args] -- argparse-based with per-tool subparsers
• Kit System: Curated tool collections -- core ships with dazzlecmd, dazzletools bundles the default collection
• Polyglot Support: Python, shell, batch, compiled binaries -- dispatch handles runtime differences transparently
• Progressive Scaffolding: dz new my-tool starts minimal (blank canvas), --simple adds TODO/NOTES, --full adds roadmap and tests
• Namespace Organization: Tools grouped under projects/<namespace>/<tool>/ to prevent collisions at scale
• Platform-Aware: Each tool declares both a quick-glance platform category and specific verified OS list
• No Modification Required: Existing scripts work as-is -- dazzlecmd wraps them, doesn't rewrite them

Installation

pip install dazzlecmd

Or install from source:

git clone https://github.com/DazzleTools/dazzlecmd.git
cd dazzlecmd
pip install -e .

Usage

# List all available tools
dz list

# Run a tool (all arguments pass through)
dz dos2unix myfile.txt
dz rn "(.*)\.bak" "\1.txt" *.bak
dz delete-nul C:\projects
dz links -r --type symlink,junction    # Find all symlinks and junctions recursively
dz links --broken                      # Find broken links in current directory

# Get detailed info about a tool
dz info dos2unix

# List kits and their contents
dz kit list
dz kit list core
dz kit list dazzletools

# Create a new tool project
dz new my-tool                  # Bare minimum: manifest + script
dz new my-tool --simple         # + TODO.md, NOTES.md
dz new my-tool --full           # + ROADMAP.md, tests/, private/

# Version info
dz --version

Included Tools

Core Kit

These are the tools that ship with dazzlecmd. They are available everywhere and always active.

Tool	Description	Platform
find	Cross-platform file search powered by fd	Cross-platform
fixpath	Fix mangled paths, search for files, open/copy/browse	Cross-platform
links	Detect and display filesystem links (symlinks, junctions, hardlinks, shortcuts)	Cross-platform
listall	Flexible directory structure listing with sorting and collection	Cross-platform
rn	Rename files using regular expressions	Cross-platform

DazzleTools Kit

The default DazzleTools collection.

Tool	Description	Platform
claude-cleanup	Stage and commit Claude Code transient state files	Cross-platform
dos2unix	Pure-Python line ending converter (dos2unix/unix2dos)	Cross-platform
delete-nul	Delete Windows NUL device files created by accidental >nul redirection	Windows
srch-path	Search the system PATH for executables	Cross-platform
split	Split text by separator with optional token filtering	Cross-platform

How It Works

1. Discovery: On startup, dz scans projects/<namespace>/<tool>/ for .dazzlecmd.json manifests
2. Kit Filtering: Only tools belonging to active kits are loaded
3. Parser Assembly: Each discovered tool gets an argparse subparser
4. Dispatch: When you run dz <tool> [args], the runtime type determines how the tool executes:
   • python with pass_through: false → imports the module and calls the entry point directly
   • python with pass_through: true → runs via subprocess (for tools with non-standard signatures)
   • shell / script / binary → subprocess with appropriate interpreter

Tool Manifests

Each tool has a .dazzlecmd.json manifest:

{
    "name": "dos2unix",
    "version": "0.1.0",
    "description": "Pure-Python line ending converter",
    "namespace": "dazzletools",
    "language": "python",
    "platform": "cross-platform",
    "platforms": ["windows", "linux", "macos"],
    "runtime": {
        "type": "python",
        "entry_point": "main",
        "script_path": "dos2unix.py"
    },
    "taxonomy": {
        "category": "file-tools",
        "tags": ["text", "line-endings", "conversion"]
    }
}

Project Structure

dazzlecmd/
├── src/dazzlecmd/            # Installable Python package
│   ├── cli.py                # Entry point, argparse dispatch
│   ├── loader.py             # Kit-aware project discovery
│   └── templates/            # Scaffolding templates for dz new
├── projects/                 # Tool projects by namespace
│   ├── core/                 # Core tools (ships with dazzlecmd)
│   │   ├── find/
│   │   ├── fixpath/
│   │   ├── links/
│   │   ├── listall/
│   │   └── rn/
│   └── dazzletools/          # DazzleTools collection
│       ├── claude-cleanup/
│       ├── dos2unix/
│       ├── delete-nul/
│       ├── split/
│       └── srch-path/
├── kits/                     # Kit definitions (*.kit.json)
├── config/                   # JSON schema for manifests
└── scripts/                  # Version management and git hooks

Cross-Platform

Platform	Status
Windows	Supported
Linux	Supported
macOS	Supported

Individual tools may have platform-specific requirements -- check dz info <tool> for details. See Platform Support for the full matrix.

Documentation

• Core Tool Docs -- detailed documentation for each core tool
• Creating Tools -- build your own dz tool
• Kits Guide -- how the kit system works, the recursive architecture
• Manifest Reference -- .dazzlecmd.json schema
• Platform Support -- OS compatibility matrix

Related Projects

• git-repokit -- Standardized Git repository creation tool
• preserve -- Cross-platform file preservation with path normalization and verification
• dazzlesum -- Cross-platform file checksum utility

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

Like the project?

License

Copyright (C) 2026 Dustin Darcy

This project is licensed under the GNU General Public License v3.0 -- see the LICENSE file for details.