dukatools 0.4.1

Small cross-platform CLI toolbelt (launcher-only via duka): treex, dircat, pyarc, and more.

dukatools

A small, batteries-included command line toolbox for working with directories and media across Linux, macOS, and Windows.

Table of contents

• Features at a glance
• Installation
• Upgrading
• Quick start
• CLI utilities
  • duka — run dukatools tools
  • treex — directory trees with excludes
  • dircat — batch dump directory files
  • vidcut — fast and accurate video trimming
  • pydown — grab python-build-standalone releases
  • pyarc — pack and unpack tar.gz archives
• Configuration & environment variables
• Development
• License

Features at a glance

• Cross-platform install via uv tool, pipx, or pip — no manual PATH setup required.
• Single launcher entry point (duka) to run every tool (standalone binaries are intentionally not installed).
• Tree inspection with smart excludes via duka treex, ideal for sharing repository structure without build artifacts.
• Directory dumping via duka dircat for quick audits, backups, and reviews.
• FFmpeg-powered video trimming via duka vidcut with automatic fallback from stream-copy to frame-accurate cuts.
• One-file Python downloads via duka pydown for fetching and unpacking python-build-standalone releases.
• Archive packing/unpacking via duka pyarc for fast, progress-aware .tar.gz workflows.
• Zero-config defaults plus optional environment overrides when you need extra control.

Installation

dukatools is distributed as a standard Python package targeting Python 3.10+.

Using uv

uv tool install dukatools

Using pipx

pipx install dukatools

Using pip

python -m pip install --user dukatools

All installation methods place only the duka entry point on your PATH. Every tool is invoked as duka <tool> ....

Upgrading

Stay current with the latest enhancements and fixes:

uv tool upgrade dukatools
# or
pipx upgrade dukatools
# or
python -m pip install --upgrade dukatools

From version 0.4.1 onward, dukatools installs only the duka launcher. If you still see old standalone binaries like treex or dircat on your PATH after upgrading, uninstall and reinstall the package (for pipx, pipx uninstall dukatools + pipx install dukatools).

Quick start

# Explore a repository without build artifacts
$ duka treex . --exclude .git build --exclude-re "*.pyc"

# Dump every text file in a directory into stdout (recursively)
$ duka dircat ./notes --exclude-re "^archive/"

# Trim the first five seconds off a video without re-encoding
$ duka vidcut sample.mp4 --trim-start 5s --overwrite

# Download and extract a python-build-standalone release into ~/python-builds
$ duka pydown --dest ~/python-builds --version 3.12 --extract

# Pack a project into a .tar.gz with excludes
$ duka pyarc pack ./project ./project.tar.gz --exclude .git --exclude-re "*.pyc"

Tools are launcher-only. Use duka <tool> and duka <tool> --help for full usage.

CLI utilities

duka — run dukatools tools

duka is a lightweight launcher so you do not have to remember the individual binary names.

Usage

duka <tool> [args...]

Example

duka treex /home/user/project1 --exclude .git

If you run duka with no arguments, it prints the list of available tools.

treex — directory trees with excludes

treex renders a directory structure in a friendly tree format while supporting both exact-name excludes and regex/glob rules. Invoke it as duka treex.

Highlights

• Exclude generated folders such as __pycache__, build, or node_modules with a single command.
• Handles deeply nested projects and gracefully reports permission errors.
• Works great for quickly sharing repository layouts in issues, documentation, or chats.

Usage

duka treex PATH \
      [--exclude NAME ...] \
      [--exclude-re RULE ...]

If PATH is omitted, duka treex uses the current directory.

Example output

Directory tree for: ./project
Excluded rules: *.pyc
├── pyproject.toml
├── README.md
└── src
    ├── __init__.py
    └── project
        └── core.py

dircat — batch dump directory files

dircat walks a directory, printing every file it finds to stdout with a clear header for each file. Invoke it as duka dircat.

Highlights

• Recursive by default for quick directory audits.
• Combine --exclude and --exclude-re to skip sensitive or noisy paths.
• Prints UTF-8 text and replaces undecodable bytes when needed.
• Perfect for quickly packaging logs, notes, or configuration snapshots for debugging.

Usage

duka dircat ROOT_DIR \
       [--exclude PATH ...] \
       [--exclude-re RULE ...]

Writing to a file

