nai-cli

📖 한국어 문서 | 📐 Architecture | 🎨 Prompting Guide

NovelAI image generation CLI. Supports text-to-image, img2img, inpainting, upscaling, and tag suggestion.

Installation

npm install -g nai-cli

Or build from source:

git clone https://github.com/demarlik01-ai/nai-cli-ts.git
cd nai-cli-ts
npm install
npm run build

Requires Node.js >= 18.

Configuration

A NovelAI API token is required. Subscribe at NovelAI and obtain your token.

# Set token
nai config set-token <your-token>

# Show config (token is redacted)
nai config show

# Validate config
nai config validate

The token can also be set via the NAI_API_TOKEN environment variable (overrides the config file).

Config File

Location: ~/.config/nai-cli/config.json (respects XDG_CONFIG_HOME)

{
  "version": 1,
  "apiToken": "pst-...",
  "defaultModel": "nai-diffusion-4-5-curated",
  "defaultSampler": "k_euler_ancestral",
  "defaultOutputDir": "./outputs",
  "requestTimeoutMs": 60000,
  "maxRetries": 3,
  "debug": false
}

| Field | Type | Default | Description | |-------|------|---------|-------------| | version | 1 | 1 | Config schema version | | apiToken | string | null | null | NovelAI bearer token | | defaultModel | string | nai-diffusion-4-5-curated | Default model ID | | defaultSampler | string | k_euler_ancestral | Default sampler ID | | defaultOutputDir | string | ./outputs | Default output directory | | defaultOutputTemplate | string | — | Default output filename template | | requestTimeoutMs | number | 60000 | Request timeout in ms | | maxRetries | number | 3 | Max retry count (0–10) | | manifestEnabled | boolean | — | Enable manifest logging for non-batch runs | | debug | boolean | false | Enable debug logging |

Global Options

--debug          Enable debug logging
--config <path>  Path to config.json

Commands

generate — Text-to-Image

Generate image(s) from a text prompt.

nai generate --prompt "1girl, blue hair, school uniform, smile"

nai generate \
  --prompt "1girl, blue hair, school uniform" \
  --negative "bad quality, low res" \
  --model nai-diffusion-4-5-curated \
  --width 832 --height 1216 \
  --steps 28 --scale 5.0 \
  --seed 12345 \
  --out ./my-images/

| Option | Required | Default | Description | |--------|----------|---------|-------------| | --prompt <text> | ✅ | — | Prompt text | | --negative <text> | | — | Negative prompt | | --model <id> | | Config default | Model ID | | --sampler <id> | | Config default | Sampler ID | | --width <number> | | 1024 | Image width (multiple of 64) | | --height <number> | | 1024 | Image height (multiple of 64) | | --steps <number> | | 28 | Sampling steps (1–50) | | --scale <number> | | 5 | CFG scale | | --seed <number> | | Random | Seed (0–4294967295) | | --out <dir> | | Config default | Output directory | | --preset <name> | | — | Load options from a saved preset | | --prompts <file> | | — | Prompt file (one per line) for batch | | --models <ids> | | — | Comma-separated model IDs for matrix batch | | --samplers <ids> | | — | Comma-separated sampler IDs for matrix batch | | --concurrency <n> | | 1 | Number of concurrent requests | | --output-template <tpl> | | Config default | Output filename template | | --dry-run | | — | Validate and preview without API calls |

Either --prompt or --prompts is required.

Batch Generation

Generate multiple images from a prompt file with matrix combinations:

# Generate all combinations of 2 models × 2 samplers × prompts from file
nai generate \
  --prompts prompts.txt \
  --models nai-diffusion-4-5-curated,nai-diffusion-3 \
  --samplers k_euler,k_dpmpp_2m \
  --concurrency 2

# Dry run to preview jobs
nai generate --prompts prompts.txt --models a,b --dry-run

Output Templates

Customize output filenames with template variables:

nai generate --prompt "1girl" --output-template "{date}_{model}_{seed}_{index}.png"

Available variables: {date}, {model}, {seed}, {index}, {prompt}, {sampler}.

preset — Preset Management

Save and reuse generation options.

# Save a preset
nai preset save my-style --model nai-diffusion-4-5-curated --width 832 --height 1216 --steps 28

# List presets
nai preset list

# Show preset contents
nai preset show my-style

# Delete a preset
nai preset delete my-style

