Skip to content

CLI_REFERENCE.md

Latest commit

 

History

History
168 lines (132 loc) · 4.84 KB

CLI_REFERENCE.md

File metadata and controls

168 lines (132 loc) · 4.84 KB

CLI Reference

Complete command-line interface documentation for Dir2md.

Quick Start: Wiki.md | Main: README | Features: FEATURES.md | Help: TROUBLESHOOTING.md

Basic Syntax

dir2md [PATH] [OPTIONS]

Core Options

Output Configuration

  • -o, --output FILE - Output file path (default: auto-generated)
  • --output-format [md|json|jsonl|both] - Output format (both = md + jsonl)
  • --emit-manifest - Generate .manifest.json metadata file
  • --no-timestamp - Omit timestamp from filenames (CI-friendly)

Presets

  • --preset [raw|pro] - Quick configuration profiles
  • --ai-mode - Enable AI-friendly defaults (ref mode + capped budget)
  • --fast - Tree + manifest only (no contents)
Preset Token Budget Mode Best For
raw Unlimited inline Full code review, development
pro User-defined User-defined Production, tuned budgets
ai 6000 (capped) ref LLM context with query ranking
fast n/a off Tree + manifest only, ultra-light

Token Budget Control

  • --budget-tokens NUM - Total token budget for all files
  • --max-file-tokens NUM - Per-file token limit
  • --llm-mode [off|ref|summary|inline] - Content sampling strategy
  • --sample-head NUM - Head lines to include when truncating
  • --sample-tail NUM - Tail lines to include when truncating
  • --dedup NUM - SimHash Hamming distance threshold for dedup
  • --explain - Include capsule comments explaining selections

File Filtering

  • --include-glob PATTERN - Include files matching glob pattern
  • --exclude-glob PATTERN - Exclude files matching glob pattern
  • --omit-glob PATTERN - Skip content for matching files (still listed)
  • --only-ext EXT1,EXT2 - Only process specified extensions
  • --respect-gitignore - Respect .gitignore rules
  • --follow-symlinks - Follow symlinks that remain inside root
  • --max-bytes NUM - Max bytes read per file
  • --max-lines NUM - Max lines per file

Security & Masking

  • --masking [off|basic|advanced] - Secret masking level
  • --mask-pattern REGEX - Add custom masking regex pattern
  • --mask-pattern-file FILE - Load patterns from file (file:// URI)

AI/LLM Optimization

  • --ai-mode - Enable LLM-optimized defaults
  • --query TEXT - Rank files by semantic relevance to query

Risk Analysis (Spicy)

  • --spicy / --no-spicy - Enable/disable risk report (default: enabled)
  • --spicy-strict - Exit with code 2 on high/critical findings

Utilities

  • --dry-run - Preview configuration without writing files
  • --progress [full|dots|none] - Progress verbosity
  • --stats - Include stats summary in output
  • --capsule - Package outputs into a zip capsule
  • --defaults-file FILE - Use custom defaults.json
  • --version - Show version information
  • --help - Display help message

Configuration File

Create pyproject.toml in your project root:

[tool.dir2md]
preset = "pro"
include_glob = ["src/**/*.py", "tests/**/*.py"]
exclude_glob = ["**/__pycache__/**", "**/.venv/**"]
emit_manifest = true
budget_tokens = 8000

[tool.dir2md.masking]
patterns = ["(?i)secret_key\\s*=\\s*['\"]?[A-Za-z0-9]{16,}"]
pattern_files = ["file://./.dir2md/patterns.txt"]

Exit Codes

  • 0 - Success
  • 1 - General error
  • 2 - Security violation (with --spicy-strict)

Examples

Basic Usage

# Generate blueprint for current directory
dir2md .

# Specify output path
dir2md ./my-project -o blueprint.md

AI/LLM Context

# Claude/Copilot optimized
dir2md . --ai-mode --query "authentication" --output-format jsonl

# Gemini optimized with manifest
dir2md . --ai-mode --emit-manifest --budget-tokens 4000

Security Audit

# Basic masking
dir2md . --masking basic --spicy

# Strict mode (fail on high/critical)
dir2md . --masking advanced --spicy-strict

CI/CD Integration

# Deterministic output
dir2md . --preset pro --emit-manifest --no-timestamp -o BLUEPRINT.md

# Quick validation
dir2md . --preset fast --dry-run

Custom Filtering

# Python files only
dir2md . --only-ext py --budget-tokens 5000

# Exclude build artifacts
dir2md . --exclude-glob "**/dist/**" --exclude-glob "**/.venv/**"

Docker

# Windows
docker run --rm -v %cd%:/work dir2md:local /work --ai-mode

# Linux/macOS
docker run --rm -v $PWD:/work dir2md:local /work --ai-mode

Pattern File Format

JSON format for --mask-pattern-file:

[
  "(?i)stripe_key\\s*=\\s*['\"]?sk_live_\\w+",
  "(?i)auth_token\\s*:\\s*['\"]?[A-Za-z0-9_-]{20,}",
  "custom_pattern_here"
]

Text format (one pattern per line):

(?i)secret_key\s*=\s*['"]?[A-Za-z0-9]{16,}
(?i)api_key\s*:\s*['"]?\w{32,}