---
name: onyx-cli
description: >
  Agent-friendly command-line access to the Onyx AI API for listing models,
  checking credits, inspecting generations, and creating or editing images and
  videos without writing raw curl requests. Also supports structured client and
  brand image workflows: onboarding one or many customers, collecting logos and
  product assets, persisting reusable client memory, applying recurring image
  rules, learning style preferences from feedback, and saving generated assets
  in a repeatable folder structure. Use this skill whenever Codex is working
  inside this repository and needs to operate Onyx from the terminal with
  structured JSON output, repeatable commands, downloaded generation assets,
  recurring brand/client image production, or project-specific image memory.
---

# Onyx CLI

Use the local CLI instead of handwritten API calls whenever the task fits one
of the supported commands. The CLI is built for agent use: every command can
emit structured JSON and the generation commands can save returned media to a
local file.

For recurring image work for brands, customers, projects, products, social
posts, ads, or campaigns, first read `references/brand-image-agent.md`. Load
the focused references only when needed:

- `references/onboarding-paths.md` for first-time users and memory setup.
- `references/conversation-patterns.md` for standard, re-entry, feedback, and
  express-mode dialogue.
- `references/prompt-anatomy.md` for the BRIEF-DNA prompt composer that turns
  short user requests into complete `gpt-image-2` design briefs.
- `references/style-dna-library.md` for ready-made Slot 3 style phrases
  (brutalist editorial, risograph, cinematic photoreal, premium luxury, etc.)
  and per-industry default hybrids.
- `references/translation-map.md` for translating everyday user language into
  precise prompt vocabulary.
- `references/anti-patterns.md` for Slot 9 of every BRIEF-DNA prompt (global
  always plus genre-, position-, and format-specific avoids).
- `references/director-mode.md` when the user wants more manual control via
  `/director`.
- `references/director-vocabulary.md` for the curated cinematic option list
  (Lighting, Camera, Lens, Aperture, Film Stock, Photographer, Movie Look,
  Filter, Shot Type) used in `/director`.
- `references/quality-workflow.md` for draft vs. final quality and customer
  credit handling. Pricing is computed live via
  `scripts/quote-price.mjs`; never paste raw API USD prices.
- `references/error-recovery.md` for API key, credit, model, asset, and safety
  failures.
- `config/defaults.json` for model, memory, format, prompt composer, quality,
  learning, and phase-1 defaults.

## Quick Start

Set authentication first:

```bash
$env:ONYX_API_KEY="onyx_sk_your_key_here"
$env:ONYX_API_URL="https://okta.studio" # optional
```

Run the CLI from the repo root:

```bash
.\onyx.cmd meta info
.\onyx.cmd config test
.\onyx.cmd --json models list --type image
```

Prefer `.\onyx.cmd` on Windows PowerShell so `--json` output stays clean. The
underlying executable lives at `skills/onyx-cli/scripts/onyx-cli.mjs`.

Default image model for new image work: `gpt-image-2`. Use guided mode by
default: the user briefly describes the goal, and the agent builds the full
BRIEF-DNA prompt from client memory, the references, and the libraries. Offer
`/director` once per session as the precise control mode; do not force it and
do not repeat the offer every turn.

Use `--quality medium --resolution 1K` for drafts and
`--quality high --resolution 4K` for approved finals. High 4K is a
finalization step, not the default exploration mode. Do not present
provider/API USD prices as customer prices; query the live customer price
with:

```bash
node skills/onyx-cli/scripts/quote-price.mjs --json --model gpt-image-2 --quality high --resolution 4K --aspect 1:1
```

Show price as a compact status line after generation, never as a confirmation
wall before generation:

```text
✓ ./output/acme/2026-04-30/a134-final.png
  79 Credits · 0,79 € · GPT Image 2 · high · 4K · 1:1
```

## Brand and Client Workflow

Use this workflow when the user wants ongoing image generation for themselves,
one customer, multiple customers, a product catalog, social media posts,
carousels, ads, listings, or recurring brand assets.

1. Load `references/brand-image-agent.md`.
2. Load `config/defaults.json` and resolve the memory root in this order:
   explicit user path, `ONYX_MEMORY_ROOT`, `.onyxrc`, then config default.
3. Check `last-session.md`, `registry.md`, and `clients/*/profile.md` before
   asking onboarding questions.
4. If client memory exists, ask whether to continue with an existing client or
   create a new one. Do not repeat full onboarding unless the profile is missing
   key details.
