Pixr Cli

Drives the local pixr Gemini image CLI for generation, editing, variations, model selection, saved defaults, profile-based defaults, reference-image workflow...

Security Scan

The skill is mostly coherent for controlling a local pixr CLI, but the runtime instructions reference a sensitive environment variable (PIXR_API_KEY) and home-directory files without declaring those requirements — that mismatch deserves caution before installing or granting access.

Purpose & Capability

The name/description claim to drive a local 'pixr' CLI and manage ~/.pixr files, which matches the included instructions. However, the documentation (troubleshooting) tells the user to set PIXR_API_KEY to list models — a sensitive credential relationship that is not declared in the skill's metadata (requires.env is empty). This is an incoherence between claimed requirements and referenced runtime needs.

Instruction Scope

SKILL.md explicitly instructs the agent to run local pixr commands, inspect and scaffold files under ~/.pixr (config.json, INSTRUCTION.md, STYLE.md, assets, profiles), and to use CLI flags and --json output for validation. Those actions are within the stated purpose. It also instructs exporting/using PIXR_API_KEY for model listing; reading/writing home-directory config is expected but the env var usage is not declared.

Install Mechanism

The skill is instruction-only with no install spec and no code files, so it does not add binaries or write code to disk. This minimal install surface reduces risk from supply-chain installs.

Credentials

No environment variables are declared, yet troubleshooting explicitly references PIXR_API_KEY (sensitive credential). The skill may access environment variables and home config files at runtime; requesting a single API key for the service is plausible, but it should be declared. The undeclared credential is a proportionality mismatch and a potential surprise for users.

Persistence & Privilege

The skill does not request 'always: true' and the agent metadata allows implicit invocation (allow_implicit_invocation: true). Autonomous invocation is platform-default and not flagged by itself, but note that the skill can be implicitly invoked. The skill does not modify other skills or system settings in the included materials.

What to consider before installing

This skill appears to be a thin instruction layer for running a local 'pixr' CLI and managing ~/.pixr files — that part is coherent. However, the docs instruct the user to set PIXR_API_KEY (a sensitive credential) even though the skill metadata declares no required env vars. Before installing or using: (1) verify the provenance of the 'pixr' CLI you will run (where it came from and its code), (2) confirm whether you must provide a PIXR_API_KEY and understand which service that key accesses, (3) avoid giving broad or high-privilege credentials — create a scoped/test key if possible, (4) be aware the skill will read and write files in your home directory (~/.pixr and legacy paths), so inspect those files for sensitive content, and (5) if you are uncomfortable with implicit invocation, restrict or review agent permissions for invoking this skill. If you need higher assurance, request the actual pixr binary source or an install spec from the publisher before granting access.

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