uncutly

Agent-native command line interface for Uncutly.AI — unrestricted creative image and video generation, scriptable from a terminal or an AI agent's tool-calling loop.

Structured, predictable output; deterministic exit codes; no interactive prompts required. Designed to be driven by scripts, CI, and autonomous agents as comfortably as by a human at a keyboard.

Install

npm install -g uncutly

Requires Node.js 18 or newer (uses the built-in fetch).

Authenticate

uncutly auth login

This starts a device authorization flow: the CLI prints a short code and a URL, you open the URL in any browser (on any device) and approve, and the CLI polls in the background until the token lands. The token is written to ~/.config/uncutly/config.json (mode 600, owner-read-only).

uncutly auth status     # who am I, plan, credit balance
uncutly auth status --json
uncutly auth logout     # revoke and remove the local token

Token resolution order

1. UNCUTLY_API_TOKEN environment variable (highest priority — useful in CI/agents)
2. token stored by uncutly auth login in ~/.config/uncutly/config.json

API base resolution order

1. --api-base <url> flag
2. UNCUTLY_API_BASE environment variable
3. apiBase stored in the config file
4. https://uncutly.ai/api/v1 (default)

Commands

uncutly models

List available generation models with their credit cost.

uncutly models
uncutly models --json

uncutly create image

Text-to-image generation.

uncutly create image --prompt "a neon-lit alley at night, cinematic" \
  --model seedream-4.5 \
  --aspect-ratio 9:16 \
  --out ./out

| Flag | Description | | --- | --- | | --prompt <text> | required. Generation prompt. | | --model <id> | Model id from uncutly models. Defaults to the first available text-to-image model. | | --aspect-ratio <ratio> | e.g. 9:16, 1:1, 16:9. | | --negative-prompt <text> | Negative prompt. | | --count <n> | Run N generations sequentially (1–20). Default 1. | | --out <dir> | Output directory. Default ./out. | | --json | Print a machine-readable JSON summary instead of progress output. | | --no-wait | Return immediately after the job is queued instead of waiting for completion / downloading. |

uncutly create video

Text-to-video generation. Pass --image to switch to image-to-video.

uncutly create video --prompt "slow dolly-in on a city skyline at dusk" --out ./out
uncutly create video --prompt "the subject turns and smiles" --image ./photo.jpg --out ./out

Same flags as create image, minus --aspect-ratio, plus:

| Flag | Description | | --- | --- | | --image <path> | Local image file to animate (uploaded via POST /uploads/direct). Switches model selection to image-to-video. |

uncutly jobs <id>

uncutly jobs job_abc123
uncutly jobs job_abc123 --wait --json

| Flag | Description | | --- | --- | | --wait | Poll every 3s until the job reaches succeeded or failed. | | --json | Print the raw job object as JSON. |

Output modes

Interactive terminal (TTY): a live, self-erasing progress bar plus a short PixVerse-style status rhythm:

✳ generating · Seedream 4.5 · 30 credits
████████████████████░░░░░░░░░░░░░░░░░░░░  52%  ~8s
✓ done in 11.4s · image
→ ./out/8f3c9a2b.png

Non-interactive (CI, pipes, agent tool calls): progress is logged as plain append-only lines (roughly every 10% of progress) instead of a redrawn bar — safe to capture in logs, never emits \r control bytes. Detected automatically (stdout.isTTY), or forced off with CI=1 / UNCUTLY_NO_TTY=1.

--json: all human-readable/progress output is suppressed. create image / create video print exactly one JSON object per generation to stdout:

{"jobId":"job_abc123","status":"succeeded","resultId":"res_xyz","files":["/abs/path/out/8f3c9a2b.png"],"credits":30,"elapsedSeconds":11.4,"failed":false}

With --count greater than 1, one such JSON object is printed per completed generation (JSON Lines — one object per line), not a single array, so output can be streamed and parsed incrementally by an agent.

Exit codes

| Code | Meaning | | --- | --- | | 0 | Success. | | 1 | Generation failed, or the server rejected the request for a business reason (e.g. a premium-only feature). | | 2 | Bad arguments — invalid flags, missing required options, out-of-range values. Never reached the network. | | 3 | Not authenticated, or the stored token was rejected by the server. Run uncutly auth login. | | 4 | Insufficient credits. | | 5 | Network or server error (unreachable host, 5xx response, malformed response body). |

Downloaded files and unlocking

If your account does not have full access to a result (e.g. a locked preview pending an unlock/subscription), the CLI downloads the best asset it is authorized to fetch and prints a note that it is a locked preview rather than the full-resolution export. This is not treated as a failure (the generation itself succeeded); check the printed note, or the --json output, if you need to distinguish the two.

Development

pnpm install
pnpm run build   # tsc -> dist/
pnpm test        # vitest
node dist/index.js --help

License

MIT