Skill: dishant0406/pixr (version 1.0.2)

--- name: pixr-cli description: Drives the local pixr Gemini image CLI for generation, editing, variations, model selection, saved defaults, profile-based defaults, reference-image workflows, and output sizing or format conversion. Use when the user wants to generate or edit images with pixr, inspect config, refs, or profiles, set the default model or save directory, manage ~/.pixr files, or get command-specific help for this CLI. metadata: author: pixr version: 0.1.0 --- # Pixr CLI ## When To Use Use this skill when the task is specifically about the local `pixr` CLI in this repository or its home-directory defaults under `~/.pixr`. Typical triggers: - "generate an image with pixr" - "edit an image with pixr" - "create variations with pixr" - "set the pixr model" - "save images to a default folder" - "use the refs from ~/.pixr/assets" - "init a pixr profile" - "make a profile use a different model or save dir" - "show the pixr profile layout" - "show what pixr supports" - "fix or inspect pixr config" Do not use this skill for general Gemini API design discussions that are not tied to this CLI. ## Execution Mode Prefer the installed binary when available: - `pixr` If you are working inside this repo and do not want to depend on a global link, use: - `npm run dev -- <command>` - `npm run pixr -- <command>` ## Core Workflow 1. Start by checking the exact command surface instead of assuming flags. Use `pixr help` for global help or `pixr <command> --help` for command help. 2. If the task is generation, inspect saved defaults first when they matter. Run `pixr config --json`. 3. If the task depends on profile-specific defaults, inspect or scaffold them first: - `pixr profile list` - `pixr profile show <name>` - `pixr profile init <name>` - `pixr config --profile <name> --json` 4. If the task depends on a saved model or output directory, prefer the dedicated commands over editing config by hand: - `pixr model ...` - `pixr save-dir ...` 5. If the task depends on reusable prompts or style, use the home-directory files: - `~/.pixr/INSTRUCTION.md` - `~/.pixr/STYLE.md` - `~/.pixr/prompts/<command>.md` - `~/.nano-image/STYLE.md` 6. If the task uses default reference images, inspect `~/.pixr/assets` or `~/.pixr/profiles/<name>/assets` and verify with `pixr refs --json`. Remember that pixr keeps only the latest three default asset images by modified time. 7. After changing behavior, validate with one concrete CLI command and capture the resulting output path or config state. ## Image Workflows For generation details and command recipes, read `references/command-reference.md`. Key rules: - Use `generate` or `gen` for prompt-only creation. - Use `edit` for text-guided changes to an existing image. - Use `vary` for one or more Gemini-generated variations of an existing image. - Respect saved defaults from `~/.pixr/config.json`. - If the user passes `--save-to` or `--output`, that overrides the saved default output directory. - Width-only or height-only requests preserve aspect ratio during local resize. - Width plus height forces the final image to the exact requested dimensions. - Format defaults to `png`; `jpg`, `jpeg`, and `webp` are supported through local conversion. ## Configure Defaults For persistent settings and file layout, read `references/defaults-and-files.md`. Prefer command-driven config changes: - Save model: `pixr model <name>` - Pick model interactively: `pixr models` - Save default output dir: `pixr save-dir --set "<path>"` - Clear saved output dir: `pixr save-dir --clear-save-dir` - Save profile defaults: `pixr profile init <name> --model ... --save-dir ...` - Use interactive profile setup: `pixr profile init <name>` Avoid editing `~/.pixr/config.json` directly unless the user explicitly asks for a manual file edit. ## Troubleshooting Read `references/troubleshooting.md` when: - generation fails - models do not list - the picker or config looks wrong - output paths or refs are not being used ## Validation After making changes or guiding usage: - run one obvious command that should succeed - use `--json` when you need machine-readable confirmation - report the exact saved model, output directory, or generated file path when relevant

path: agents/openai.yaml
content: interface:
  display_name: "Pixr CLI"
  short_description: "Operate the local pixr image CLI and its defaults"
  default_prompt: "Use $pixr-cli to generate or configure images with the local pixr CLI."

policy:
  allow_implicit_invocation: true


path: references/command-reference.md
content: # Command Reference

## Identity

- npm package name: `pixr-cli`
- installed binary: `pixr`

## Help

- `pixr help`
- `pixr help edit`
- `pixr help vary`
- `pixr help generate`
- `pixr help profile`
- `pixr edit --help`
- `pixr vary --help`
- `pixr generate --help`
- `pixr profile --help`
- `pixr models --help`
- `pixr save-dir --help`

## Generate

Use for one-shot image creation:

```bash
pixr gen "a minimal editorial thumbnail"
pixr generate "a minimal editorial thumbnail"
pixr generate --save-to ./renders "a product poster"
pixr generate -w 1600 -h 840 -f webp "a dark blog hero"
pixr generate --ref ./extra.png --no-default-refs "a controlled studio shot"
```

## Edit

Use for text-guided image edits:

