---
title: The CLI
description: Install the nolgia CLI, log in, generate images, video and audio, and script it with JSON output.
---

# The CLI

Use `nolgia` to generate media, follow jobs and manage your library from a terminal; add `--json` when another program will read the output.

## Install

Choose one installation method.

```bash tab="Homebrew"
$ brew install nolgiainc/nolgia/nolgia
```

```bash tab="npm"
$ npm install -g @nolgia/cli
```

```bash tab="Cargo"
$ cargo install nolgia-cli
```

```bash tab="curl installer"
$ curl -fsSL https://raw.githubusercontent.com/nolgiainc/nolgia-cli/main/install.sh | bash
```

### Platforms

The installer and the released binaries cover every target below. The Linux musl builds are statically linked, so the CLI runs in a slim container — Alpine, `debian:bookworm-slim` — with no libc to install first.

<!-- gen:cli-platforms -->
| Platform | Architectures | Install |
| --- | --- | --- |
| macOS | Apple silicon and Intel | Homebrew, npm, Cargo or the installer script |
| Linux (glibc) | x86_64 and aarch64 | Ubuntu, Debian, Fedora and the like |
| Linux (musl) | x86_64 and aarch64 | Alpine and slim containers; statically linked, no libc to install |
| Windows | x86_64 and aarch64 | npm or the released binary |
<!-- /gen -->


## Log in

Sign in through the browser device flow, or supply a Personal Access Token with `NOLGIA_TOKEN` or `--token`.

```bash
$ nolgia auth login
$ nolgia auth whoami
```

## Generate

Save an image, a video or an audio file with `--out`; `--json` makes the command output machine-readable.

```bash
$ nolgia gen image --model flux-pro --prompt "a paper-cut mountain range at dawn" --out first.png
$ nolgia gen video --model veo-3.1-lite --prompt "a paper-cut mountain range at dawn, slow push-in as the sun rises" --duration-seconds 4 --out first.mp4
$ nolgia gen audio --model stable-audio-2.5 --prompt "quiet wind through mountain pines" --out first.mp3
```

## Commands

<!-- gen:cli-release -->
From `nolgia --help` in release 0.2.30, published 2026-09-21:
<!-- /gen -->

| Command | What it does |
| --- | --- |
| `auth` | Authenticate this machine |
| `gen` | Generate images, video, or audio |
| `restore` | Restore and upscale existing footage (de-noise, de-haze, up-res) |
| `status` | Show current job status |
| `jobs` | List your generation jobs |
| `wait` | Wait for a job to finish |
| `assets` | List and manage generated assets |
| `characters` | Manage reusable characters for generation |
| `projects` | Group assets into projects |
| `products` | Products imported from a store link, reusable in every ad |
| `compositions` | Assemble clips into a Studio timeline and render one finished video |
| `render` | Assemble ordered clip and narration pairs into one finished video |
| `account` | Inspect account details and usage |
| `billing` | Inspect billing state and portal links |
| `pat` | Manage personal access tokens |
| `org` | Organization workspaces: list, status, switch, create, members, invite, credits [aliases: workspace] |
| `skills` | Bundled AI-agent skills (list, show, install) |
| `ability` | Marketplace abilities for your NOLGIA Agent (list, install, sync, init, pack, publish) |
| `models` | Live model catalog with capabilities and pricing |
| `voices` | Voice catalog for text-to-speech models (list) |
| `motions` | Camera-move library for `gen video --motion` (list) |
| `color-presets` | Built-in color-grade preset looks for Studio compositions (list, cube) |
| `masks` | Timeline masks for Studio compositions (validate, example) |
| `completion` | Generate shell completions (bash, zsh, fish, powershell) |
| `help` | Print this message or the help of the given subcommand(s) |

## Idempotency and scripting

Reuse `--idempotency-key` or `NOLGIA_IDEMPOTENCY_KEY` to collapse generation retries into one job; use a fresh key for an intentional second take. List existing work with `nolgia jobs` and `nolgia assets`, follow a job with `nolgia wait`, and read the model catalog before submitting.

```bash
$ nolgia --json jobs list
$ nolgia --json wait "$JOB_ID"
$ nolgia --json assets list
$ nolgia models list --modality image
```

:::cards
- [Quick Start](./getting-started.html) icon=spot-library: Generate your first image and video.
- [Run MCP](./mcp.html) icon=spot-agent: Connect the tools to your coding agent.
- [Nolgia for Claude Code, Cursor and Codex](./coding-agents.html) icon=spot-terminal: Install the skills and follow the runbook.
:::