> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modellix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Modellix CLI for Image, Video, and Audio Generation

> Use modellix-cli to authenticate, discover models, inspect request schemas, submit async image, video, and audio tasks, wait for results, and download assets from the terminal or CI.

`modellix-cli` is the official command-line client for [Modellix](https://modellix.ai).
Use it to manage authentication profiles, discover and run models, inspect request schemas, 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](/ways-to-use/api) guide.
Package details: [npm](https://www.npmjs.com/package/modellix-cli) · [GitHub](https://github.com/Modellix/modellix-cli)

## Requirements

* Node.js 18.17 or later
* A Modellix API key from the [Modellix Console](https://www.modellix.ai/console/api-key) (`model get-schema` is public and does not need one)

## Install

```bash theme={null}
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.

```bash theme={null}
modellix-cli
modellix-cli quickstart
modellix-cli --help
```

## Quickstart

<Steps>
  <Step title="Store and Validate an API Key">
    ```bash theme={null}
    modellix-cli init
    ```

    Or set `MODELLIX_API_KEY` for temporary and CI usage (see [Authentication](#authentication-and-profiles)).
  </Step>

  <Step title="Check the Environment">
    ```bash theme={null}
    modellix-cli doctor
    ```
  </Step>

  <Step title="Discover Model Slugs">
    ```bash theme={null}
    modellix-cli model list
    ```
  </Step>

  <Step title="Inspect a Model Schema">
    ```bash theme={null}
    modellix-cli model get-schema bytedance/seedream-4.5-t2i
    ```
  </Step>

  <Step title="Submit a Model Task">
    ```bash theme={null}
    modellix-cli model run \
      --model-slug bytedance/seedream-4.5-t2i \
      --body '{"prompt":"A cute cat playing in a sunny garden"}'
    ```
  </Step>

  <Step title="Query the Returned Task ID">
    ```bash theme={null}
    modellix-cli task get task-abc123
    ```
  </Step>
</Steps>

## Authentication and Profiles

Authenticated commands select a profile in this order:

1. `--profile`
2. `MODELLIX_PROFILE`
3. the saved `currentProfile`
4. `default`

They resolve the API key independently in this order:

1. `--api-key`
2. `MODELLIX_API_KEY`
3. the selected saved profile

### Recommended Setup

```bash theme={null}
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:

```bash theme={null}
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)

```bash theme={null}
# macOS / Linux
export MODELLIX_API_KEY="your_api_key"
```

```powershell theme={null}
# 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

```bash theme={null}
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

```bash theme={null}
modellix-cli config path
modellix-cli config show
modellix-cli config show --json
modellix-cli config clear --profile work --yes
```

## Diagnose the Environment

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
modellix-cli model describe google/nano-banana-2
modellix-cli model describe google/nano-banana-2 --json
```

## Get a Model API Schema

Use the exact `provider/model` value returned by `model list`.
This command calls the public [Get Schema](/api/get-schema) endpoint on `https://www.modellix.ai` and does not require an API key.

```bash theme={null}
modellix-cli model list --output slugs
modellix-cli model get-schema alibaba/qwen-image-3.0-pro
modellix-cli model get-schema alibaba/qwen-image-3.0-pro --output human
modellix-cli model get-schema alibaba/qwen-image-3.0-pro --quiet
```

JSON is the default. It preserves the complete `servers` and `post` fields returned by Modellix.
Human output summarizes the inference endpoint, summary, description, request body, and responses.
Quiet output prints only `servers[0].url` for scripts.

The printed inference URL is the async generate path on `https://api.modellix.ai`. Submitting a task with that URL, or with `model run`, still requires a Bearer API key.

The default schema host is `https://www.modellix.ai`. Pass `--base-url` only when testing a compatible local schema endpoint, for example `http://127.0.0.1:3000`. Setting `MODELLIX_BASE_URL` to `https://api.modellix.ai` overrides that default and will miss the public schema endpoint.

## Run a Model

### Inline JSON Body

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

### JSON File Body

```bash theme={null}
modellix-cli model run \
  --model-slug alibaba/qwen-image-edit \
  --body-file ./payload.json
```

### Pipe JSON from Stdin

```bash theme={null}
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

```bash theme={null}
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.

<Warning>
  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.
</Warning>

### Compatibility Alias

`modellix-cli model invoke` remains an alias of `model run`.
New scripts should use `model run`.

Example success response (async submit):

```json theme={null}
{
  "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):

```json theme={null}
{"modelSlug":"google/nano-banana-2","body":{"prompt":"First image"}}
{"modelSlug":"google/nano-banana-2","body":{"prompt":"Second image"}}
```

```bash theme={null}
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

```bash theme={null}
modellix-cli task get task-abc123
modellix-cli task get task-abc123 --output human
modellix-cli task get task-abc123 --quiet
```

Example success response:

```json theme={null}
{
  "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

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
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, inference 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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
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. |
| Schema slug not found | Confirm the slug with `model list --output slugs`, then retry `model get-schema`. |
| 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`, `--model-slug`, or the `model get-schema` slug
* `429`: rate or concurrency limits
* `500` / `503`: temporary server-side issue

## Help

```bash theme={null}
modellix-cli --help
modellix-cli help --nested-commands
modellix-cli model run --help
modellix-cli model get-schema --help
modellix-cli task wait --help
```

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