Nolgia CLI

The nolgia command-line client for the Nolgia generative-media platform. Generate images, video, and audio; inspect the live model catalog; manage assets, projects, and characters; and install the bundled agent instructions or marketplace Abilities.

Source versus releases. main is the development source and can contain unreleased commands and flags. The shell installer, Homebrew, prebuilt binaries, npm, and crates.io each install a tagged release. The npm postinstall downloads the binary matching its package version, and a package version without a matching GitHub release cannot install. Check nolgia --version and nolgia --help for the binary you actually installed. To exercise this checkout, use cargo run -p nolgia-cli --bin nolgia -- --help.

Contents

• Installation
• Quick start
• Generation
• Models and cost estimates
• Bundled skills and marketplace Abilities
• Authentication
• Credits
• Output and scripting
• Command index
• Global flags and environment
• Shell completions
• Development and spec sync

Installation

Shell installer (macOS and Linux)

curl -fsSL https://raw.githubusercontent.com/nolgiainc/nolgia-cli/main/install.sh | bash

The installer uses the latest GitHub release and installs without sudo to ~/.local/bin (falling back to ~/bin). It adds the selected directory to your shell profile when needed. Use --prefix <DIR> for another user-writable directory, --tag vX.Y.Z to pin a release, or --system when you intentionally want /usr/local/bin and will provide any required privilege yourself. Re-running the same version is idempotent.

This command executes a script fetched from the repository's main branch and then downloads a release binary. If your environment requires review or provenance checks, save and inspect install.sh first and pin the binary with --tag; on macOS the script removes the downloaded binary's quarantine attribute so it can run.

npm

npm install -g @nolgia/cli

The package requires Node 18 or newer and downloads a matching prebuilt binary during postinstall: macOS universal, Linux x86_64, or Windows x86_64. See the npm README for package-specific caveats.

Homebrew

brew tap nolgiainc/nolgia
brew install nolgia

Cargo or a prebuilt binary

cargo install nolgia-cli

The public binary is named nolgia. Building this Rust 2024 workspace from source on Linux requires pkg-config and libdbus-1-dev for the keyring dependency. Alternatively, download the platform binary from the GitHub releases and put nolgia (or nolgia.exe) on PATH.

Quick start

nolgia auth login                         # browser device-code flow
nolgia models list                        # live models, capabilities, and pricing
nolgia gen image --prompt "watercolor fox" --out fox.png
nolgia gen video --prompt "a slow dolly through a studio" --out clip.mp4
nolgia billing credits                    # subscription and API top-up balances

Generation is account-backed and consumes the applicable credit pool. Use nolgia models get <MODEL_ID> before selecting model-specific options.

Generation

All generation requests require --prompt. The server catalog is authoritative for model IDs, supported durations, aspect ratios, quality tiers, and pricing; do not assume that an option accepted by one model is accepted by another. Every gen subcommand (and assets upload) accepts --project-id <PROJECT_UUID> to file the resulting asset(s) into one of your projects at creation (nolgia projects list for ids); without it, assets land in your default Library project.

Images

nolgia gen image --prompt "a paper-cut mountain range" --out mountains.png
nolgia gen image --model <IMAGE_MODEL_ID> --quality <TIER> --prompt "..."

--out downloads the completed asset. --quality is optional and model-specific. Image references belong in a video request; the image command has no working reference-input path in this source tree.

Video

# A local image is uploaded, or an existing image asset can be addressed by UUID.
nolgia gen video --model <VIDEO_MODEL_ID> --input portrait.png \
  --prompt "the subject turns toward the camera" --out shot.mp4

# Multi-shot segments use SECONDS:PROMPT, optionally followed by |AUDIO DIRECTION.
nolgia gen video --prompt "gritty 35mm film look" \
  --shot "4:wide shot of a rural road|engine and wind" \
  --shot "3:the driver checks the radio|static cuts out" \
  --generate-audio true --out sequence.mp4

--input is a local image path or an existing image asset UUID; the selected model must support image input. --video-ref <ASSET_UUID> (repeat up to three) and --element <ASSET_UUID> (repeat up to nine) are for models that advertise reference-to-video support. Reference videos must be MP4/MOV, 480p–720p, 2–15 seconds, and 50 MB combined; reference prompts address them as @Video1…@Video3 and elements as @Image1…@Image9. --end-frame <ASSET_UUID|FILE> pins a final image and requires --input. --quality and --bitrate are validated against the model's published capabilities. --negative-prompt, --aspect-ratio, --duration-seconds, and --seed are also model-dependent.

