cdx-chores

A Node.js CLI for file-processing chores, tabular data workflows, rename automation, and Codex-assisted tasks.

Current command scope:

• interactive mode + nested CLI commands, including Esc exit on command menus
• doctor capability checks
• CSV / TSV / JSON conversion and preview workflows, including explicit headerless preview support
• data extract for shaped-table materialization across delimited, SQLite, and Excel inputs
• DuckDB-backed query, reviewed header-mapping, source-shape replay, and Parquet preview workflows
• data stack for assembling multiple CSV, TSV, JSONL, or JSON files and directories into one output table
• replayable data stack plan artifacts, dry-run diagnostics, duplicate/key checks, and optional reviewed Codex assistance
• md to-docx via pandoc, Markdown-to-PDF rendering via WeasyPrint, and Markdown PDF profile/template/project helpers
• preview-first rename flows
• ffmpeg-backed video wrappers, including GIF quality modes and profiles

Quick Start

Install globally from npm:

npm install -g cdx-chores

Recommended first check after install:

cdx-chores doctor

Show command help:

cdx-chores --help

Start interactive mode (default when no args are provided in a TTY):

cdx-chores

For doctor checks in Interactive mode, choose doctor, then select Summary, Details, or JSON.

Runtime requirement:

• Node.js >= 22.23.0

Command Overview

Command group	Important subcommands	Purpose	Capability notes
doctor	doctor, doctor --details, doctor --json	Inspect current tool and feature readiness	Run this first on a new machine or after environment changes
data	preview, extract, query, query codex, stack, stack replay, parquet preview, duckdb doctor, duckdb extension install, (conversion actions)	Tabular conversion, preview, extraction, multi-source stacking, DuckDB-backed SQL query, and Codex SQL drafting	lightweight csv / tsv / json preview and conversion stay on the in-memory PapaParse-backed path; extract is best suited to shaping one clean table, stack assembles many matching local sources before later work, and query is the expressive lane for filtering, projection, and output selection
md	to-docx, to-pdf, pdf-profile init, pdf-profile codex, pdf-template init, pdf-template codex, pdf-project codex, frontmatter-to-json	Markdown conversion, PDF profile/template/project generation, and metadata extraction	to-docx requires pandoc; to-pdf requires Pandoc 2.0+ and weasyprint
rename	file, batch, cleanup, apply	Safe rename previews, cleanup flows, and replayable apply runs	Codex analyzer routes are optional, not required for standard rename usage
video	convert, resize, gif, frames	Video conversion and still-frame exports	Frames requires ffmpeg, ffprobe, and the requested image encoder; other video commands require ffmpeg
interactive	interactive or no args	Guided menu flow for supported command groups	Requires a TTY

Data notes:

• conversion actions are json-to-csv, json-to-tsv, csv-to-json, csv-to-tsv, tsv-to-csv, and tsv-to-json
• data extract materializes one shaped table from one input file to .csv, .tsv, or .json; its strongest shaping surface is Excel-oriented cleanup, where it can target a sheet or range, set --header-row and --body-start-row, and replay reviewed source-shape or header-mapping artifacts for awkward header bands or merged-cell layouts
• data stack materializes one merged table from many local files or directories; use it before data query when the first problem is file assembly rather than SQL
• data query is the current general-purpose lane when you need richer filtering or transformation logic than data extract exposes without SQL

Capability Checks And External Tools

The npm package installs the CLI and its Node.js dependencies, but not every command is fully self-contained. Some workflows depend on machine-level tools or environment state outside the main CLI package.

Use cdx-chores doctor before relying on a command in a script, a CI job, or a fresh machine setup.