5. If no memory exists, use `references/onboarding-paths.md`.
6. Load the selected client's profile, summary, project brief, product brief,
   taste file, feedback file, style preset, asset notes, and latest relevant
   outputs before brainstorming or generating.
7. Persist only reusable preferences, asset references, product notes, output
   folders, feedback, and generation decisions. Never store API keys or secrets
   in client memory.
8. Compose each generation with `references/prompt-anatomy.md`: fill the
   relevant BRIEF-DNA slots from user request + selected client/project/product
   memory + relevant asset notes + fixed image rules + Director choices +
   model settings.
9. Use `references/translation-map.md` to turn vague words like "warm",
   "clean", or "edgy" into concrete prompt language. If the user says
   "modern", ask what kind instead of accepting it as a style.
10. Save prompts, slot/source notes, JSON responses, and generated files into
   the selected client output folder so the next agent can continue the same
   work.
11. After every generation, ask for feedback and update memory according to
    `references/conversation-patterns.md`.

## Command Map

### Metadata and configuration

```bash
.\onyx.cmd meta info
.\onyx.cmd config show
.\onyx.cmd config test
```

Use `config test` before authenticated work if the environment may be stale or
the base URL is uncertain.

### Read-only API access

```bash
.\onyx.cmd --json models list --type image
.\onyx.cmd --json credits show
.\onyx.cmd --json generations list --type video --limit 5
```

Prefer `--json` for agent flows so the response is parseable.

### Quote a price (live customer credits)

Returns the customer-facing credits and euros for a generation. Reads
`config/pricing-snapshot.json` and applies the formula from
`src/utils/pricing.ts`.

```bash
node skills/onyx-cli/scripts/quote-price.mjs --draft
node skills/onyx-cli/scripts/quote-price.mjs --final
node skills/onyx-cli/scripts/quote-price.mjs --json --model gpt-image-2 --quality high --resolution 4K --aspect 1:1
node skills/onyx-cli/scripts/quote-price.mjs --table gpt-image-2
node skills/onyx-cli/scripts/quote-price.mjs --list-models
```

### Create images

```bash
.\onyx.cmd --json image create `
  --model gpt-image-2 `
  --prompt "Luxury watch on dark velvet, studio light" `
  --aspect-ratio 16:9 `
  --quality medium `
  --output ./output/watch.png
```

Supported image flags:

- `--model`
- `--prompt` or `--prompt-file`
- `--aspect-ratio`
- `--width` and `--height`
- `--quality`
- `--settings-json`
- `--output`

Use `--output` when the task needs a real file on disk. Without it, the CLI
returns the hosted `image_url`.

### Edit images

Single reference:

```bash
.\onyx.cmd --json image edit `
  --model gpt-image-2 `
  --prompt "Replace the background with a clean white studio backdrop" `
  --image-url https://example.com/input.jpg `
  --aspect-ratio 1:1 `
  --quality medium `
  --output ./output/edited.png
```

Multiple references (up to 10) — comma-separated or repeated `--image-urls`:

```bash
.\onyx.cmd --json image edit `
  --model gpt-image-2 `
  --prompt "Compose social hero: place the product centered, place the brand wordmark top-right at ~8% width, keep the lighting reference's mood" `
  --image-urls https://example.com/product.png,https://example.com/logo.png,https://example.com/lighting-ref.jpg `
  --aspect-ratio 4:5 `
  --quality medium `
  --output ./output/social-hero.png
```

`gpt-image-2` accepts up to 10 input images (`maxInputImages: 10` in
`studio_models.ts`). Use multiple references when you have logo + product +
style anchor — do NOT switch to another model thinking it has "more
references"; gpt-image-2 already handles this.

Supported image edit flags:

- `--model`
- `--prompt` or `--prompt-file`
- `--image-url` (single reference) **or** `--image-urls` (multiple, comma-separated or repeated)
- `--aspect-ratio`
- `--width` and `--height`
- `--quality`
- `--settings-json`
- `--output`

### Apply a saved logo after generation

Use deterministic compositing when a logo must always be in an exact place. Do
not rely only on the image model for strict logo placement or carousel numbers.

```bash
node skills/onyx-cli/scripts/apply-logo.mjs `
  --input ./output/post.png `
  --logo ./.agent/onyx-image-memory/clients/acme/assets/logos/logo.png `
  --output ./output/post-branded.png `
  --position bottom-right
