# Modly CLI

Calls a running Modly app from the terminal to make image-to-3D assets.

- Repository: https://github.com/lightningpixel/modly (8509 stars)
- Category: Media
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add lightningpixel/modly --skill modly-cli -g -a claude-code -y`
Codex: `npx skills add lightningpixel/modly --skill modly-cli -g -a codex -y`
Cursor: `npx skills add lightningpixel/modly --skill modly-cli -g -a cursor -y`
Gemini CLI: `npx skills add lightningpixel/modly --skill modly-cli -g -a gemini-cli -y`

## Description

Use when an agent needs to call a running Modly desktop instance from the terminal to generate/export image-to-3D assets through canonical JSON-first automation commands.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Modly CLI

## Overview

Modly exposes a local API at `http://127.0.0.1:8765` while the official desktop app is running. The stdlib-only CLI at `tools/modly-cli/agent.py` is an agent helper over the canonical automation contract:

- `health`
- `model`
- `workflow-run`
- `capability`
- `process-run`

Final machine-readable JSON is printed to stdout. Progress JSON lines, when requested, are printed to stderr.

## Prerequisites

Launch the official Modly desktop app first, then check readiness:

```bash
python tools/modly-cli/agent.py health
```

Use `--compact` when another agent needs single-line JSON:

```bash
python tools/modly-cli/agent.py --compact health
```

`GET /health` is checked before business operations. If the app is unavailable, failures are structured:

```json
{
  "ok": false,
  "code": "API_UNAVAILABLE",
  "message": "Cannot reach Modly API at ..."
}
```

## Canonical Commands

Inspect models through `/model/*`:

```bash
python tools/modly-cli/agent.py model list
python tools/modly-cli/agent.py model status
python tools/modly-cli/agent.py model params --model active
```

Start or resume workflow runs:

```bash
python tools/modly-cli/agent.py workflow-run start --image ./input.png --wait
python tools/modly-cli/agent.py workflow-run status <run_id>
python tools/modly-cli/agent.py workflow-run cancel <run_id>
```

Generate from an image and export the finished mesh:

```bash
python tools/modly-cli/agent.py generate \
  --image ./input.png \
  --output ./export.glb \
  --progress
```

`generate` is a friendly wrapper around `POST /workflow-runs/from-image` and `GET /workflow-runs/{run_id}`. It does not silently fall back to `/generate/*`. The JSON includes recovery metadata:

The rest: https://github.com/lightningpixel/modly/blob/HEAD/tools/modly-cli/SKILL.md