cosmion
Skill2 starsChanged 30 days agoMITView on GitHub
Generate images with any image model on OpenRouter from the command line, save them to files, check prices before spending, and track what was spent. Use when asked to generate, create or edit an image with an AI model, compare image model prices, or run many image prompts within a budget.
- Reads credentials
- Installs packages
In this repository16 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- speckit-analyzeSkill
- speckit-checklistSkill
- speckit-clarifySkill
- speckit-constitutionSkill
- speckit-convergeSkill
- speckit-git-commitSkill
- speckit-git-featureSkill
- speckit-git-initializeSkill
- speckit-git-remoteSkill
- speckit-git-validateSkill
- speckit-implementSkill
- speckit-planSkill
- speckit-specifySkill
- speckit-tasksSkill
- speckit-taskstoissuesSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 17
Never prompt: Cosmion doesn't ask questions when stdin isn't a terminal.
- Very specific: line 19
Check the price first when cost matters: cosmion price spends nothing.
- Distinctive: line 188
Every row is checked before anything is spent.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Cosmion
cosmion is a CLI that generates images with any image model on OpenRouter, using the
user's own OpenRouter key. csn is the short form: csn gen … is cosmion gen ….
It needs Node 22.12 or newer. Install it with npm install -g cosmion.
Rules for agents
- Pass
--jsonto every command. stdout is then exactly one JSON object; logs, progress and warnings go to stderr. Read the exit code (see Exit codes). - Never prompt: Cosmion doesn't ask questions when stdin isn't a terminal. Anything it would need to ask exits 2 with a message saying what to pass instead.
- Check the price first when cost matters:
cosmion pricespends nothing. genandregenare never retried automatically, because a retry can be charged twice. After anupstreamerror that isn't retryable (Cosmion's own 5-minute timeout), tell the user to check their activity on openrouter.ai before trying again: the provider may already have charged.- For
batch, always pass--budgetwith a dollar amount. Use--no-budgetonly when the user asks for it. If a batch stops because a cost is unknown, tell the user and suggest the--no-budget --resumecommand from the message rather than running it yourself. cosmion schemaprints every command, option, JSON output (as JSON Schema) and exit code as one JSON object, generated from the code itself.
Setup
The key comes from OPENROUTER_API_KEY if set, otherwise from the one saved with
cosmion auth. Check with cosmion auth status --json or cosmion doctor --json.
Environment variables:
| Variable | Does |
OPENROUTER_API_KEY | The OpenRouter key; used instead of the saved one while set |
COSMION_MODEL | The model when --model isn't passed (gen, price, batch) |
COSMION_HOME | Keep all of Cosmion's files (settings, history, catalog cache) under this folder instead of the usual per-OS folders |
COSMION_DEBUG | 1 adds the stack trace of an unexpected error (exit 1) to stderr |
NO_COLOR | Turns off colors, animation and tables fitted to the window on a terminal |
Commands
Gen options
Shared by gen, price, models rank and the batch columns. Only the
options passed are sent; the rest use the model's defaults. Each is checked against what
the model supports, and a value it doesn't support exits 2 listing the allowed values
(see cosmion models <id>):
| Option | Sends | Value |
--aspect <ratio> | aspect_ratio | e.g. 16:9 |
--resolution <r> | resolution | e.g. 1K, 2K, 4K |
--quality <q> | quality | e.g. low, medium, high |
--background <b> | background | auto, transparent or opaque |
-n, --count <n> | n | how many images to ask for (an upper bound) |
--seed <int> | seed | for repeatable results; gen picks and records one when the model supports it |
--format <f> | output_format | png, jpeg, webp, svg or gif (GPT Image 2.6's GIFs are animated) |
--compression <0-100> | output_compression | for jpeg and webp |
--ref <path-or-url> | input_references | a PNG, JPEG or WebP file or an https:// URL; repeatable |
cosmion gen <prompt>
Generates images, saves them and records the generation in the history. <prompt> is
the text, or - to read it from stdin.
Options: -m, --model <id> (default COSMION_MODEL), the gen options above,
--out <path>, --force, --json.
- Without
--out, images go in the current folder ascosmion-<id>.<ext>, orcosmion-<id>-<k>.<ext>when there are several. --out <path>is a folder if it exists as one or ends with/; otherwise it is the exact file to write (<stem>-<k><ext>for several images). An--outending in an image extension also asks the model for that format when--formatisn't given. A model that can't make that format still writes to the exact path, so the file can hold another format (say WebP inx.png);images[].formatin the output says which, and a warning goes to stderr. To get the right extension without checking, leave--outoff or give a folder, and Cosmion names the file by its real format.- Existing files are never replaced unless
--forceis passed. - Everything is checked (key, model, options, references, output paths) before anything is sent or spent.
--json prints the history entry:
{
"v": 1,
"id": "k3f9x2ab",
"created_at": "2026-10-17T14:03:11.204Z",
"model": "bytedance-seed/seedream-4.5",
"prompt": "a lighthouse on a tiny moon",
"settings": { "aspect_ratio": "16:9", "resolution": "2K", "seed": 1234 },
"references": [],
"images": [
{ "path": "/home/me/site/cosmion-k3f9x2ab.jpg", "width": 2560, "height": 1440, "format": "jpeg" }
],
"cost_usd": 0.04,
"usage": { "prompt_tokens": 17, "completion_tokens": 16384, "total_tokens": 16401 },
"provider": "Seed",
"generation_id": "gen-img-…",
"batch_id": null,
"row": null,
"regen_of": null
}cost_usd is what OpenRouter charged, or null when it didn't say. Paths are absolute.
Text mode prints the saved paths on stdout, one per line.
cosmion price
Shows what a generation would cost, without spending anything or needing a key.
Options: -m, --model <id>, the gen options above, --json.
{ "model": "…", "settings": { "resolution": "2K" }, "kind": "exact", "cost_usd": 0.04, "notes": [] }kind is one of:
exact: the listed price.at_most: a ceiling (providers at different prices, or a tier that can't be told apart).estimate: from the last generation with the same model and the same settings in the history. Same settings means every option sent except the prompt and seed, including the number of references and the format thatgen --out x.pngimplies; soprice --format pngmatches an earliergen --out x.png, andpricewithout--formatdoesn't.unknown:cost_usdisnull; nothing is guessed. Generate once andpricecan then estimate it.
notes explains anything not counted. With an unknown price it also gives the model's
listed rate when there is one, such as Rate per 1M tokens: $30 out, $8 image in, $5 text in.
That isn't the cost of an image: don't budget from it. Tell the user the rate, and that the
cost is known after the first image.
cosmion models [id]
Lists every image model, or shows one in full.
Options: --refresh (fetch the catalog again; it is otherwise cached for 24 hours),
--json.
- List:
{"models": [{"id", "name", "accepts_references", "max_references", "parameters", "price"}], "fetched_at"}. - One model:
{"id", "name", "description", "parameters", "endpoints": [{"provider_name", "provider_tag", "supported_parameters", "pricing"}], "fetched_at"}.parameterslists the options it supports and their allowed values.
The plain-text output names options by their flag where one exists (--count), otherwise by the field; --json always uses the field names (n).
price is {"kind", "cost_usd", "notes"}, as cosmion price gives it.
cosmion models rank
Lists the models that support every option passed, cheapest first (unknown prices
last).
Options: the gen options above except --ref, --refs <n> (models must accept at least
this many references), --json.
{"settings", "models": [{"id", "name", "price"}]}
cosmion batch <file>
Generates every row of a .csv (with a header row) or .jsonl file, within a budget.
Columns: prompt (required), model (required unless --model or COSMION_MODEL is
set), aspect, resolution, quality, background, count, seed, format,
compression, ref (several separated by | in CSV, an array in JSONL), out. Unknown
columns exit 2.
Options:
--budget <usd>: the most this run may spend. Always pass it.--no-budget: no cap except the key's own spending limit. Only when the user asks.-m, --model <id>: the model for rows without one.--out <folder>: the folder for rows without anout.--concurrency <n>: rows at once, 1 to 8 (default 2).--force: replace files that already exist.--dry-run: check every row and show prices, spending nothing (no budget needed).--resume <batch-id>: continue a batch; rows already saved are skipped and its earlier spending counts against--budget.--json.
Every row is checked before anything is spent; any bad row exits 2 listing each bad row.
A row starts only if its price fits in what's left of the budget. Rows are never
retried. A failed row doesn't stop the others; an auth or credits error stops new
rows from starting.
{
"batch_id": "…", "budget_usd": 0.2, "spent_usd": 0.08,
"stopped": null,
"rows": [{ "row": 1, "status": "ok", "id": "…", "paths": ["…"], "cost_usd": 0.04, "price": { "kind": "exact", "cost_usd": 0.04, "notes": [] }, "error": null }]
}budget_usdisnullwith--no-budget.statusisok,failed,skipped_budget,skipped_resumedornot_run.- A failed row's
erroris{"code", "message"}, plusretry_after_secondswhen OpenRouter said how long to wait. stoppedisnull, or{"code", "message"}when the batch stopped early. Codeunknown_costmeans a row's cost couldn't be known, so the budget couldn't be tracked; the message gives the--no-budget --resumecommand to continue, which is the user's call.- With
--dry-run:{"rows": [{"row", "price"}], "total": <price>}.
Exit 0 when every row succeeded; 3 or 4 when an auth or credits error stopped it (the report is still printed); 8 when any row failed, was skipped or didn't run.
cosmion regen <id>
Runs a past generation again with the same model, prompt, settings (seed included) and references. Only where the images go can change.
Options: --out <path>, --force, --json (as gen). Prints the new history entry,
with regen_of set to <id>.
cosmion history
Lists past generations, newest first.
Options: --limit <n> (default 20), -m, --model <id>, --json.
{"entries": [<entry>, …]}, each entry as gen prints it.
cosmion show <id>
Shows one generation in full, with "exists": true|false added to each image (false
when the file was moved or deleted). An unknown id exits 5.
Options: --json.
cosmion usage
Totals spending over a period, by model or by day (local time).
Options: --since <when> and --until <when> (a date such as 2026-10-01, or days back
such as 7d; default the last 30 days), --by <group> (model or day), --json.
{"since", "until", "by", "total_usd", "generations", "images", "unknown_cost_count", "groups": [{"key", "total_usd", "generations", "images", "unknown_cost_count"}]}
Generations whose cost isn't known are counted in unknown_cost_count, not as $0.
cosmion auth
Checks a key with OpenRouter and saves it (readable by the user only). Agents pass it on
stdin: cosmion auth --stdin --json < key.txt. Without --stdin and without a terminal,
it exits 2.
Options: --stdin, --json. Prints {"saved": true, "label"}; a rejected key exits 3
and saves nothing.
cosmion auth status
Shows which key is in use and what it has left.
Options: --json.
{"source": "env|file|none", "valid", "label", "limit_usd", "limit_remaining_usd", "usage_usd", "balance_usd", "budget"}. A rejected key is "valid": false with exit 0.
budget is null, or {"scope", "limit_usd", "remaining_usd", "resets_at"} when an
organization or workspace budget will block the key before its own limit does
(resets_at is null if it never resets).
The figures are OpenRouter's, read fresh each time, and can lag a generation that just finished.
cosmion auth logout
Removes the saved key (not OPENROUTER_API_KEY).
Options: --json. Prints {"removed": true|false}.
cosmion doctor
Checks Node, the key, OpenRouter, the model catalog, the settings file's permissions, the folders, the history file and whether an installed skill is out of date.
Options: --json.
{"checks": [{"name", "status": "ok|warn|fail", "message", "fix"}]}. fix says what to
do, and is null when the check passed. The key_limit check covers whichever has less
left: the key's own limit, or an organization or workspace budget over it. Exit 0 when nothing fails (warnings are fine),
8 otherwise.
cosmion skill install
Installs this SKILL.md as cosmion/SKILL.md in agents' skills folders. An agent with its
own folder gets the skill there, for it alone; shared is the folder that Codex and most
other agents read. An existing cosmion/SKILL.md that Cosmion didn't write exits 2
unless --force is passed.
Options: --agent <name> (repeatable: claude-code, codex, opencode, antigravity,
cursor, grok-build, copilot, shared), --global (home folder, all projects) or
--project (current folder), --dir <path> (any skills folder, repeatable), --force,
--json. Without a terminal, pass --agent with --global or --project, or --dir.
| Agent | Global | Project |
claude-code | ~/.claude/skills | .claude/skills |
codex, shared | ~/.agents/skills | .agents/skills |
opencode | ~/.config/opencode/skills | .opencode/skills |
antigravity | ~/.gemini/config/skills | .agents/skills |
cursor | ~/.cursor/skills | .cursor/skills |
grok-build | ~/.grok/skills | .grok/skills |
copilot | ~/.copilot/skills | .github/skills |
{"installed": [{"path", "scope": "global|project|dir", "agents": [...]}]}
cosmion skill update
Rewrites Cosmion's installed copies that came from another version: those in every global folder above and in the current folder's project folders. Run it after upgrading Cosmion.
Options: --dir <path> (also update the copy there, repeatable), --json.
{"skills": [{"path", "status": "updated|current"}]}
cosmion skill uninstall
Removes Cosmion's installed copies, never anything else. With no options, every global and
project copy; --agent, --global, --project and --dir narrow it.
Options: --agent <name> (repeatable), --global, --project, --dir <path>
(repeatable), --json.
{"removed": [{"path", "agents": [...]}]}. agents lists every agent using that folder.
cosmion schema
Prints the whole interface as JSON (with or without --json):
{"version", "commands": [{"name", "summary", "args", "options", "output"}], "error", "exit_codes"}.
Options: --json.
Errors
With --json, a failure prints one object on stdout:
{ "error": { "code": "rate_limited", "message": "…", "retryable": true } }retryable: true means trying the same command again later may work. When OpenRouter
says how long to wait, the error also has retry_after_seconds: wait that long first.
credits is never retryable, even when a limit resets at a time the message states: tell
the user, then wait for that time or have the limit raised. The message says which ran out:
the account's credits, the key's own limit, or an organization or workspace budget (for
those, the user may need to ask an admin). Generations running at the same time may count
against a limit before they finish, so if you ran several at once, let them finish and try
again one at a time.
Exit codes
| Code | Meaning | error.code |
| 0 | Success | |
| 1 | Unexpected error, or a local write failed | internal |
| 2 | Invalid usage or input: flags, values, files, paths, input needed without a terminal, or OpenRouter refusing the request (400; 413, too large, so use fewer or smaller --ref images; or a 403 such as flagged content). Change the request rather than retrying | usage |
| 3 | No key, or the key was rejected | auth |
| 4 | Insufficient credits, or a spending limit reached (the key's, or an organization or workspace budget); the message says which and when it resets | credits |
| 5 | Unknown model or history id | not_found |
| 6 | Rate limited, or refused while other requests are running; retryable, and the message says how long to wait when OpenRouter does | rate_limited |
| 7 | OpenRouter, provider or network failure; retryable (the message says how long to wait when OpenRouter does), except Cosmion's own 5-minute timeout | upstream |
| 8 | Finished, but some parts failed or were skipped (batch rows, doctor checks). Not an error: the normal result is printed | |
| 130 | Interrupted (Ctrl-C); nothing on stdout |
Example
cosmion price -m bytedance-seed/seedream-4.5 --resolution 2K --json
cosmion gen "a lighthouse on a tiny moon, watercolor" -m bytedance-seed/seedream-4.5 \
--resolution 2K --out images/lighthouse.png --jsonReport the saved path (images[].path) and the cost (cost_usd) to the user.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