# Use a preset (CLI flags override preset values)
nai generate --preset my-style --prompt "1girl, blue hair"

Presets are stored in ~/.config/nai-cli/presets/*.json.

img2img — Image-to-Image

Generate image(s) from an input image and prompt.

nai img2img \
  --image input.png \
  --prompt "1girl, blue hair, school uniform" \
  --strength 0.7 \
  --noise 0.1 \
  --out ./outputs/

| Option | Required | Default | Description | |--------|----------|---------|-------------| | --image <path> | ✅ | — | Input image path | | --prompt <text> | ✅ | — | Prompt text | | --strength <number> | ✅ | — | Transformation strength (0–1) | | --noise <number> | ✅ | — | Noise amount (0–1) | | --negative <text> | | — | Negative prompt | | --model <id> | | Config default | Model ID | | --sampler <id> | | Config default | Sampler ID | | --width <number> | | 1024 | Image width | | --height <number> | | 1024 | Image height | | --steps <number> | | 28 | Sampling steps | | --scale <number> | | 5 | CFG scale | | --seed <number> | | Random | Seed | | --out <dir> | | Config default | Output directory |

inpaint — Inpainting

Regenerate masked region of an image.

nai inpaint \
  --image input.png \
  --mask mask.png \
  --prompt "red eyes" \
  --strength 0.7 \
  --out ./outputs/

| Option | Required | Default | Description | |--------|----------|---------|-------------| | --image <path> | ✅ | — | Input image path | | --mask <path> | ✅ | — | Mask image path | | --prompt <text> | ✅ | — | Prompt text | | --strength <number> | ✅ | — | Inpainting strength (0–1) | | --negative <text> | | — | Negative prompt | | --model <id> | | Config default | Model ID | | --sampler <id> | | Config default | Sampler ID | | --width <number> | | 1024 | Image width | | --height <number> | | 1024 | Image height | | --steps <number> | | 28 | Sampling steps | | --scale <number> | | 5 | CFG scale | | --seed <number> | | Random | Seed | | --out <dir> | | Config default | Output directory |

upscale — Image Upscaling

Upscale an image.

nai upscale --image input.png --scale 4 --out ./outputs/

| Option | Required | Default | Description | |--------|----------|---------|-------------| | --image <path> | ✅ | — | Input image path | | --scale <number> | | 4 | Upscale factor | | --out <dir> | | Config default | Output directory |

suggest-tags — Tag Suggestion

Suggest prompt tags based on input text.

# JSON output (default)
nai suggest-tags --prompt "1girl, blue hair"

# Table output with Japanese tags
nai suggest-tags --prompt "1girl" --format table --lang jp

| Option | Required | Default | Description | |--------|----------|---------|-------------| | --prompt <text> | ✅ | — | Prompt text | | --model <id> | | Config default | Model ID | | --lang <code> | | — | Tag language (en or jp) | | --format <type> | | json | Output format (json or table) |

config — Configuration Management

nai config set-token <token>   # Save API token
nai config show                # Show config (token redacted)
nai config validate            # Validate config file

Supported Models

| Model | ID | |-------|-----| | V4.5 Curated | nai-diffusion-4-5-curated | | V4.5 Full | nai-diffusion-4-5-full | | V4 Full | nai-diffusion-4-full | | V4 Curated | nai-diffusion-4-curated | | V3 | nai-diffusion-3 | | V3 Inpainting | nai-diffusion-3-inpainting | | Furry V3 | nai-diffusion-furry-3 | | V2 | nai-diffusion-2 | | V1 | nai-diffusion | | Safe Diffusion | safe-diffusion |

V4/V4.5 models automatically use the V4 prompt structure (v4_prompt).

Samplers

k_euler, k_euler_ancestral, k_dpmpp_2s_ancestral, k_dpmpp_2m, k_dpmpp_sde, ddim

Output

• Image: <model>-seed-<seed>-img-<n>.png (or custom template)
• Metadata: <model>-seed-<seed>-img-<n>.json

Default output directory is ./outputs/ (configurable).

Manifest Logging

Batch runs automatically create manifest.jsonl in the output directory. Each line records:

{"prompt":"...","model":"...","sampler":"...","seed":123,"filename":"out.png","success":true,"timestamp":"2026-02-18T00:00:00.000Z"}

For non-batch single generations, enable manifest logging via config:

{ "manifestEnabled": true }

License

MIT