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

The Modly CLI (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): 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.

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:

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

Execute the batch:

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

The _manifest_jobs parser in 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.

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) 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 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.

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