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

> Explore the Craft Agents OSS CLI client commands for scripting document automation. Discover over 40 sub-commands for conversion comparison and manipulation.

- Repository: [Craft Docs/craft-agents-oss](https://github.com/lukilabs/craft-agents-oss)
- Tags: api-reference
- Published: 2026-04-18

---

**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`](https://github.com/lukilabs/craft-agents-oss/blob/main/markitdown_cli.py) | `main` – Convert files to Markdown | [Source](https://github.com/lukilabs/craft-agents-oss/blob/main/apps/electron/resources/scripts/markitdown_cli.py) |
| **DocDiff** – Diff two documents after Markdown conversion | [`doc_diff.py`](https://github.com/lukilabs/craft-agents-oss/blob/main/doc_diff.py) | `main` – Compare documents with format options | [Source](https://github.com/lukilabs/craft-agents-oss/blob/main/apps/electron/resources/scripts/doc_diff.py) |
| **PDF Tool** – Full-featured PDF processor | [`pdf_tool.py`](https://github.com/lukilabs/craft-agents-oss/blob/main/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](https://github.com/lukilabs/craft-agents-oss/blob/main/apps/electron/resources/scripts/pdf_tool.py) |
| **PowerPoint Tool** – Create or extract .pptx files | [`pptx_tool.py`](https://github.com/lukilabs/craft-agents-oss/blob/main/pptx_tool.py) | `create`, `extract` | [Source](https://github.com/lukilabs/craft-agents-oss/blob/main/apps/electron/resources/scripts/pptx_tool.py) |
| **Image Tool** – Image processing and manipulation | [`img_tool.py`](https://github.com/lukilabs/craft-agents-oss/blob/main/img_tool.py) | `resize`, `crop`, `rotate`, `convert`, `info`, `watermark`, `composite` | [Source](https://github.com/lukilabs/craft-agents-oss/blob/main/apps/electron/resources/scripts/img_tool.py) |
| **iCal Tool** – Calendar file operations | [`ical_tool.py`](https://github.com/lukilabs/craft-agents-oss/blob/main/ical_tool.py) | `read`, `create`, `filter` | [Source](https://github.com/lukilabs/craft-agents-oss/blob/main/apps/electron/resources/scripts/ical_tool.py) |
| **DOCX Tool** – Word document automation | [`docx_tool.py`](https://github.com/lukilabs/craft-agents-oss/blob/main/docx_tool.py) | `create`, `template`, `info`, `replace`, `extract` | [Source](https://github.com/lukilabs/craft-agents-oss/blob/main/apps/electron/resources/scripts/docx_tool.py) |
| **XLSX Tool** – Excel workbook operations | [`xlsx_tool.py`](https://github.com/lukilabs/craft-agents-oss/blob/main/xlsx_tool.py) | `read`, `write`, `info`, `add-sheet`, `export` | [Source](https://github.com/lukilabs/craft-agents-oss/blob/main/apps/electron/resources/scripts/xlsx_tool.py) |

## 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`](https://github.com/lukilabs/craft-agents-oss/blob/main/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`](https://github.com/lukilabs/craft-agents-oss/blob/main/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:

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

```

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

```bash
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:

```bash
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:

```bash
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:

```bash
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:

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

```

7. Create a PowerPoint from markdown:

```bash
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:

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

```

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

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

```

10. Generate a DOCX report from a template:

```bash
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:

```bash
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`](https://github.com/lukilabs/craft-agents-oss/blob/main/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`](https://github.com/lukilabs/craft-agents-oss/blob/main/pyproject.toml) for the formats you need to process.