Area	What ships with cdx-chores	Additional requirement	How to verify or repair
md to-docx	Markdown-to-DOCX command wrapper	pandoc must be installed on PATH	Run cdx-chores doctor
md to-pdf	Markdown-to-PDF command wrapper and default HTML/CSS recipe	Pandoc 2.0+ and weasyprint must be installed on PATH	Run cdx-chores doctor
video convert, video resize, video gif	Video command wrappers	ffmpeg must be installed on PATH	Run cdx-chores doctor
video frames	Frame selection, sampling and still-image exports	ffmpeg and ffprobe on PATH, with the requested image encoder in the FFmpeg build	Run cdx-chores doctor --details; doctor reports advertised support. Verify an actual export for the intended source and mode
data extract, data query for csv, tsv, parquet	Extract and query command surfaces plus DuckDB integration	DuckDB runtime must be available in the current install/runtime	Run cdx-chores doctor
data extract, data query for sqlite, excel	Extract and query command surfaces	Required DuckDB extension must be loadable for the current DuckDB runtime	Run cdx-chores doctor, then cdx-chores data duckdb doctor or cdx-chores data duckdb extension install <name>
data extract reviewed suggestions, data query codex	Codex-assisted source shaping, semantic header review, and natural-language SQL drafting	Codex support must be configured and an auth/session signal must be available	Run cdx-chores doctor
md pdf-profile codex, md pdf-template codex, md pdf-project codex	Codex-assisted Markdown PDF profile, template, and coordinated project drafting	Codex support must be configured for Codex-assisted decisions; deterministic fallback paths remain available where documented	Run cdx-chores doctor

The Codex SDK baseline for v0.2.1 is @openai/codex-sdk 0.163.0.

Adopted helper commands and explicit interactive sessions accept --codex-model, --codex-provider, and --codex-reasoning-effort. Model and provider inherit Codex configuration when omitted; helper reasoning defaults to low. See Codex execution configuration for command scope and failure behavior.

Inspect the configuration and reported catalog without drafting a helper result:

cdx-chores codex-info
cdx-chores codex-info models --details
cdx-chores codex-info providers --json

Provider discovery lists configured definitions only; built-ins are not enumerated. Model metadata does not verify support through the selected provider.

Markdown PDF profile, template, and Codex-assisted profile/template/project helpers remain available as direct CLI flows. Interactive mode also provides md -> to-pdf for guided rendering and md -> pdf-recipes for durable recipe authoring with an optional render handoff.

The default doctor view is a compact workflow summary with detected actions. Use --details for complete human-readable evidence and --json for automation or machine-readable checks.

Video frames availability requires both FFmpeg and FFprobe. Doctor separately reports advertised PNG, JPG, still-WebP, and WebP lossless support; unknown assessments remain visible. These checks inspect encoder information without reading media or generating images. Successful export still depends on the source.

Machine-readable check:

cdx-chores doctor --json

Examples

Doctor

Compact workflow summary:

cdx-chores doctor

Detailed human evidence:

cdx-chores doctor --details

Machine-readable evidence:

cdx-chores doctor --json

Data

JSON to CSV:

cdx-chores data json-to-csv -i ./input.json -o ./output.csv

JSON to TSV:

cdx-chores data json-to-tsv -i ./input.json -o ./output.tsv

CSV to JSON:

cdx-chores data csv-to-json -i ./input.csv -o ./output.json --pretty

CSV to TSV:

cdx-chores data csv-to-tsv -i ./input.csv -o ./output.tsv

TSV to CSV:

cdx-chores data tsv-to-csv -i ./input.tsv -o ./output.csv

TSV to JSON:

cdx-chores data tsv-to-json -i ./input.tsv -o ./output.json --pretty

Preview CSV, TSV, or JSON as a bounded table:

cdx-chores data preview ./input.csv --rows 20
cdx-chores data preview ./input.tsv --rows 20

Preview a headerless CSV with generated column_n names:

cdx-chores data preview ./input.csv --no-header

Interactive lightweight conversion groups these formats under:

data -> convert

Extract one shaped table from an Excel sheet:

cdx-chores data extract ./input.xlsx --source Sheet1 --header-row 2 --body-start-row 3 -o ./output.tsv

Extract from a messier Excel range with explicit body rows:

cdx-chores data extract ./messy.xlsx --source Report --range A1:Z200 --header-row 4 --body-start-row 6 -o ./output.csv

Preview Parquet through DuckDB:

cdx-chores data parquet preview ./input.parquet --rows 20

Run a SQL query against one input file:

cdx-chores data query ./input.csv --sql "select * from file limit 20"

