> ## 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.

# CLI

> Use Modellix from terminal to create model tasks and fetch results.

`modellix-cli` is the official command-line tool for [Modellix](https://modellix.ai).
It helps you call the Modellix async model API from terminal and automate workflows in scripts or AI agents.

For full API behavior and response fields, see the official [REST API docs](/ways-to-use/api).

## What You Can Do

* Create async model generation tasks
* Query task status and final generation result

## Install

```bash theme={null}
npm install -g modellix-cli
modellix-cli --version
```

## Authentication

You can provide API key in either way:

1. Recommended: environment variable `MODELLIX_API_KEY`
2. Alternative: `--api-key` flag in each command

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

```powershell theme={null}
# Windows PowerShell
$env:MODELLIX_API_KEY="your_api_key"
```

## Create a Task

### Use inline JSON body

```bash theme={null}
modellix-cli model invoke \
  --model-slug bytedance/seedream-4.5-t2i \
  --body '{"prompt":"A cute cat playing in a garden on a sunny day"}'
```

### Use JSON file body

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

### Common flags

* `--model-slug` (required): model slug in `provider/model` format, for example `bytedance/seedream-4.5-t2i`
* `--body`: request JSON string
* `--body-file`: path to request JSON file
* `--api-key`: API key (overrides `MODELLIX_API_KEY`)

Example success response:

```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"
    }
  }
}
```

## Query Task Result

Use the returned `task_id`:

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

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"
        }
      ]
    }
  }
}
```

## Recommended Workflow

1. Run `modellix-cli model invoke ...` and copy the returned `task_id`.
2. Run `modellix-cli task get <task_id>` to get status and result.

`modellix-cli model invoke` returns immediately with a `task_id`, so you need to poll `task get` to track progress.

## Error Handling Guide

The CLI surfaces API errors directly. Use the error code to decide whether to fix inputs or retry.

* `400`: fix parameters or request body format before retrying.
* `401`: your API key is missing, invalid, or expired. Verify `MODELLIX_API_KEY` or pass `--api-key`.
* `402`: your account balance is insufficient. Recharge in the Modellix console and retry.
* `404`: verify `task_id` and `--model-slug`.
* `429`: you hit rate or concurrency limits. Retry with exponential backoff (for example: 1s, 2s, 4s).
* `500` / `503`: temporary server-side issue. Retry up to 3 times with backoff.

## Help

```bash theme={null}
modellix-cli --help
modellix-cli model invoke --help
modellix-cli task get --help
```