```

```bash
node skills/onyx-cli/scripts/apply-carousel-number.mjs `
  --input ./output/slide-01.png `
  --output ./output/slide-01-numbered.png `
  --index 1 `
  --total 5
```

### Initialize or inspect memory

```bash
node skills/onyx-cli/scripts/init-client.mjs `
  --name "Acme Bikes" `
  --project "Instagram Carousels" `
  --product-id A134 `
  --logo-position top-right `
  --format instagram_post
```

```bash
node skills/onyx-cli/scripts/show-summary.mjs --client acme-bikes
```

### Create videos

```bash
.\onyx.cmd --json video create `
  --model veo-3.1-fast `
  --prompt "Slow cinematic orbit around the product" `
  --image-url https://example.com/start-image.png `
  --duration 6 `
  --aspect-ratio 16:9 `
  --output ./output/product.mp4
```

Supported video flags:

- `--model`
- `--prompt` or `--prompt-file`
- `--duration`
- `--aspect-ratio`
- `--image-url`
- `--settings-json`
- `--output`

## Agent Rules

Use these defaults unless the user asks otherwise:

1. Prefer `.\onyx.cmd --json ...` on Windows or `node skills/onyx-cli/scripts/onyx-cli.mjs --json ...` when you need pristine machine-readable output.
2. Run `config test` before paid or stateful operations if credentials or base
   URL might have changed.
3. `gpt-image-2` is the exclusive default image model. Do NOT substitute another
   model (seedream, nano-banana, ideogram, flux, ...) on your own
   judgement — not for "stronger text", not for "cheaper drafts", not for
   "more references". `gpt-image-2` already supports up to 10 input images
   (see `studio_models.ts` `maxInputImages: 10`) and renders typography
   accurately; it covers the brand-image use cases this skill is built for.
   Switch models only when (a) the user explicitly names a different model,
   (b) the user has been dissatisfied with `gpt-image-2` outputs three
   iterations in a row and you propose an alternative for confirmation, or
   (c) the operation is genuinely outside `gpt-image-2`'s capability set
   (e.g. video). Document the reason in `feedback.md` whenever you switch.
4. Use guided mode first. Offer `/director` once per session or when the user
   asks for more control.
5. Build prompts with the BRIEF-DNA composer before calling the CLI. Pull
   styles from `references/style-dna-library.md`, vague-word translation from
   `references/translation-map.md`, and 6-12 avoids from
   `references/anti-patterns.md`. Never accept `modern` as a final slot value.
6. Use `--quality medium --resolution 1K` for drafts. Use
   `--quality high --resolution 4K` only for finals or explicit user requests.
   Do not put a confirmation wall in front of finals; one compact status line
   after generation is enough. Query exact credits with
   `scripts/quote-price.mjs` rather than estimating.
7. Brainstorm before generation unless express mode is active.
8. Save media with `--output` when the image will be reused, reviewed, branded,
   or added to client memory.
9. Pass absolute output paths when the destination matters across tools or
   agents.
10. `gpt-image-2` renders text and logos accurately when given literal strings.
    Default for brand wordmarks, headlines, taglines, product names, prices,
    and visible copy is to put them verbatim in Slot 6 (Content literals) and
    let the model render them in-prompt. Use `scripts/apply-logo.mjs` only for
    repeatable exact-pixel-position needs (carousel slide consistency,
    watermark uniformity, packshot families). Use
    `scripts/apply-carousel-number.mjs` for slide numbering — the model is
    unreliable for sequential numbers. See `references/brand-image-agent.md`
    "Brand-asset decision tree" before defaulting to post-processing.
11. Pre-flight check before any image generate when a brand or product is in
    scope: Slot 6 (Content literals) MUST contain every visible string the
    image needs. Empty Slot 6 + a brand-named brief = predictably text-less,
    generic output. If literals are missing, STOP and ask one question before
    generating.
12. For phase-1 beginner flows, avoid videos, bulk runs over 5 images, custom
    pixel dimensions, restoration, upscaling, and complex multi-reference work
    unless the user explicitly asks and understands the tradeoff.
13. If the CLI does not expose a needed endpoint yet, fall back to
   `skills/onyx-api/SKILL.md` and call the API directly.

## When To Prefer The CLI Over Raw API Calls

- You need stable terminal commands another agent can repeat.
- You need JSON envelopes around results for automation.
- You want a returned image or video downloaded directly to disk.
- You want a fast connectivity check before a generation request.