cli-anything-trellis

name	cli-anything-trellis
description	Operate the cli-anything-trellis harness: submit image-to-3D generation jobs via Microsoft TRELLIS.2, inspect job history, manage sessions, and probe GPU availability — all from the CLI without importing trellis2 directly.
triggers	["/trellis","generate 3d from image","trellis generate","image to glb","probe-gpu trellis"]

cli-anything-trellis Skill

When to use

Invoke this skill when:

• Submitting an image-to-3D generation job via TRELLIS.2
• Checking GPU availability in the TRELLIS Python environment
• Inspecting job history or catalog statistics
• Managing trellis session settings (home, python, resolution defaults)
• Writing agent code that calls the trellis CLI programmatically

Prerequisites

1. pip install -e ".[dev]" from the harness root
2. TRELLIS.2 installed in a separate Python environment
3. TRELLIS_HOME pointing to the TRELLIS.2 repo/install root
4. TRELLIS_PYTHON pointing to the Python interpreter with trellis2 installed
5. A CUDA-capable GPU (required by TRELLIS.2; CPU inference not supported)

Install

cd /path/to/cli-anything/trellis/agent-harness
pip install -e ".[dev]"

Verify:

trellis --version
trellis config probe-gpu

Command groups

Group	Subcommands	Purpose
generate	run	Submit image-to-3D job
jobs	list, show	Browse/inspect job history
catalog	list, stats	Read append-only JSONL catalog
session	show, set, unset, list, delete, clear-history	Persist settings
config	show, validate, probe-gpu	Installation/GPU checks
(bare)	—	Launch interactive REPL

Agent-facing JSON contract

All commands accept --json for machine-readable output.

generate run --json

{
  "job_id": "a1b2c3d4e5f6a7b8",
  "image_path": "/abs/path/to/image.png",
  "output_dir": "/abs/path/to/output",
  "resolution": "low",
  "seed": 42,
  "decimation_target": 1000000,
  "texture_size": 4096,
  "status": "done",
  "created_at": 1716000000.0,
  "started_at": 1716000001.0,
  "finished_at": 1716000045.0,
  "glb_path": "/abs/path/to/output/a1b2c3d4e5f6a7b8.glb",
  "error": null,
  "extra": {}

Status values: pending | running | done | failed

config probe-gpu --json

{
  "available": true,
  "device_count": 1,
  "devices": [
    {"index": 0, "name": "NVIDIA A100-SXM4-80GB", "total_memory_gb": 79.2}
  ]
}

catalog stats --json

{
  "total": 12,
  "done": 10,
  "failed": 1,
  "pending": 0,
  "running": 1
}

Worked examples

Submit a low-resolution job and capture the GLB path

result=$(trellis --json \
  --trellis-home "$TRELLIS_HOME" \
  --trellis-python "$TRELLIS_PYTHON" \
  generate run \
  --image /path/to/product.png \
  --output-dir /tmp/trellis-out \
  --resolution low \
  --seed 42)

echo "$result" | python -c "import sys,json; d=json.load(sys.stdin); print(d['glb_path'])"

Persist TRELLIS settings in the current session

trellis session set trellis_home "$TRELLIS_HOME"
trellis session set trellis_python "$TRELLIS_PYTHON"
trellis session set default_resolution low
# Now generate without flags:
trellis generate run --image product.png --output-dir /tmp/out

Probe GPU from a Python agent

import subprocess, json, sys

result = subprocess.run(
    [sys.executable, "-m", "cli_anything.trellis.trellis_cli",
     "--json", "config", "probe-gpu"],
    capture_output=True, text=True, timeout=30,
)
gpu_info = json.loads(result.stdout)
if not gpu_info["available"]:
    raise RuntimeError("No CUDA GPU — cannot run TRELLIS.2")

Programmatic generation from Python

import subprocess, json, sys, os

proc = subprocess.run(
    [sys.executable, "-m", "cli_anything.trellis.trellis_cli",
     "--json",
     "--trellis-home", os.environ["TRELLIS_HOME"],
     "--trellis-python", os.environ["TRELLIS_PYTHON"],
     "generate", "run",
     "--image", "/path/to/image.png",
     "--output-dir", "/tmp/trellis-out",
     "--resolution", "high",
     "--seed", "-1"],
    capture_output=True, text=True, timeout=900,
)
record = json.loads(proc.stdout)
if record["status"] != "done":
    raise RuntimeError(f"TRELLIS generation failed: {record['error']}")
glb_path = record["glb_path"]

Error handling

Error class	Cause	Resolution
TrellisNotFoundError	TRELLIS_HOME not set or no trellis2/ dir inside	Set TRELLIS_HOME correctly
TrellisPythonError	Python interpreter not found or fails --version	Set TRELLIS_PYTHON to the trellis2 venv python
GPUUnavailableError	torch.cuda.is_available() returned False	Ensure CUDA drivers installed and a GPU is available
RunnerError	Runner subprocess exited non-zero with no JSON	Check stderr attribute for details
RunnerTimeoutError	Generation exceeded --timeout seconds	Increase timeout or use a lower resolution preset

All errors are reflected in the JSON result when using --json:

{"status": "failed", "error": "CUDA is not available ...", ...}

Dry-run discipline

There is no --dry-run flag for generation (TRELLIS.2 is GPU-only with no mock mode). To test connectivity and environment without a GPU job:

trellis config validate     # checks TRELLIS_HOME + Python interpreter
trellis config probe-gpu    # checks CUDA via subprocess

Session model

Sessions are persisted at ~/.cli_anything/trellis/sessions/<name>.json. The default session is named default. Each session stores:

• trellis_home — path override
• trellis_python — interpreter override
• default_resolution — "low" or "high"
• default_output_dir — default output directory
• history — last 50 commands (capped)

The append-only job catalog lives at ~/.cli_anything/trellis/catalog.jsonl. One JSON record per line; never modified after append.

Scope limits

1. TRELLIS.2 only — no other image-to-3D backends are wired.
2. Single-job dispatch — generate run is synchronous; no queue or batch.
3. CUDA required — CPU inference is not supported by TRELLIS.2.
4. GLB output only — OBJ, FBX, USD are not exposed; change the runner if needed.
5. No model fine-tuning — the harness uses microsoft/TRELLIS.2-4B from HuggingFace Hub; custom checkpoints require modifying trellis_runner.py.