CLI

modellix-cli is the official command-line client for Modellix. Use it to manage authentication profiles, discover and run models, wait for asynchronous tasks, download results, and produce stable output for scripts and agents. For full API behavior and response fields, see the REST API guide. Package details: npm · GitHub

Requirements

Node.js 18.17 or later
A Modellix API key from the Modellix Console

Install

npm install --global modellix-cli
modellix-cli --version

Running modellix-cli with no arguments prints a local Quickstart. It does not call the API or start an interactive wizard.

modellix-cli
modellix-cli quickstart
modellix-cli --help

Quickstart

Store and validate an API key

modellix-cli init

Or set MODELLIX_API_KEY for temporary and CI usage (see Authentication).

Check the environment

modellix-cli doctor

Discover model slugs

modellix-cli model list

Submit a model task

modellix-cli model run \
  --model-slug bytedance/seedream-4.5-t2i \
  --body '{"prompt":"A cute cat playing in a sunny garden"}'

Query the returned task ID

modellix-cli task get task-abc123

Authentication and profiles

Authenticated commands select a profile in this order:

--profile
MODELLIX_PROFILE
the saved currentProfile
default

They resolve the API key independently in this order:

--api-key
MODELLIX_API_KEY
the selected saved profile

Recommended setup

modellix-cli auth login
modellix-cli auth login --profile work
modellix-cli auth status --profile work

modellix-cli init is the short setup command and supports the same profile selection. Interactive prompts hide the key, and the CLI validates it before writing. Non-interactive setup:

modellix-cli init --api-key "$MODELLIX_API_KEY" --yes
modellix-cli init --api-key "$MODELLIX_API_KEY" --yes --json
modellix-cli init --api-key "$MODELLIX_API_KEY" --check

Environment variable (CI and temporary use)

# macOS / Linux
export MODELLIX_API_KEY="your_api_key"

# Windows PowerShell
$env:MODELLIX_API_KEY = "your_api_key"

Prefer the hidden prompt or an environment variable over --api-key on the command line, which can remain in shell history. auth status, auth whoami, config show, and JSON status output never print the credential value.

Auth commands

modellix-cli auth login [--profile NAME]
modellix-cli auth status [--profile NAME] [--json]
modellix-cli auth whoami [--profile NAME] [--json]
modellix-cli auth logout [--profile NAME] [--yes]

Local configuration

modellix-cli config path
modellix-cli config show
modellix-cli config show --json
modellix-cli config clear --profile work --yes

Diagnose the environment

modellix-cli doctor
modellix-cli doctor --json

doctor checks the Node.js version, reports the API-key source without printing the key, validates API connectivity, and reads the team balance when authentication succeeds. A failed required check returns a non-zero exit status.

Discover models

modellix-cli model list
modellix-cli model list --type text-to-image --output slugs
modellix-cli model list --provider google --limit 20
modellix-cli model list --search banana

Use --quiet or --output slugs to print one slug per line. Inspect one model:

modellix-cli model describe google/nano-banana-2
modellix-cli model describe google/nano-banana-2 --json

Run a model

Inline JSON body

modellix-cli model run \
  --model-slug bytedance/seedream-4.5-t2i \
  --body '{"prompt":"A cute cat"}'

JSON file body

modellix-cli model run \
  --model-slug alibaba/qwen-image-edit \
  --body-file ./payload.json

Pipe JSON from stdin

printf '%s' '{"prompt":"A cute cat"}' | \
  modellix-cli model run --model-slug google/nano-banana-2 --body-file -

Common flags

--model-slug (required): exact provider/model value from model list
--body: request JSON string
--body-file: path to a JSON file, or - for stdin
--api-key: API key (overrides environment and saved profile)
--wait: poll until the task reaches a terminal state
--timeout: wait deadline (for example 5m, 30s, or bare seconds)
--output task-id: print only the new task ID for shell pipelines

