# How to Use the Modly CLI for Automated Batch Processing: A Complete Guide

> Automate image-to-3D conversions with the Modly CLI. This guide shows you how to leverage the Modly CLI for efficient batch processing and streamline your workflow. Get started today.

- Repository: [lightningpixel/modly](https://github.com/lightningpixel/modly)
- Tags: how-to-guide
- Published: 2026-08-15

---

**The Modly CLI ([`tools/modly-cli/agent.py`](https://github.com/lightningpixel/modly/blob/main/tools/modly-cli/agent.py)) is a std‑library‑only Python wrapper that drives the Modly desktop application via its local HTTP API (`http://127.0.0.1:8765`) to execute sequential image‑to‑3D conversions using the hidden `batch` sub‑command.**

The `lightningpixel/modly` repository provides a lightweight command‑line interface for automating large‑scale 3D asset generation without requiring interactive GUI sessions. When the Modly desktop app is running, the CLI exposes a **batch processing engine** that can enumerate directories or JSON manifests and run the full generation pipeline on each input image sequentially. This guide explains how to configure and execute automated batch workflows using the native CLI tools.

## Architecture of the Batch Processing System

Understanding the components helps you integrate the CLI into CI pipelines and job schedulers effectively.

- **Modly Desktop**: Hosts the FastAPI server on `127.0.0.1:8765` that executes workflows and serves generated assets. The CLI verifies health via `cmd_health` before any operation.
- **CLI Agent ([`tools/modly-cli/agent.py`](https://github.com/lightningpixel/modly/blob/main/tools/modly-cli/agent.py))**: Parses arguments in `build_parser()` and dispatches to `cmd_batch` for batch operations. It builds HTTP requests and formats JSON results without external dependencies.
- **Batch Engine**: The core loop in `cmd_batch` enumerates input images (or parses a manifest JSON) and invokes the standard `generate` workflow for each entry.
- **Recovery Metadata**: Each generation call returns a `meta` object via `_recovery_meta` containing `status` and `cancel` commands, enabling resumable automation and failure tracking.
- **Output Handling**: Path resolution occurs in `_manifest_jobs` and `cmd_batch`, downloading generated meshes to the source folder or a user‑specified `--output-dir`.

## Processing an Entire Directory

The most common use case involves converting a folder of PNG or JPEG images into 3D meshes. The CLI accepts `--input-dir` and processes files sequentially.

```bash
python tools/modly-cli/agent.py batch \
    --input-dir ./photos \
    --output-dir ./meshes \
    --format glb \
    --continue-on-error

```

**Key parameters:**
- `--input-dir`: Path to the folder containing source images.
- `--output-dir`: Destination directory for the resulting `.glb` (or specified format) files.
- `--format`: Export container format (default is `glb`).
- `--continue-on-error`: Ensures the batch continues processing remaining images if one fails.

By default, a single failure halts the entire batch unless `args.continue_on_error` is set.

## Using a Manifest JSON for Complex Workflows

For scenarios requiring per‑file output paths or mixed formats, create a JSON manifest instead of relying on directory enumeration.

Create [`jobs.json`](https://github.com/lightningpixel/modly/blob/main/jobs.json):

```json
{
  "jobs": [
    { "image": "samples/a.png", "output": "results/a.glb" },
    { "image": "samples/b.png", "format": "obj" }
  ]
}

```

Execute the batch:

```bash
python tools/modly-cli/agent.py batch \
    --manifest jobs.json \
    --format glb

```

The `_manifest_jobs` parser in [`tools/modly-cli/agent.py`](https://github.com/lightningpixel/modly/blob/main/tools/modly-cli/agent.py) expands each entry, resolves relative paths against the manifest location, and applies the default format to entries lacking an explicit `"format"` key.

## Error Handling and Recovery Metadata

The batch system provides granular control over failure behavior and post‑execution inspection.

When `--continue-on-error` is omitted, the loop in `cmd_batch` raises an exception immediately upon the first failed generation. When enabled, failures are recorded in the final JSON output without stopping execution.

Each successful or failed job returns a `meta` object generated by `_recovery_meta` containing:
- `status`: Command to check the current state of that specific job.
- `cancel`: Command to abort the job if it is still running.

This metadata enables you to resume interrupted batches or integrate with external orchestrators that need to poll individual job states.

## Integrating with CI Pipelines and Logging

For automated environments, combine `--progress` and `--compact` flags to separate structured logging from final output.

```bash
python tools/modly-cli/agent.py batch \
    --input-dir ./photos \
    --output-dir ./meshes \
    --progress \
    --compact \
    2> progress.log | jq .

```

**Output behavior:**
- `--progress` emits per‑step JSON lines to **stderr**, suitable for real‑time monitoring.
- `--compact` prints the final aggregated result as a single JSON line on **stdout**, ideal for piping to `jq` or storing as a CI artifact.

The final JSON structure includes `ok`, `count`, `failures`, and per‑image results, making it easy for downstream automation to determine success states.

## Summary

- The Modly CLI ([`tools/modly-cli/agent.py`](https://github.com/lightningpixel/modly/blob/main/tools/modly-cli/agent.py)) provides a **headless, dependency‑free** interface to the Modly desktop API.
- Use `cmd_batch` with `--input-dir` for simple directory processing or `--manifest` for complex job definitions.
- Enable `--continue-on-error` to prevent single failures from stopping large batches.
- Leverage `--progress` and `--compact` flags to integrate with shell scripts and CI systems.
- Recovery metadata (`_recovery_meta`) in the JSON output enables resumable workflows and operational monitoring.

## Frequently Asked Questions

### Does the Modly CLI require any external Python packages?

No. According to the `lightningpixel/modly` source code, the CLI is implemented as a **std‑library‑only** wrapper. It uses built‑in modules such as `urllib` for HTTP communication and `argparse` for command parsing, ensuring it runs on any standard Python installation without `pip install` requirements.

### What happens if the Modly desktop application is not running when I execute a batch command?

The CLI will fail during the initial health check (`cmd_health`). Before processing any batch items, `cmd_batch` verifies connectivity to `http://127.0.0.1:8765`. If the desktop app is not active, the command exits with an error indicating the API endpoint is unreachable.

### Can I specify different export formats for individual images within the same batch?

Yes. While the `--format` flag sets a global default, you can override formats per job by using a JSON manifest. In the manifest file, include a `"format"` key (e.g., `"format": "obj"`) inside specific job objects. The `_manifest_jobs` parser in [`agent.py`](https://github.com/lightningpixel/modly/blob/main/agent.py) applies these individual settings while using the CLI flag as a fallback for entries without explicit format declarations.

### How does the batch command handle file paths when using a manifest JSON?

The CLI resolves relative paths relative to the manifest file's directory, not the current working directory. This behavior, implemented in `_manifest_jobs` and `cmd_batch`, ensures that moving the manifest and input files together preserves path integrity, making the batch configuration portable across different execution environments.