montaj --version    # or: montaj -v
# montaj 3.2.5

--json        # output result as JSON (for scripting and agent use)
--out <path>  # specify output path (default: workspace/)
--quiet       # suppress progress output, result only on stdout

montaj run ./clips --prompt "tight cuts, remove filler, 9:16"
# Runs default workflow against all clips in the directory

montaj run ./clips --workflow tight-reel --prompt "..."
# Runs a named workflow

montaj run --canvas --workflow animations --prompt "60s animated explainer, dark theme"
# Animation project — no source footage required

montaj serve
# Start local HTTP server + open UI at http://localhost:3000

montaj serve --network
# Bind to all network interfaces — accessible to other devices on the local network.
# WARNING: only use on trusted networks.

montaj render
# Render project.json [final] → final.mp4

montaj render --project ./workspace/project.json --out ./output/final.mp4
# Explicit paths

montaj render --clean
# Delete intermediate files after compositing

montaj workflow list
# List all available workflows (native + custom)

montaj workflow new <name>
# Scaffold a new workflow file at workflows/<name>.json

montaj workflow edit <name>
# Open workflow in the node graph UI

montaj workflow run <name> ./clips --prompt "..."
# Run a specific workflow (alias for: montaj run --workflow <name>)

montaj step --help                  # list all available steps
montaj step <name> --help           # show params for a specific step
montaj step <name> --input <file>   # run a step

montaj create-step <name>           # scaffold steps/<name>.py + .json

montaj validate step <filename>     # validate a step schema
montaj validate project <filename>  # validate a project.json
montaj validate workflow <filename> # validate a workflow .json

FILE=$(montaj step rm_fillers --input clip.mp4 --model base.en)
FILE=$(montaj step waveform_trim --input "$FILE")
FILE=$(montaj step resize --input "$FILE" --ratio 9:16)

montaj fetch --url "https://www.tiktok.com/@handle/video/123"
# Download a single video via yt-dlp

montaj fetch --url "https://www.tiktok.com/@handle" --limit 15 --out ./clips/
# Download up to N videos from a profile or playlist

montaj init --prompt "tight cuts, remove filler"
# Create empty project.json in current directory

montaj init --prompt "..." --color-space hdr_hlg
# Force the project's working color space. Default is `auto`, which picks
# the MODAL (most common) color space across clips — outliers are
# converted on the fly. 27 HLG + 1 SDR → hdr_hlg (the SDR clip is stretched).
# Tiebreaks: PQ wins HDR-only ties; SDR wins SDR-vs-HDR ties.
# Choices: auto | sdr_bt709 | hdr_hlg | hdr_pq. Peer of --resolution.

montaj init --prompt "..." --resolution 1080x1920
# Force the project's output resolution. Default is `auto`, which preserves
# the MODAL source resolution. Mixed-aspect inputs (portrait + landscape)
# are scale-fit and center-padded to the chosen canvas at compose time.
# Format: WxH (e.g. 1080x1920, 3840x2160). Peer of --color-space.

montaj init --prompt "..." --project-path my-project
# Pin the project directory's path under the workspace root. Single segment
# for flat layouts (`my-project`), multi-segment slash-separated for nested
# layouts (`teamA/my-project`). Intermediate directories are created on
# demand. When omitted, the directory name is generated as `<date>-<slug>`
# from --name (or `<date>-<HHMMSS>` if --name is also absent). Useful for
# sidecar deploys where the caller already has its own project ID and wants
# to skip the date prefix. Segments must match `[A-Za-z0-9_-]+`; collisions
# on an explicit path are hard errors, not auto-suffixed.

montaj init --workflow carousel --carousel-aspect portrait --prompt "..."
# Create an image-carousel project. --carousel-aspect picks the slide ratio:
# `square` (1:1, 1080x1080), `portrait` (4:5, 1080x1350), or `vertical`
# (9:16, 1080x1920). Locked at creation. Add reference images with --asset
# (repeatable); they're copied into the workspace and surface in
# project.assets[]. The agent reads project.json + project.assets and the
# `montaj/carousel` callable skill to author slides. See projects/carousel
# for the full flow.

