# Nolgia CLI
[](https://crates.io/crates/nolgia-cli)
[](https://github.com/nolgiacorp/nolgia-cli/actions/workflows/release.yml)
[](https://crates.io/crates/nolgia-cli)
[](#license)
Command-line client for the [Nolgia](https://nolgia.ai) generative media platform — Seedance v2 Pro, Kling v3, Veo 3.1, FLUX Pro, ElevenLabs and more, from your terminal, scripts, and AI agents. Multi-shot video sequences, image-to-video with reusable references, native audio tracks, credit estimates before you spend, and bundled agent skills.
```console
$ nolgia gen image --prompt "A serene mountain lake at dawn" --out lake.png
$ nolgia gen video --prompt "A drone shot over a coastline" --no-wait
9b2f5c1e-... # job id; check with `nolgia wait <id>`
```
> A [Nolgia account](https://nolgia.ai) with an active subscription or prepaid API credits is required.
## Contents
- [Installation](#installation) · [Quick start](#quick-start) · [Examples](#examples) · [Models](#models) · [AI agents & skills](#ai-agents--skills) · [Authentication](#authentication) · [Credits](#credits) · [Command reference](#command-reference) · [Global flags and environment](#global-flags-and-environment) · [Shell completions](#shell-completions) · [Development](#development)
## Installation
### Shell installer (macOS, Linux)
```bash
The installer picks /usr/local/bin when writable and ~/.local/bin otherwise; pass `--prefix <dir>` to choose and `--tag vX.Y.Z` to pin a release. On macOS it clears the quarantine attribute for you
### npm
```bash
npm install -g @nolgia/cli
```
The package downloads the prebuilt binary for your platform (macOS universal, Linux x86_64, Windows x86_64) during postinstall
### Homebrew (macOS, Linux)
```bash
brew tap nolgiacorp/nolgia
brew install nolgia
```
Homebrew prompts once to trust third-party taps: `brew trust nolgiacorp/nolgia`.
### Cargo
```bash
cargo install nolgia-cli
```
Building from source requires the Rust 2024 toolchain; on Linux you also need `libdbus-1-dev` and `pkg-config` for keyring support.
### Prebuilt binaries
Download the binary for your platform from the [latest release](https://github.com/nolgiacorp/nolgia-cli/releases/latest) (macOS universal, Linux x86_64, Windows x86_64), rename it to `nolgia` (`nolgia.exe` on Windows), and place it on your `PATH`.
### Update check
The CLI checks GitHub for a newer release at most once a day and prints a one-line upgrade hint on stderr, matched to how you installed it. It never delays commands, stays quiet for `--json`, piped output, CI, and agent traffic, and can be disabled entirely with `NOLGIA_NO_UPDATE_CHECK=1`
## Quick start
```bash
nolgia auth login # device-code sign-in via your browser
nolgia gen image --prompt "watercolor fox" --out fox.png
nolgia models list # live catalog: models, pricing, capabilities
nolgia billing credits # see what you have left
```
## Examples
### Multi-shot cinematic sequence (Seedance v2 Pro, native audio)
The clip is one generation; the model cuts between your shots. `--prompt` sets overall style, each `--shot` is `"SECONDS:PROMPT"` with an optional `|AUDIO DIRECTION`:
```bash
nolgia gen video --model fal-ai/bytedance/seedance/v2/pro/text-to-video \
--prompt "Gritty 35mm film look, overcast light." --generate-audio true \
--out highway.mp4
```
### Image-to-video with a reusable reference
`--input` takes a local file (uploaded automatically) **or the UUID of any previous asset** — generate a character portrait once, reuse it across every clip:
```bash
nolgia gen image --prompt "portrait, wire-rim glasses, olive field jacket" --out maya.png
nolgia gen video --model fal-ai/kling-video/v3/pro/image-to-video \
--input maya.png --prompt "she turns toward the camera and smiles" --out shot1.mp4
nolgia assets list --modality image --limit 1 # grab the portrait's asset id
nolgia gen video --model fal-ai/kling-video/v3/pro/image-to-video \
--input <asset-uuid> --prompt "she walks out of frame" --out shot2.mp4
```
### Know the cost before you spend
```bash
$ nolgia gen video --model fal-ai/bytedance/seedance/v2/pro/text-to-video \
--duration-seconds 12 --prompt "..." --cost-only
365 credits (fal-ai/bytedance/seedance/v2/pro/text-to-video, 12s)
```
### Hero-quality shot (Veo 3.1)
```bash
nolgia gen video --model veo-3.1 --duration-seconds 8 --aspect-ratio 16:9 \
--prompt "slow cinematic dolly through a warmly lit design studio" --out hero.mp4
```
### Works with your tools
```bash
# newest finished video assets, URLs only
# fire-and-poll from a script
```
## Models
The server is the source of truth — new models appear in the catalog with no CLI update:
```bash
nolgia models list # id, modality, credit pricing, durations, aspect ratios
nolgia models list --modality video
nolgia models get fal-ai/bytedance/seedance/v2/pro/text-to-video
```
Current video lineup: **Kling v3** (standard/master/pro, 3–15s, the workhorse), **Seedance v2 Pro** (4–15s, multi-shot + native audio, cinematic), **Veo 3.1 / 3.1-fast** (4/6/8s, hero quality / fast previz) — each with an image-to-video variant (except Veo). Defaults: `flux-pro` (image), `fal-ai/stable-audio-25/text-to-audio` (audio), `fal-ai/kling-video/v3/text-to-video` (video).
## AI agents & skills
The CLI ships **agent skills** — SKILL.md packs that teach Claude Code, hermes, Cursor, or any agent how to generate on Nolgia well:
```bash
nolgia skills list
nolgia skills install # → ~/.claude/skills/ (Claude Code)
nolgia skills install --target claude-project # → ./.claude/skills/
nolgia skills install --target hermes # → $HERMES_HOME/skills/
```
Bundled: `nolgia-platform` (the full tool surface), `nolgia-video-prompting` (shot grammar, multi-shot directing, consistency), `nolgia-ugc-ads` (vertical ad production recipe).
Also for agents: an **MCP server** at `https://mcp.nolgia.ai` (tools `nolgia_text_to_video`, `nolgia_text_to_image`, …, same params as the CLI flags), **PATs** for headless auth, `nolgia auth token` to extract the current bearer, and `--json` everywhere. The CLI identifies its calling surface (`X-Nolgia-Surface`: `claude-code`, `codex`, `hermes`, `cli`; override with `NOLGIA_SURFACE`) so agent traffic is first-class, not an afterthought.
## Authentication
Two ways to authenticate; every command accepts either.
**Device-code login** (interactive use). Tokens live in your system keyring and refresh automatically:
```bash
nolgia auth login # approve at the printed https://nolgia.ai/device URL
nolgia auth status # -> you@example.com (pro)
nolgia auth logout
```
**Personal Access Tokens** (scripts, CI, agents). PATs start with `nol_` and are passed via `--token` or `NOLGIA_TOKEN`:
```bash
nolgia pat create --name build-server # token is printed once — store it securely
export NOLGIA_TOKEN=nol_...
nolgia account me
```
## Credits
Generation costs credits, drawn from one of two pools depending on how you authenticate:
| Subscription credits | your monthly/yearly plan | device-login sessions (and the web app) |
| API credits | prepaid top-ups (never expire) | PAT-authenticated requests |
If the applicable pool can't cover a generation the API returns `402 Payment Required`. Check balances with `nolgia billing credits`, estimate video jobs with `--cost-only`; buy top-ups and manage your plan from the [billing dashboard](https://nolgia.ai/billing) (`nolgia billing portal` deep-links there).
## Command reference
| `nolgia auth login` / `status` / `logout` / `token` | Device-code sign-in, current identity + tier, sign out, print bearer |
| `nolgia gen image --prompt <p> [--model <m>] [--out <file>]` | Generate an image (waits; prints signed URL or saves) |
| `nolgia gen audio --prompt <p>` | Generate audio (TTS, music, SFX) |
| `nolgia gen video --prompt <p> [--shot "S:P\|A"]... [--input <file\|uuid>] [--duration-seconds N] [--aspect-ratio R] [--generate-audio true] [--seed N] [--negative-prompt <p>] [--cost-only] [--no-wait]` | Generate video: multi-shot, image-to-video, native audio, cost estimate |
| `nolgia models list [--modality m]` / `get <id>` | Live model catalog with pricing and capabilities |
| `nolgia status <job-id>` / `wait <job-id> [--timeout <s>]` | Job status; block until finished |
| `nolgia assets list [--limit N] [--modality m]` / `get <id> [--out <file>]` / `delete <id>` | List, inspect/download, delete assets |
| `nolgia skills list` / `show <name>` / `install [--target t]` | Bundled AI-agent skills |
| `nolgia account me` / `usage` | Identity; job and asset counts |
| `nolgia billing subscription` / `credits` / `portal` | Plan status, credit pools, Stripe portal link |
| `nolgia pat create --name <n>` / `list` / `revoke <id>` | Manage personal access tokens |
| `nolgia completion <shell>` | Shell completions (bash, zsh, fish, powershell) |
## Global flags and environment
| `--api-url` | `NOLGIA_API_URL` | `https://api.nolgia.ai` | API base URL (the client appends `/v1`) |
| `--token` | `NOLGIA_TOKEN` | keyring | Bearer token (PAT or JWT); overrides the stored login |
| `--json` | — | off | Machine-readable output for scripting |
| — | `NOLGIA_SURFACE` | auto-detected | Calling-surface tag sent as `X-Nolgia-Surface` |
## Shell completions
```bash
# zsh (analogous for bash/fish/powershell)
nolgia completion zsh > "${fpath[1]}/_nolgia" && exec zsh
```
## Development
```bash
cargo build --release # binary at target/release/nolgia
cargo test --workspace
```
The API client crate (`crates/client`) is generated at build time from the [Nolgia OpenAPI spec](crates/client/openapi.yaml); don't hand-edit generated shapes. Built with `tokio`, `reqwest`, and `clap`.
## License
[MIT](LICENSE)