# Artillect CLI

Artillect CLI — генерация картинок и видео из терминала. Тот же аккаунт и баланс, что в студии.

Интерактивная страница: [/docs/cli](/docs/cli).

## Содержание

- [Установка](#установка)
- [Быстрый старт](#быстрый-старт)
- [Примеры](#примеры)
- [Элементы и storage](#элементы-и-storage)
- [Задачи](#задачи)
- [Команды](#команды)
- [Флаги](#флаги)
- [Результат](#результат)
- [Обновление](#обновление)
- [Если не работает](#если-не-работает)

## Установка

```bash
npm install -g @artillect/cli
```

Нужен Node.js 20+. Без глобальной установки: `npx @artillect/cli@latest --help`.

## Быстрый старт

```bash
artillect auth login
artillect generate image --prompt "кот в космосе" --wait --open
```

Ключ также можно задать через `ARTILLECT_API_KEY`.

## Примеры

### Картинка

```bash
artillect generate image \
  --model seedream-5-pro \
  --prompt "современная архитектура, золотой час" \
  --wait --open
```

### Видео — Grok

```bash
artillect generate video grok-imagine-video \
  --prompt "кот идёт по комнате, простой план" \
  --wait --open
```

### Видео — Kling 3 со стартовым кадром

```bash
artillect generate video kling-3 \
  --prompt "медленный проезд камеры через лес на рассвете" \
  --start-image ./first.png \
  --wait
```

### Цена до сабмита

```bash
artillect estimate image -m seedream-5-pro -p "кот в космосе"
artillect estimate video -m grok-imagine-video -p "кот идёт"
```

### Каталог

```bash
artillect models list
artillect models list -k video
artillect models get grok-imagine-video --json
```

## Элементы и storage

Файл в storage — стабильный `ast_…`. Список страницами: если в конце есть `дальше --cursor …`, повторите команду с этим флагом.

Элемент — запись в библиотеке проекта: в промпте `@Hero`. Хранится в Kling-shape. Как уходит в модель, решает сервер:

- `kling-3` / `kling-o3` — нативные элементы провайдера (не turbo)
- остальные модели — `@Hero` парсится, frontal подставляется как референс

Нужен `--project`.

```bash
artillect projects list
artillect upload ./hero.png --project 12
artillect assets list --project 12
artillect assets list --project 12 --cursor ast_01ARZ3NDEKTSV4RRFFQ69G5FAV
```

```bash
artillect elements create --project 12 --name Hero --file ./hero.png
artillect generate video kling-3 \
  --project 12 \
  --prompt "@Hero идёт по улице" \
  --start-image ast_01ARZ3NDEKTSV4RRFFQ69G5FAV \
  --wait
```

```bash
artillect generate video seedance-2 \
  --project 12 \
  --prompt "@Hero идёт по улице" \
  --wait
```

`--input` / `--start-image` / `--end-image` принимают локальный файл, HTTPS или `ast_…`.

## Задачи

Без `--wait` команда сразу печатает `task_id`. Дальше можно смотреть статус, ждать файл или отменить.

```bash
artillect generate image --prompt "кот"
artillect generate get <task_id>
artillect generate wait <task_id> --open
artillect generate cancel <task_id>
```

## Команды

| Команда              | Зачем                                             |
| -------------------- | ------------------------------------------------- |
| `artillect auth`     | login / logout / status                           |
| `artillect balance`  | баланс токенов                                    |
| `artillect models`   | list / get — каталог и схема параметров с сервера |
| `artillect generate` | image / video / get / wait / list / cancel        |
| `artillect estimate` | цена до генерации, без списания                   |
| `artillect upload`   | загрузить файл, получить ast_…                    |
| `artillect assets`   | list / get / copy — storage ast_…                 |
| `artillect projects` | list — проекты аккаунта                           |
| `artillect elements` | list / create — @Name в проекте                   |

Подсказки по флагам: `artillect --help`, `artillect generate image --help`.

## Флаги

| Флаг             | Зачем                                                 |
| ---------------- | ----------------------------------------------------- |
| `--wait`         | ждать готовности и скачать файл                       |
| `--wait-timeout` | лимит ожидания, по умолчанию `20m` (ещё `90s`, `10m`) |
| `--out`          | папка для файлов, по умолчанию текущая                |
| `--open`         | открыть скачанный файл                                |
| `--json`         | сырой JSON для скриптов                               |
| `--project`      | id проекта: лента, storage, @элементы                 |
| `--cursor`       | следующая страница list                               |

## Результат

С `--wait` CLI печатает путь к файлу в текущей папке. С `--open` сразу открывает его. Без флага — `open ./artillect-….png` на macOS или клик по пути в Terminal.

## Обновление

```bash
npm i -g @artillect/cli@latest
```

npm сам пакет на компьютере не обновляет. Когда выйдет версия, CLI подскажет в терминале.

## Если не работает

- `Нет входа` — `artillect auth login` или `ARTILLECT_API_KEY`.
- Каталог всегда с сервера: `artillect models list`. Слаги вроде `kling-3`, не `kie-vp-…`.
- Для скриптов: `--json`. Прогресс идёт в stderr, результат — в stdout.