duka dircat ./config --exclude-re "\.git/" > artifacts/config-dump.txt

vidcut — fast and accurate video trimming

vidcut wraps FFmpeg and provides a friendly interface for clipping one or more video files. It prefers stream-copy (no re-encode) for speed, then transparently falls back to a frame-accurate re-encode when necessary. Invoke it as duka vidcut.

Highlights

• Accepts flexible time formats (90, 45.5, 00:01:02.300, 5s, 2m, etc.).
• Supports batch processing using glob patterns ("*.mp4").
• Automatically discovers FFmpeg: explicit path, DUKATOOLS_FFMPEG, bundled imageio-ffmpeg, or system PATH.
• Provides a --doctor command to inspect and pre-download the FFmpeg binary.
• Adds MP4-friendly flags such as +faststart for streaming-optimized outputs.

Usage

duka vidcut INPUT [INPUT ...] \
       [--out OUTPUT.mp4] \
       [--suffix _cut] \
       [--from START] [--to END] [--duration DURATION] \
       [--trim-start SECONDS] [--trim-end SECONDS] \
       [--accurate | --fast] \
       [--overwrite] [--dry-run] [--ffmpeg PATH] [--doctor]

Common scenarios

# Keep a 12 second clip (fast copy mode)
duka vidcut clip.mp4 --from 00:00:05 --duration 12s --overwrite

# Batch trim all MOV files, append suffix, and overwrite existing clips
duka vidcut "videos/*.mov" --trim-start 3s --suffix _trimmed --overwrite

# Force frame-accurate cutting
duka vidcut input.mp4 --from 1m --duration 5s --accurate --overwrite

# Preview the ffmpeg command without running it
duka vidcut input.mp4 --from 10s --duration 15s --dry-run

# Ensure FFmpeg is available (downloads via imageio-ffmpeg if needed)
duka vidcut --doctor

pydown — grab python-build-standalone releases

pydown automates downloading python-build-standalone artifacts from GitHub, selecting the right CPU/OS triplet and variant, and optionally extracting the archive for you. Invoke it as duka pydown.

Highlights

• Detects the correct python-build-standalone triplet for Linux (glibc/musl), macOS, and Windows hosts, with manual overrides when you need them.
• Supports picking variants (install_only_stripped, install_only, full, debug) and specific Python versions.
• Can extract archives in place and create helpful shims to add the installed Python to your PATH.
• Works with anonymous GitHub access or an optional GITHUB_TOKEN for higher rate limits.

Usage

duka pydown --dest PATH \
       [--version 3.12.6] \
       [--variant install_only_stripped] \
       [--extract] \
       [--triplet aarch64-apple-darwin]

Common scenarios

# Download the latest CPython build for your platform and extract it
duka pydown --dest ~/python-builds --extract

# Grab Python 3.12.6 and unpack it into a versioned directory
duka pydown --dest ./pbs --version 3.12.6 --extract

# Override the platform triplet (useful for cross-deployment scripting)
duka pydown --dest ./artifacts --triplet x86_64-unknown-linux-gnu

pyarc — pack and unpack tar.gz archives

pyarc creates and extracts .tar.gz archives with progress output. It uses external pigz and tar for speed. Invoke it as duka pyarc.

Highlights

• Fast gzip compression via pigz with configurable threads.
• Exact excludes and flexible rules (--exclude / --exclude-re).
• Progress bars and throughput reporting for pack/unpack operations.

Usage

duka pyarc pack SRC ARCHIVE.tar.gz \
      [--exclude NAME ...] \
      [--exclude-re RULE ...] \
      [--threads N] \
      [--level 1..9]

duka pyarc unpack ARCHIVE.tar.gz DEST_DIR \
      [--threads N]

Example

duka pyarc pack ./project ./project.tar.gz --exclude .git --exclude-re "*.pyc"

Configuration & environment variables

• DUKATOOLS_FFMPEG — absolute path to an FFmpeg binary. Overrides auto-detection for vidcut.
• Standard locale and encoding settings (e.g., LANG, LC_ALL) influence how output is rendered in your terminal.

Development

Interested in hacking on dukatools? Clone the repository and install local dependencies with your preferred workflow. A concise developer walkthrough lives in DEV.md, covering how to add or remove CLI tools, build wheels, and publish releases.

License

dukatools is released under the MIT License. See LICENSE for the full text.