montaj init --prompt "..." \
  --remote-clip '{"url":"https://...","destPath":"clip1.mp4","contentType":"video/mp4","sizeBytes":12345}' \
  --remote-asset '{"url":"https://...","destPath":"logo.png","contentType":"image/png","sizeBytes":678}'
# Fetch clips/assets from remote URLs at init time (S3 pre-signed, R2, GCS,
# Azure SAS, plain HTTPS) directly into the project workspace. Repeatable.
# For batch input use --remote-clips-file / --remote-assets-file pointing at
# a JSON array of the same item shape. Fail-closed: requires
# MONTAJ_HTTP_ALLOWED_HOSTS in the environment (comma-separated lowercase
# hostnames). Content-type and byte count are verified against declared
# values; writes are atomic.

montaj upload --project <id-or-path> \
  --src output/render.mp4 --to "https://..." \
  --src output/manifest.json --to "https://..."
# Push project workspace files to caller-supplied URLs. --src/--to is a
# repeatable pair. Returns 200 on full success or 207 Multi-Status on
# partial failure (per-op results in stdout). Use this with cloud
# storage's pre-signed PUT URLs to ship renders without provider-specific
# code in Montaj. Same allowlist gate as remote inputs.

montaj status
# Show current project.json state + step progress

montaj approve
# ai_video projects only — mark the storyboard as approved

montaj doctor
# Check all system dependencies (ffmpeg filters, ffprobe, node, whisper)
# Exit 0 = OK, exit 1 = issues

montaj regen <clip_id>
# Queue a full-scene regeneration for an ai_video clip

montaj regen subcut <clip_id>
# Queue a sub-range regeneration within a clip

montaj profile
# Manage creator style profiles

montaj profile asset list <name>
# List all assets registered in the profile's asset library

montaj profile asset add <name> <path> [--description TEXT] [--tags A,B,C]
# Copy a file into the profile's assets dir and register it in the manifest

montaj profile asset rm <name> <filename>
# Remove an asset from the library (deletes the file and its manifest entry)

montaj profile asset notes <name> --get
# Print the profile-wide creative notes

montaj profile asset notes <name> --set "your notes here"
# Overwrite the profile-wide creative notes

montaj sample overlay <overlay.jsx> --out <path.png>
# Render frame 0 at default canvas (1080×1920)

montaj sample overlay <overlay.jsx> --frame 30 --out /tmp/frame30.png
# Render frame 30

montaj sample overlay <overlay.jsx> --measure --out /tmp/check.png
# Also return per-element bounding-box and overflow data as JSON

{
  "pngPath": "/tmp/check.png",
  "measurements": {
    "anyOverflow": true,
    "viewport": { "w": 1080, "h": 1920 },
    "texts": [
      {
        "text": "RECURSIVE",
        "tag": "DIV",
        "fontFamily": "Syne, sans-serif",
        "fontSize": "160px",
        "bbox": { "x": -257, "y": 740, "w": 1594, "h": 154 },
        "overflow": { "left": 257, "right": 257, "top": 0, "bottom": 0 },
        "clippingAncestor": null
      }
    ]
  }
}

# Check a headline overlay before adding it to project.json
montaj sample overlay ~/.montaj/overlays/headline.jsx \
  --google-fonts "Syne:wght@800" \
  --measure \
  --out /tmp/headline-check.png

montaj sample frame <project.json> --at <seconds>
# Default output: <project_dir>/render/samples/frame-<t>s.png

montaj sample frame <project.json> --at 5.5 --out /tmp/frame5.5.png

# Verify an overlay isn't covering the speaker's face at t=5.5s
montaj sample frame ./my-project/project.json --at 5.5 --out /tmp/t5.5.png