Draft SQL from natural-language intent:

cdx-chores data query codex ./input.csv --intent "show the top 10 rows with the highest revenue"

Inspect or repair DuckDB extension state for query inputs such as SQLite or Excel:

cdx-chores data duckdb doctor
cdx-chores data duckdb extension install sqlite

Markdown

Markdown to DOCX:

cdx-chores md to-docx -i ./notes.md -o ./notes.docx

Markdown to PDF:

cdx-chores md to-pdf -i ./notes.md

Markdown to PDF with a report ToC:

cdx-chores md to-pdf -i ./report.md --preset report --toc --toc-depth 3

Generate and use a reusable Markdown PDF profile:

cdx-chores md pdf-profile init --output ./pdf-profile.yml
cdx-chores md to-pdf -i ./report.md --profile ./pdf-profile.yml --meta author="Noname"

Generate editable Markdown PDF template files:

cdx-chores md pdf-template init --output ./pdf-template

Draft a coordinated Markdown PDF project and render its accepted inputs:

cdx-chores md pdf-project codex ./report.md \
  --intent "client report with a table of contents and readable code" \
  --output ./report-pdf-project

cdx-chores md to-pdf \
  --input ./report.md \
  --bundle ./report-pdf-project \
  --output ./report.pdf

Markdown frontmatter to JSON:

cdx-chores md frontmatter-to-json -i ./notes.md --pretty

Rename

Batch rename preview:

cdx-chores rename batch ./images --prefix gallery --dry-run

Single-file rename preview:

cdx-chores rename file ./images/IMG_1024.JPG --prefix gallery --dry-run

Cleanup an existing filename by normalizing a matched timestamp:

cdx-chores rename cleanup ./captures/'Screenshot 2026-03-02 at 4.53.04 PM.png' --hint timestamp --style slug --dry-run

Cleanup a directory with mixed hint families and recursive traversal:

cdx-chores rename cleanup ./captures --hint date,serial,uid --recursive --max-depth 1 --dry-run

Codex-assisted batch rename preview:

cdx-chores rename batch ./images --prefix gallery --codex --dry-run

DOCX title suggestions use the package's internal reader to extract metadata, headings, and text. Extraction attempts are limited to 8 MiB inputs and a 5-second processing deadline, separate from the Codex request timeout. Files above 8 MiB through 10 MiB fail extraction; larger files are skipped. Extraction failures retain deterministic rename fallback. See Rename scope and Codex capabilities and DOCX extraction limits for content and platform limits.

Give every Codex request attempt a two-minute deadline, with a shorter image analyzer override:

cdx-chores rename batch ./images \
  --codex \
  --codex-timeout 2m \
  --codex-images-timeout 45s \
  --dry-run

Apply an exact dry-run snapshot later:

cdx-chores rename apply ./rename-plan-20260225T214012Z-a1b2c3d4.csv

Recursive image rename with depth limit:

cdx-chores rename batch ./photos --recursive --max-depth 1 --ext jpg,png,webp --dry-run

Custom filename template:

cdx-chores rename batch ./images --prefix trip --pattern "{date}-{stem}-{serial}" --dry-run

UID-backed template example:

cdx-chores rename file ./images/IMG_1024.JPG --pattern "{uid}-{stem}" --dry-run

Template notes:

• placeholder families cover prefixes, stems, UIDs, dates, timestamps, and serials
• --prefix is optional
• --codex is the common smart-routing flag for CLI mode
• --codex-images and --codex-docs are explicit analyzer overrides
• --codex-timeout sets one per-request-attempt value, while --codex-images-timeout and --codex-docs-timeout override only their own analyzer
• timeout flags configure enabled Codex requests; they do not enable an analyzer
• the legacy --codex-images-timeout-ms and --codex-docs-timeout-ms flags remain supported during the current compatibility phase and print migration guidance when used
• {uid} renders a deterministic uid-<token> fragment
• {serial...} enables serial controls
• --serial-width uses a digit count such as 2 or 4, not #
• use docs/guides/rename-common-usage.md for the complete template contract

Cleanup notes:

• rename cleanup <path> accepts either a single file or a directory
• --hint is the canonical flag and --hints is accepted as an alias
• supported hint families are date, timestamp, serial, and uid
• cleanup applies multiple hint families in this order: timestamp, then date, then serial, then uid
• --style defaults to preserve; supported values are preserve and slug
• --timestamp-action keep|remove applies only when --hint timestamp is active
• --conflict-strategy currently supports skip, number, and uid-suffix

Cleanup option comparison:

Surface	Current role	Current values / scope
--hint	Choose fragment families to clean	date, timestamp, serial, uid
--style	Format surviving text after cleanup	preserve, slug
--timestamp-action	Keep or remove matched timestamp text	keep, remove with --hint timestamp
--conflict-strategy	Resolve collisions only when the cleaned target conflicts	skip, number, uid-suffix

Video

Export one frame, a fixed frame set, or a whole-video image sequence:

cdx-chores video frames -i ./clip.mp4 --first-frame
cdx-chores video frames -i ./clip.mp4 --frame-set first-middle-last
cdx-chores video frames -i ./clip.mp4 --interval 2s --format webp

Choose exactly one selector or cadence. PNG is the default and requires quality full; JPG and WebP offer low, medium, high, and full. JPG full remains lossy. WebP full requires advertised lossless support and rejects fully transparent pixels whose RGB values the supported encoder cannot preserve; use PNG for exact RGBA in that case. --output names a file for one frame and a folder for sets/sequences. Explicit image extensions must match the selected format. Matching existing files require --overwrite; completed images remain after interruption or failure. Use video frames --help for selector, template, and serial options.

For guided export, run cdx-chores and choose video → frames. Select one frame, a fixed set or a whole-video sequence, configure image settings and review the filenames before export. The custom picker offers a timeline and exact frame/time input, with direct-input fallback in small terminals.

See Video frames usage for sampling estimates, naming, dependency capabilities, progress and partial-output rules.

Video to GIF:

cdx-chores video gif -i ./clip.mp4 -o ./clip.gif --width 480 --fps 10

Video to GIF with explicit quality mode:

cdx-chores video gif -i ./clip.mp4 -o ./clip-quality.gif --mode quality --width 480 --fps 10

Video to GIF with a quality profile:

cdx-chores video gif -i ./clip.mp4 -o ./clip-screen.gif --gif-profile screen --width 480 --fps 10

Video to GIF with explicit look tuning:

cdx-chores video gif -i ./clip.mp4 -o ./clip-vibrant.gif --mode quality --gif-profile video --gif-look vibrant --width 480 --fps 10

Video resize with aspect-ratio-preserving scale:

cdx-chores video resize -i ./clip.mp4 -o ./clip-small.mp4 --scale 0.5

Video resize with explicit dimensions override:

cdx-chores video resize -i ./clip.mp4 -o ./clip-720p.mp4 --width 1280 --height 720

Guides

Cross-feature:

• Codex execution configuration and discovery
• Environment variables
• CLI output and color
• Codex timeouts, retries, and recovery
• Patterns, placeholders, and templates

Rename:

• Rename common usage
• Rename timestamp format matrix
• Rename scope and Codex capabilities
• DOCX extraction limits and behavior

Data:

• Data preview usage
• Data extract usage
• Data stack usage
• Data source shape usage
• Data schema and mapping usage
• Data query usage
• Interactive data query usage
• Data DuckDB usage
• Data query Codex usage

Video:

• Video frames usage
• Video GIF usage and quality modes
• Video resize usage and UX

Markdown:

• Markdown PDF usage
• Interactive Markdown PDF usage
• Markdown PDF Codex profile helper
• Markdown PDF Codex template helper
• Markdown PDF Codex project helper
• Markdown frontmatter to JSON output contract

Local Development

Install dependencies:

bun install

Run unit tests, or all suites when their prerequisites are available:

bun run test:unit
bun run test:all

See the Contributor Testing Guide for suite selection, platform requirements, prerequisites, focused testing, and retained results.

Build the package:

bun run build

Run the built CLI locally:

bun run cli --help

License

This project is licensed under the MIT License. See the LICENSE file for details.