Use either --body or --body-file, not both. The request body must be a JSON object and is capped at 64 MiB.

Submit and wait in one command

modellix-cli model run \
  --model-slug google/nano-banana-2 \
  --body '{"prompt":"A cute cat"}' \
  --wait --timeout 5m --quiet

The default remains asynchronous. If waiting times out after a task ID is received, the error prints that ID and a safe task wait recovery command.

Paid POST submissions are never automatically retried. If a network or protocol failure leaves the submission outcome unknown, do not immediately repeat the same request—check task history and account activity first.

Compatibility alias

modellix-cli model invoke remains an alias of model run. New scripts should use model run. Example success response (async submit):

{
  "code": 0,
  "message": "success",
  "data": {
    "status": "pending",
    "task_id": "task-abc123",
    "model_id": "alibaba/qwen-image-plus",
    "get_result": {
      "method": "GET",
      "url": "https://api.modellix.ai/api/v1/tasks/task-abc123"
    }
  }
}

Batch model tasks

model batch accepts one JSON object per line (JSONL):

{"modelSlug":"google/nano-banana-2","body":{"prompt":"First image"}}
{"modelSlug":"google/nano-banana-2","body":{"prompt":"Second image"}}

modellix-cli model batch tasks.jsonl --max-tasks 10 --concurrency 3
cat tasks.jsonl | modellix-cli model batch - --yes --wait --quiet

Batch submission requires either --max-tasks or explicit --yes, because every line can create a paid task. All slugs and JSON bodies are validated before the first POST. Concurrency is limited to 1–10, and the absolute local limit is 1000 tasks.

Query, wait, and download tasks

Get a task result

modellix-cli task get task-abc123
modellix-cli task get task-abc123 --output human
modellix-cli task get task-abc123 --quiet

Example success response:

{
  "code": 0,
  "message": "success",
  "data": {
    "status": "success",
    "task_id": "task-abc123",
    "result": {
      "resources": [
        {
          "url": "https://cdn.example.com/images/abc123.png",
          "type": "image"
        }
      ]
    }
  }
}

Wait for one or more tasks

modellix-cli task wait task-abc123
modellix-cli task wait task-a task-b --interval 5s --timeout 10m --concurrency 8

Bare time values remain seconds. One invocation accepts at most 1000 unique IDs. Any failed terminal task exits 1. An overall timeout exits 124; JSON mode includes completed responses and unfinishedTaskIds.

Download task resources

modellix-cli task download task-abc123 --output-dir ./results
modellix-cli task download task-abc123 --output-dir ./results --json

Downloads require a successful task. Existing files are preserved by default; use --overwrite deliberately. JSON output contains local paths and byte counts, not signed source URLs.

Local task history

Successful submissions are recorded locally so task IDs remain recoverable:

modellix-cli task history
modellix-cli task history --limit 50 --json
modellix-cli task history --profile work --json
modellix-cli task history --clear --yes

History stores Task ID, profile, API origin, model slug, status, and timestamps—never an API key or request body.

Output, automation, and CI

Built-in Modellix business commands accept these common output controls:

Flag	Behavior
`--json` / `--output json`	One machine-readable JSON document. Failures use `{ "ok": false, "error": { "exitCode", "message" } }`.
`--quiet` / `-q` / `--output quiet`	Only the primary value (slugs, task IDs, resource URLs, or local paths).
`--output human`	Concise readable output.
`--output slugs`	Compatible format for `model list` (one slug per line).
`--output task-id`	Compatible format for `model run` (task ID only).

When flags overlap, quiet wins over JSON, then JSON wins over the command default. Business output uses stdout; warnings, debug details, and recovery instructions use stderr. For CI:

modellix-cli init --api-key "$MODELLIX_API_KEY" --yes --json
modellix-cli doctor --json --no-color --no-progress

CI automatically disables colors, progress-capable output, and the background update check. Set MODELLIX_CLI_SKIP_NEW_VERSION_CHECK=true to disable the update check explicitly.

