Use Drawthings CLI

Use Draw Things CLI

Use the Homebrew-installed draw-things-cli executable from PATH. Assume it is already installed and the user does not have the Draw Things source repository. Do not build with Bazel or SwiftPM unless the user explicitly asks to develop or test the CLI itself.

Follow The Shortest Safe Workflow

1. Verify the installed command and read its current help; repair installation only if verification fails.
2. Choose local, cloud, or remote-server execution.
3. Discover a valid model file ID instead of guessing one.
4. Start with one inexpensive, reproducible output.
5. Write to an explicit output path and validate the artifact before reporting success.

Before downloading a large local model or consuming cloud compute, tell the user what will happen. Treat an explicit request to download or generate as authorization for that requested operation; do not submit extra variants without permission. Cloud generation has no dry-run or built-in price preview, so obtain confirmation immediately before the first cloud job unless the user explicitly requested that cloud job.

Verify The Installed CLI

Start here; do not reinstall or upgrade a working CLI merely to run a generation:

command -v draw-things-cli
draw-things-cli --version
draw-things-cli --help
draw-things-cli generate --help

If the executable is missing, confirm the stable Homebrew Core formula and install it as a recovery step:

brew info draw-things-cli
brew install draw-things-cli
command -v draw-things-cli

If the installed CLI lacks a required documented option, record its version and ask before upgrading:

brew outdated draw-things-cli
brew upgrade draw-things-cli

Do not substitute the draw-things GUI cask, an old custom tap, or --HEAD. On Apple Silicon, if installation fails or the binary has the wrong architecture, compare uname -m with brew --prefix; a native Homebrew normally uses /opt/homebrew, while /usr/local may indicate a Rosetta installation. Do not replace Homebrew or edit shell startup files without the user's approval. Use brew info draw-things-cli as the authority for current platform requirements.

Treat the installed --help output as the source of truth because flags and model support evolve. Read the relevant subcommand help before constructing a non-trivial command:

draw-things-cli models --help
draw-things-cli auth --help
draw-things-cli generate --help
draw-things-cli train --help

Choose A Backend

Keep these current CLI boundaries explicit:

• Remote and cloud generation reject video output.
• Remote and cloud generation reject --audio.
• LongCat --avc is local-only.
• Remote and cloud accept a normal --image input for supported image-to-image generation.
• --offline cannot be combined with remote or cloud execution.
• --remote and --cloud-compute are mutually exclusive.
• Remote and cloud upload prompts and any image input to the selected service. Confirm that the user accepts this privacy boundary.
• Remote and cloud do not upload local model or LoRA weights. Do not assume an unregistered local model or LoRA exists on the target service.

If the installed help differs, follow the installed version and report the difference.

Discover And Prepare Models

List model mappings before choosing a model:

draw-things-cli models list
draw-things-cli models list --downloaded-only

Prefer the exact file ID from the first column, such as z_image_turbo_1.0_q8p.ckpt. Human-readable names and Hugging Face references are supported, but the exact registered file ID makes runs easier to reproduce.

For local generation, download the selected model and its registered dependencies explicitly when the user wants a predictable preparation step:

draw-things-cli models ensure --model z_image_turbo_1.0_q8p.ckpt

Generation downloads missing files by default. Add --no-download-missing only after verifying the files exist. Add --offline only when the user requires no network access.

Let the CLI resolve its default model directory unless the user supplies one. Resolution is shown by models list --help; override it consistently with either --models-dir /path/to/Models or DRAWTHINGS_MODELS_DIR. Quote paths containing spaces.

Generate A First Local Image

Use model-recommended settings for the first run. Override only the seed and output so the result is reproducible and saved:

draw-things-cli generate \
  --model z_image_turbo_1.0_q8p.ckpt \
  --prompt "A small red cube on a wooden table, soft studio light" \
  --seed 42 \
  --disable-preview \
  --output "$PWD/draw-things-first.png"

If that model ID is absent from models list, select another downloaded or official text-to-image model and keep its recommended settings. Do not assume one model's steps or CFG suit another model.

Always pass --output for unattended agent work. Without it, the CLI may render a temporary inline preview and intentionally leave no file.

Generate With Draw Things Cloud

Prefer browser login over asking the user to paste an API key. Pause for the user when the browser, Google login, MFA, or an OS permission prompt requires interaction:

draw-things-cli auth login
draw-things-cli auth token

Do not print saved credentials or place an API key in shell history, logs, source files, or chat. Before submission, choose a new .png output path and confirm its parent directory exists and is writable. This avoids paying for a successful generation that cannot be saved locally. After the user has authorized cloud usage, generate one PNG first:

draw-things-cli generate \
  --cloud-compute \
  --model z_image_turbo_1.0_q8p.ckpt \
  --prompt "A small red cube on a wooden table, soft studio light" \
  --seed 42 \
  --output "$PWD/draw-things-cloud.png"

Run auth logout only when the user asks to remove saved credentials.