CLI Client Commands for Scripting: Complete Reference to Craft Agents Document Automation Tools

The Craft Agents OSS repository provides nine specialized CLI tools built with Click, offering over 40 sub-commands for document conversion, comparison, and manipulation in scriptable workflows.

The lukilabs/craft-agents-oss repository ships a comprehensive suite of command-line utilities located in apps/electron/resources/scripts/. These CLI client commands for scripting implement a consistent architecture using the Click framework, making them ideal for CI/CD pipelines, batch processing, and terminal workflows that require document automation.

Complete Inventory of CLI Tools

The following table provides a complete architecture-level inventory of every public CLI command, including entry points, available sub-commands, and source locations:

Tool	Entry Point	Sub-commands	Source
Markitdown – Universal document-to-Markdown converter	markitdown_cli.py	main – Convert files to Markdown	Source
DocDiff – Diff two documents after Markdown conversion	doc_diff.py	main – Compare documents with format options	Source
PDF Tool – Full-featured PDF processor	pdf_tool.py	extract, info, merge, split, rotate, reorder, duplicate, watermark, fill-form, compress, crop, resize, flatten, header-footer, encrypt, decrypt, redact, sanitize, to-image, from-image, to-docx, to-pptx	Source
PowerPoint Tool – Create or extract .pptx files	pptx_tool.py	create, extract	Source
Image Tool – Image processing and manipulation	img_tool.py	resize, crop, rotate, convert, info, watermark, composite	Source
iCal Tool – Calendar file operations	ical_tool.py	read, create, filter	Source
DOCX Tool – Word document automation	docx_tool.py	create, template, info, replace, extract	Source
XLSX Tool – Excel workbook operations	xlsx_tool.py	read, write, info, add-sheet, export	Source

Architecture and Design Patterns

All CLI client commands for scripting in apps/electron/resources/scripts/ share a unified architecture that ensures consistency, performance, and reliability across the tool suite.

Click Entry Points

Each file defines a top-level command group using @click.group() (typically named cli), which registers sub-commands via the @cli.command() decorator. This pattern, implemented in files like apps/electron/resources/scripts/pdf_tool.py, enables modular organization and automatic help generation for complex tools with multiple operations.

Helper Utilities

Common functionality is abstracted into reusable helpers. Most tools expose write_output() for streaming results to stdout or file handles, while domain-specific utilities like parse_page_range() in pdf_tool.py handle complex parameter parsing. These utilities ensure consistent I/O behavior and error reporting across the entire CLI ecosystem.

Lazy Imports for Performance

To minimize startup time and avoid dependency crashes, heavy third-party libraries such as markitdown, pypdfium2, and python-pptx are imported inside command functions rather than at module level. This lazy loading strategy keeps the CLI responsive and prevents failures on systems missing optional native binaries.

Error Handling and Exit Codes

Every command implements robust error handling through try … except blocks. On failure, utilities emit user-friendly messages via click.echo(..., err=True) and terminate with sys.exit(1). This ensures that CLI client commands for scripting return canonical non-zero exit codes, making them safe for use in CI/CD pipelines and shell scripts that depend on error detection.

Practical Scripting Examples

The following one-liners demonstrate how to drive each tool from shell scripts. Replace uv run with your preferred Python launcher (python -m, poetry run, etc.) if not using uv.

1. Convert a DOCX file to Markdown:

uv run markitdown_cli.py resume.docx -o resume.md

2. Show the diff between two PDFs (summary view):

uv run doc_diff.py old_report.pdf new_report.pdf --format summary --word-level -o diff.txt

3. Extract text from specific pages of a PDF:

uv run pdf_tool.py extract contract.pdf --pages "1-3,5" -o contract_pages.txt

4. Add a watermark to every page of a PDF:

uv run pdf_tool.py watermark contract.pdf \
    --text "CONFIDENTIAL" \
    --font-size 72 --opacity 0.2 --angle 45 \
    -o contract_watermarked.pdf

5. Merge several PDFs into one:

uv run pdf_tool.py merge part1.pdf part2.pdf part3.pdf -o combined.pdf

6. Convert PDF pages to PNG images for a CI artifact:

uv run pdf_tool.py to-image slides.pdf --format png --dpi 150 -o images/

7. Create a PowerPoint from markdown:

uv run pptx_tool.py create --from-file deck.md -o deck.pptx

8. Resize an image to 800 px wide while keeping aspect ratio:

uv run img_tool.py resize photo.jpg --width 800 -o photo_resized.jpg

9. List all events from an iCal file in JSON:

uv run ical_tool.py read calendar.ics --format json -o calendar.json

10. Generate a DOCX report from a template:

uv run docx_tool.py template report_template.docx \
    --data '{"title":"Q1 Report","author":"Alice"}' -o Q1_Report.docx

11. Export every sheet of a workbook as CSV:

uv run xlsx_tool.py export workbook.xlsx --all-sheets --format csv -o all_sheets.csv

Summary

• Nine specialized tools provide over 40 sub-commands for document automation, all located in apps/electron/resources/scripts/.
• Consistent Click architecture with @click.group() entry points and modular @cli.command() registration enables predictable CLI behavior.
• Production-ready reliability through lazy imports for fast startup, helper utilities like write_output(), and sys.exit(1) error codes for pipeline integration.
• Universal format support covers Markdown conversion, PDF manipulation, Office documents (DOCX, XLSX, PPTX), images, and iCal calendars.

Frequently Asked Questions

How do I install the CLI tools for scripting?

The CLI tools reside in apps/electron/resources/scripts/ and require Python 3.x. You can execute them directly using uv run, python -m, or poetry run after installing the repository dependencies. Each script uses lazy imports, so you only need the specific dependencies for the formats you process, which are typically listed in the repository's pyproject.toml.

Can I use these CLI client commands in a CI/CD pipeline?

Yes, these tools are explicitly designed for automation. They return non-zero exit codes (sys.exit(1)) on failure and write errors to stderr via click.echo(..., err=True), making them compatible with standard CI/CD error detection. The lazy import architecture ensures fast container startup times, while the comprehensive PDF, Office, and image format support covers most document processing pipeline needs.

What exit codes do the CLI commands return?

All tools follow standard Unix conventions: exit code 0 indicates success, while exit code 1 indicates failure. The error handling in apps/electron/resources/scripts/ explicitly catches exceptions and calls sys.exit(1), ensuring that shell scripts and automation tools can reliably detect failures using standard constructs like set -e or if command; then ... fi.

How do I handle missing dependencies for specific file formats?

The CLI tools use lazy imports, meaning heavy libraries like pypdfium2, python-pptx, or markitdown are only imported when a specific command runs. If a required library is missing, the command will fail with a clear ImportError at runtime rather than at module load. Install the specific extras or dependencies listed in the repository's pyproject.toml for the formats you need to process.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}