Exit codes

Code	Meaning
`0`	Success
`1`	API, task, operation, or command validation failure
`2`	Argument-parser rejection or an explicit safety guard (for example batch cost limit)
`124`	Local task wait timeout; the remote task may still be running
`127`	Unknown command; suggestions are never executed automatically

Networking and diagnostics

Override the API origin for a trusted gateway or local development server:

modellix-cli doctor --base-url https://gateway.example.com
MODELLIX_BASE_URL=https://gateway.example.com modellix-cli model list

HTTPS is required; HTTP is accepted only for localhost, 127.0.0.1, or ::1. Sanitized request diagnostics go to stderr:

modellix-cli model list --verbose
modellix-cli model list --debug

Diagnostics include method, endpoint path, retry attempt, response status, and elapsed time. They exclude API keys, request bodies, and response bodies.

Shell completion

modellix-cli autocomplete
modellix-cli autocomplete bash
modellix-cli autocomplete zsh
modellix-cli autocomplete powershell

Troubleshooting

Problem	What to do
Missing API key	Run `modellix-cli init`, set `MODELLIX_API_KEY`, or pass `--api-key`.
`401 Unauthorized`	Repair auth with `init` or `auth login`, then verify with `doctor`.
`402 Payment Required`	Recharge in the Modellix Console and retry.
`429 Too Many Requests`	Read-only commands already retry within their deadline. Do not blindly retry paid submissions.
Paid submission outcome unknown	Check `task history` and account activity before submitting again.
Download blocked	Downloads default to HTTPS and public network destinations. Use `--allow-insecure-http` or `--allow-private-network` only in explicitly trusted environments.

API error codes the CLI surfaces:

400: fix parameters or request body format before retrying
401: API key missing, invalid, or expired
402: insufficient balance
404: verify task_id and --model-slug
429: rate or concurrency limits
500 / 503: temporary server-side issue

Help

modellix-cli --help
modellix-cli help --nested-commands
modellix-cli model run --help
modellix-cli task wait --help

Misspelled commands receive a nearest-command suggestion. Suggestions are never executed automatically.

Getting Started

Ways to Use

Requirements

Install

Quickstart

Authentication and profiles

Recommended setup

Environment variable (CI and temporary use)

Auth commands

Local configuration

Diagnose the environment

Discover models

Run a model

Inline JSON body

JSON file body

Pipe JSON from stdin

Common flags

Submit and wait in one command

Compatibility alias

Batch model tasks

Query, wait, and download tasks

Get a task result

Wait for one or more tasks

Download task resources

Local task history

Output, automation, and CI

Exit codes

Networking and diagnostics

Shell completion

Troubleshooting

Help

​Requirements

​Install

​Quickstart

​Authentication and profiles

​Recommended setup

​Environment variable (CI and temporary use)

​Auth commands

​Local configuration

​Diagnose the environment

​Discover models

​Run a model

​Inline JSON body

​JSON file body

​Pipe JSON from stdin

​Common flags

​Submit and wait in one command

​Compatibility alias

​Batch model tasks

​Query, wait, and download tasks

​Get a task result

​Wait for one or more tasks

​Download task resources

​Local task history

​Output, automation, and CI

​Exit codes

​Networking and diagnostics

​Shell completion

​Troubleshooting

​Help

Requirements

Install

Quickstart

Authentication and profiles

Recommended setup

Environment variable (CI and temporary use)

Auth commands

Local configuration

Diagnose the environment

Discover models

Run a model

Inline JSON body

JSON file body

Pipe JSON from stdin

Common flags

Submit and wait in one command

Compatibility alias

Batch model tasks

Query, wait, and download tasks

Get a task result

Wait for one or more tasks

Download task resources

Local task history

Output, automation, and CI

Exit codes

Networking and diagnostics

Shell completion

Troubleshooting

Help