Use --cost-only to query the live catalog and print an estimate without creating a job. It is an estimate, not a reservation or a hard-coded price.

Audio

nolgia gen audio --model <AUDIO_MODEL_ID> --prompt "rain on a window" --out rain.mp3
nolgia gen audio --model <TTS_MODEL_ID> --voice <VOICE_ID> --prompt "Welcome" --format mp3

Discover voices with nolgia models get <AUDIO_MODEL_ID>; --format selects the CLI's supported output format. The server validates model-specific audio options.

Models and cost estimates

nolgia models list
nolgia models list --modality video
nolgia models get <MODEL_ID>
nolgia gen video --model <MODEL_ID> --prompt "..." --cost-only

The catalog includes modality, credit pricing, duration and aspect-ratio support, image-input support, quality tiers, reference limits, and (for audio) voices. New models and capability changes can appear without a CLI release.

Bundled skills and marketplace Abilities

These are separate surfaces:

• Bundled skills are embedded SKILL.md packs that teach an agent how to use Nolgia. They install locally and do not call the API:

  nolgia skills list
  nolgia skills show nolgia-platform
  nolgia skills install --target claude-user
  nolgia skills install --target claude-project
  nolgia skills install --target hermes
  nolgia skills install --target dir --dir ./agent-skills
  

  The three bundled packs are nolgia-platform, nolgia-video-prompting, and nolgia-ugc-ads. --force is required to overwrite an existing file. The Hermes target writes to $HERMES_HOME/skills and defaults HERMES_HOME to /opt/data when it is unset.

• Marketplace Abilities are registry-backed packages installed for a Hermes agent through the API. The package manifest is ability.json; its agent instructions remain SKILL.md for Hermes compatibility:

  nolgia ability list
  nolgia ability show <ABILITY_SLUG>
  nolgia ability installed
  nolgia ability install <ABILITY_SLUG>
  nolgia ability uninstall <ABILITY_SLUG>
  nolgia ability sync --dir "${HERMES_HOME:-/opt/data}/skills"
  

  Administrators can author and publish an Ability with nolgia ability init <SLUG>, nolgia ability pack <DIR>, and nolgia ability publish <DIR>. publish is an admin-only API operation; init and pack work locally. ability pack passes the optional python_requirements manifest field through to the marketplace. Synced marketplace directories carry a .nolgia-ability.json version marker. Review an Ability's ability.json, SKILL.md, and payload before installing it: Hermes may execute the instructions and code it contains. Marketplace commands use the ability name; the separate bundled command remains skills.

Authentication

Networked commands resolve a bearer token from --token, then NOLGIA_TOKEN, then the stored device-login token. Local commands such as skills, completion, and Ability init/pack do not need a token.

Device login

nolgia auth login
nolgia auth status       # `whoami` is an alias
nolgia auth token        # print the resolved access token for a script
nolgia auth logout

The default store is ${XDG_CONFIG_HOME:-$HOME/.config}/nolgia/tokens.json. On Unix, the CLI creates a 0600 file in a 0700 directory; Windows uses the platform's normal file ACLs. This avoids repeated macOS keychain prompts after upgrades. Set NOLGIA_TOKEN_STORE=file to use only that file and never probe the keyring; set NOLGIA_TOKEN_STORE=keyring to opt into the OS keyring. With the variable unset, a one-time migration read may import an older keyring token into the file store.

Personal access tokens

nolgia pat create --name build-server   # shown once; store it securely
export NOLGIA_TOKEN=nol_...
nolgia account me
nolgia pat list
nolgia pat revoke <PAT_UUID>

Use PATs for CI, scripts, and agents. Prefer NOLGIA_TOKEN or a secret manager over --token: command-line arguments can appear in shell history and process listings. Do not put a token in a README or command log.

Credits

nolgia billing credits reports subscription and API top-up balances separately, plus the overall total (use --json for additional fields). Device-login sessions and PAT-authenticated requests use the credential-appropriate pool; the API rejects a generation when that pool cannot cover it. billing subscription shows plan status, and billing portal prints a Stripe customer-portal link. account usage reports the number of job and asset items on its default visible pages, not credit spend or an all-account total.

Output and scripting

--json is a global flag for machine-readable output on commands that implement a JSON response. It is not a promise that every invocation emits JSON. In particular:

