# ViewMax CLI

Reference for the viewmax command-line client for video generation tasks. The package is not yet published to npm.

## Availability

`viewmax-cli` is not published to npm yet, so `npm install -g viewmax-cli` fails. Until it is, create tasks from scripts and CI with the [REST API](https://viewmax.studio/docs/api), or from an agent with [MCP](https://viewmax.studio/docs/mcp). This page documents the commands the package provides.

The CLI requires Node.js 20 or later and has no runtime dependencies. It covers video only; use the REST API or MCP for images, music, and audio.

## Configure an API key

```bash
viewmax config set-key sk-your-api-key
```

The command saves the key to `~/.config/viewmax/config.json` with file mode 600. The key must start with `sk-`. For one shell or CI, use an environment variable instead:

```bash
export VIEWMAX_API_KEY=sk-your-api-key
```

For authenticated commands, the CLI resolves credentials in this order: `--api-key`, `VIEWMAX_API_KEY`, then the saved config. `viewmax models` is public and does not send a key.

## Commands

```bash
viewmax config set-key <sk-...> [--json]
viewmax models [--json]
viewmax credits [--json]
viewmax generate -m <model> -p <prompt> [options]
viewmax task <task_id> [--wait] [--output file] [--json]
viewmax help
```

### `models`

Lists the public video catalog (`GET /api/v1/models`), one `id  label — vendor (credits)` line per model. Add `--json` for the full catalog with each mode's durations, resolutions, aspect ratios, `defaults`, and credit pricing.

### `credits`

Prints the authenticated account's remaining credits.

### `generate`

```bash
viewmax generate -m viewmax-c1 -p "A paper kite crossing a bright summer sky" \
  --duration 5s --resolution 768P --aspect-ratio 16:9 \
  --idempotency-key kite-demo-001 --wait --output kite.mp4
```

This task costs 10 credits (ViewMax C1 bills 2 credits per second).

| Option                      | Meaning                                                                                                                                                      |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `-m`, `--model`             | Required model ID                                                                                                                                            |
| `-p`, `--prompt`            | Required prompt                                                                                                                                              |
| `--mode`                    | Video mode such as `text-to-video` or `image-to-video`. The CLI cannot send `video_urls`                                                                     |
| `--image <url>`             | Public source image URL; repeat for multiple images. Sets `image-to-video` when `--mode` is omitted                                                          |
| `--duration <duration>`     | A duration the model lists, such as `5s`; omitted values use the mode's default                                                                              |
| `--resolution <resolution>` | A resolution the model lists, such as `768P`                                                                                                                 |
| `--aspect-ratio <ratio>`    | An aspect ratio the model lists, such as `16:9`                                                                                                              |
| `--audio`                   | Request audio; only for modes whose `audio_toggle` is `true`                                                                                                 |
| `--idempotency-key <key>`   | Sent as the `Idempotency-Key` header (1–200 visible ASCII characters, no spaces). Rerunning with the same key returns the original task without a new charge |
| `--wait`                    | Poll every 5 seconds for up to 10 minutes                                                                                                                    |
| `--output <file>`           | Wait for the task, then download its first `taskUrls` entry to a file (implies `--wait`)                                                                     |

Without `--wait` or `--output`, `generate` prints `Created task <id>: <status> (<credits> credits)`. Human-readable output does not print result URLs; use `--json` and read `taskUrls`, or use `--output`.

### `task`

Reads a task by ID. Use `--wait` to poll it and `--output` to download its first result. When a task ends `failed` or `canceled`, the CLI prints the reason from `taskInfo.errorMessage` and exits `1`; the credits are refunded automatically.

## Shared options, output, and exit codes

`--base-url <url>` overrides the default `https://viewmax.studio`, which is useful for a test deployment. `--api-key <key>` overrides the environment and saved key. `--json` prints bare JSON to stdout: `data` on success, or the API error envelope `{ code, message, error }` on failure.

| Exit code | Meaning                                                                         |
| --------- | ------------------------------------------------------------------------------- |
| `0`       | Success                                                                         |
| `1`       | API error, `failed` or `canceled` task, download failure, or a `--wait` timeout |
| `2`       | Invalid usage, including an unknown option, missing `-m`/`-p`, or no API key    |

After a `--wait` timeout the task keeps running; resume with `viewmax task <task_id> --wait`. Check `viewmax models --json` before generating: creation consumes the model's configured credits.