```bash
pixr edit ./hero.png "turn this into a premium ad with softer lighting"
pixr edit --input ./hero.png --count 2 "replace the label and keep the bottle shape"
pixr edit ./hero.png --ref ./logo.png "integrate this logo into the design"
```

## Vary

Use for Gemini-based variations of an existing image:

```bash
pixr vary ./hero.png
pixr vary ./hero.png --count 3
pixr vary ./hero.png "keep the same subject, explore bolder compositions"
```

## Models

```bash
pixr models
pixr models --no-interactive
pixr models --json
pixr model
pixr model gemini-3.1-flash-image-preview
pixr model --clear-model
```

Notes:

- In a TTY, `pixr models` opens an arrow-key picker.
- The chosen model is saved to config on Enter.

## Profiles

```bash
pixr config --init
pixr profile list
pixr profile show social
pixr profile init social
pixr profile init social --model gemini-3.1-flash-image-preview --save-dir "~/Pictures/pixr/social"
```

Notes:

- `config --init` scaffolds `~/.pixr/` without overwriting existing files.
- `profile init <name>` creates `INSTRUCTION.md`, `STYLE.md`, and `assets/` for that profile.
- In a TTY, `profile init <name>` asks for model, format, save dir, dimensions, prefix, and default-profile choice unless you pass flags or `--no-interactive`.
- Profiles can save their own `model` and `outputDir`, so `pixr config --profile <name> --json` can resolve differently from the global defaults.
- `profile show <name>` reports whether the profile comes from config, files, or both.

## Output Directory

```bash
pixr save-dir
pixr save-dir --set "~/Pictures/pixr"
pixr save-dir /absolute/or/relative/path
pixr save-dir --clear-save-dir
```

Resolution order:

1. explicit `--save-to` or `--output`
2. saved `outputDir` in `~/.pixr/config.json`
3. current working directory

## Inspect

```bash
pixr config --json
pixr refs --json
```

Notes:

- If more than three default asset images exist, `pixr` uses the latest three by modified time and emits a warning.


path: references/defaults-and-files.md
content: # Defaults And Files

## Home Directory Layout

```text
~/.pixr/
├── config.json
├── INSTRUCTION.md
├── STYLE.md
├── prompts/
│   ├── generate.md
│   ├── edit.md
│   └── vary.md
├── assets/
│   ├── common/
│   ├── generate/
│   ├── edit/
│   └── vary/
└── profiles/
    └── social/
        ├── INSTRUCTION.md
        ├── STYLE.md
        └── assets/
```

Legacy paths still read when present:

```text
~/.nano-img/
~/.nano-image/STYLE.md
```

## File Roles

- `INSTRUCTION.md`: persistent non-style guidance
- `STYLE.md`: persistent style guidance
- `prompts/<command>.md`: prompt prefix applied per command
- `assets/`: default reference images used unless `--no-default-refs` is passed
- `profiles/<name>/...`: profile-specific overrides for instructions, style, and assets
- `config.json`: saved defaults for model, output directory, and profile-level overrides

Example:

```json
{
  "model": "gemini-3.1-flash-image-preview",
  "outputDir": "/absolute/path/to/renders",
  "profiles": {
    "social": {
      "model": "gemini-3.1-flash-image-preview",
      "outputDir": "/absolute/path/to/social-renders",
      "format": "webp",
      "width": 1600,
      "height": 900
    }
  }
}
```

## Preferred Commands

- model: `pixr model <name>`
- output dir: `pixr save-dir --set "<path>"`
- scaffold home dir: `pixr config --init`
- scaffold profile: `pixr profile init <name>`
- non-interactive profile config: `pixr profile init <name> --model ... --save-dir ...`

## Inspect

```bash
pixr config --json
pixr refs --json
find ~/.pixr -maxdepth 2 -type f | sort
```

## Notes

- `save-dir --set "~/Pictures/pixr"` expands `~` to the current user's home directory
- `--save-to` and `--output` are aliases
- if more than three default asset images exist, `pixr` keeps the latest three by modified time


path: references/troubleshooting.md
content: # Troubleshooting

## Models Do Not List

1. Verify `PIXR_API_KEY` is set.
2. Run `pixr models --no-interactive`.

If the API key is missing, set it first:

```bash
export PIXR_API_KEY=your_gemini_key
```

## Config Looks Wrong

Inspect runtime state:

```bash
pixr config --json
```

Check:

1. CLI flags
2. environment variables
3. saved config
4. discovered files

## Saved Defaults Not Applying

1. inspect `~/.pixr/config.json`
2. run `pixr model`
3. run `pixr save-dir`

## End-To-End Smoke Test

```bash
pixr model gemini-2.5-flash-image
pixr save-dir --set "~/Pictures/pixr"
pixr generate --save-to ./tmp "test prompt"
```

## Dimension Or Format Output Looks Wrong

Use:

```bash
pixr generate -w 1600 -h 840 -f webp "test prompt"
```

Remember:

- width only preserves aspect ratio
- height only preserves aspect ratio
- width plus height forces an exact final size


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)