• gen ... --no-wait prints {"job_id":"..."} so it can be passed to wait.
• gen video --cost-only prints a human-readable estimate and creates no job.
• auth login and auth status/whoami print human prompts/status text even when --json is also supplied; auth token prints the resolved access token, skills show prints the SKILL.md, and completion <SHELL> prints shell code.

For a fire-and-poll script:

job_uuid=$(nolgia gen video --prompt "..." --no-wait | jq -r .job_id)
nolgia wait "$job_uuid" --timeout 600 --json | jq .asset.signed_url

Human output otherwise depends on the command: completed image/audio generations print a signed URL, completed video prints the job UUID and status, and --out <FILE> downloads the asset. Signed URLs are temporary bearer capabilities; avoid sending them to persistent CI logs or telemetry, and save the file or query the asset again when needed.

Command index

Use nolgia <COMMAND> --help (and, where applicable, nolgia <COMMAND> <SUBCOMMAND> --help) for the complete flags and current server-facing details.

Replace every <PLACEHOLDER> below with a real value; angle-bracket placeholders are documentation notation, not literal shell arguments. Flag highlights include gen image/video/audio --project-id and assets upload --project-id (file the result into a project), assets list --limit/--cursor/--modality/--tag/--project-id, assets get --out, assets tag --tag (repeatable) or --clear, assets frame --at/--last/--out, projects create/update --auto-tag and update --clear-auto-tags, projects add-assets --asset-id (repeatable), and up to four characters ... --reference-asset-id values. ability sync/init accept --dir, while ability pack accepts --out, as shown by their help. Video waits by default; use --no-wait for the JSON job object and --timeout to bound waiting.

Command	Subcommands and purpose
auth	login, logout, status/whoami, token
gen	image, video, audio generation
status, wait	Inspect or wait for a job by UUID
assets	list, get, delete, upload, tag, frame
characters	list, get, create, update, delete reusable characters
projects	list, get, create, update, delete, add-assets, remove-asset
account	me, usage (identity and default-page job/asset item counts)
billing	subscription, credits, portal
pat	create, list, revoke personal access tokens
skills	list, show, install embedded agent packs
ability	list, show, installed, install, uninstall, sync, init, pack, publish marketplace Abilities
models	list, get live catalog
color-presets	list the built-in color-grade preset looks for Studio compositions; cube <slug> [-o FILE] downloads the .cube LUT
completion	bash, zsh, fish, elvish, or powershell completion script

Global flags and environment

Flag or variable	Default	Purpose
--api-url / NOLGIA_API_URL	https://api.nolgia.ai	API base URL; the client appends /v1 unless already present
--token / NOLGIA_TOKEN	stored login	Bearer token; an explicit flag wins
--json	off	Request structured output where the command supports it
NOLGIA_TOKEN_STORE	file with one-time migration	file disables keyring access; keyring opts into the OS keyring
NOLGIA_SURFACE	auto-detected	Override the X-Nolgia-Surface value sent with API requests; any non-empty value also suppresses update hints
NOLGIA_NO_UPDATE_CHECK	unset	Disable the once-per-day release hint
XDG_CONFIG_HOME	$HOME/.config	Parent for token and install-metadata files
XDG_STATE_HOME	$HOME/.local/state	Parent for the update-check cache
HERMES_HOME	/opt/data for Hermes targets	Parent of the Hermes skills directory

The update hint reads a local cache and refreshes it in the background at most once per day. It is suppressed for JSON output, CI, non-interactive stderr, and any non-empty NOLGIA_SURFACE; a short best-effort grace may run at process exit. Set NOLGIA_NO_UPDATE_CHECK=1 when a completely quiet invocation is required.

Shell completions

nolgia completion zsh > "${fpath[1]}/_nolgia"
mkdir -p "${XDG_DATA_HOME:-$HOME/.local/share}/bash-completion/completions"
nolgia completion bash > "${XDG_DATA_HOME:-$HOME/.local/share}/bash-completion/completions/nolgia"

Use the equivalent fish, elvish, or powershell subcommand for those shells.

Development and spec sync

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
cargo test --workspace --locked
bash tests/install_sh_test.sh
cargo build --release --locked

The Rust client is generated at build time from the vendored OpenAPI snapshot. CI compares it with the canonical API contract. Do not hand-edit generated client output. For local development, the sibling nolgia-api spec is used only when you explicitly set NOLGIA_USE_SIBLING_SPEC=1; otherwise builds use the vendored snapshot. The release workflow publishes tagged crates and release binaries, then attempts npm publishing only when npm/package.json matches the tag; a mismatch fails that npm job. A commit on main is not itself a release.

License

MIT