Getting Started with Cosy: A Template Based Image Generation CLI

What is a template based image generation CLI?

A template based image generation CLI turns structured JSON input into finished images. You design a template once, then feed it data: every render comes out with the same layout, the same fonts, the same brand colors. No browser, no Chromium, no generative model guessing what you meant.

Cosy is one of these tools, built in Rust. It renders carousels, OG images, and social visuals from SVG templates at roughly 50 milliseconds per slide, from a single binary. This guide gets you from zero to your first rendered image in about five minutes.

Install Cosy

The fastest path is the official binary from the v0.2.0 release:

# Linux x86_64, from GitHub Releases
curl -sL https://github.com/codecoradev/cosy/releases/download/v0.2.0/cosy-v0.2.0-x86_64-unknown-linux-gnu.tar.gz | tar xz
sudo mv cosy /usr/local/bin/

# Or build from source (Rust 1.96+)
git clone https://github.com/codecoradev/cosy
cd cosy
cargo build --release

macOS (Apple silicon) and Windows binaries ship in the same release. A multi-arch Docker image is published to GHCR on each release; the packages page lists tags and pull instructions.

Render your first image

Cosy ships with 152 built-in templates. List them, then render one with its default sample data:

cosy templates

cosy render --template stat-card \
  --data templates/stat-card/defaults.json \
  --output cover.png --scale 2

The --scale 2 flag doubles resolution for retina displays. For OG images, keep --scale 1: the og-image template is 1200x630 and social platforms want exactly that size.

That is the entire loop: template in, PNG out, about 50 ms later. For comparison, browser-based rendering APIs budget 2 to 5 seconds per image.

Understand the data shape

Every render takes a JSON object with two parts: brand (colors, watermark, optional logo) and slides (the per-image content). Each template's schema defines its own slide fields, and Cosy validates your input against that schema before rendering, so a missing or wrongly typed field fails fast with a clear message instead of producing a broken image.

{
  "brand": {
    "brand_name": "CodeCora",
    "bg_color": "#1e1e2e",
    "accent_color": "#cba6f7"
  },
  "slides": [
    { "stat_number": "127%", "stat_label": "Revenue Growth" }
  ]
}

The same input works three ways: the CLI above, the HTTP API, or a plain --json string for one-off renders.

Use the HTTP API when you need a server

Scripts and agents usually talk to Cosy over HTTP instead of shelling out. Start the server and call it:

cosy serve --port 3000 --token your-secret

curl http://localhost:3000/api/health   # public, no auth

curl -o cover.png -X POST http://localhost:3000/api/render \
  -H "Authorization: Bearer your-secret" \
  -H "Content-Type: application/json" \
  -d '{"template":"stat-card","scale":2,"data":{"brand":{"brand_name":"CodeCora"},"slides":[{"stat_number":"127%","stat_label":"Revenue Growth"}]}}'

One API call can also render a whole multi-slide carousel in JSON mode. This is the endpoint you would point an AI agent at: the agent supplies structured JSON, Cosy returns the finished PNG bytes.

Reproducibility is the point

One property separates template-based rendering from everything generative. Same template, same JSON input, same binary version: you get a byte-identical image back, every time. There is no seed to chase, no prompt to babysit, no "close enough" reroll.

For a marketing team this means your OG images stay on-brand across hundreds of posts. For automation it means the render step is testable: if the input is valid, the output is known. A generative model can promise neither.

Where to look next

Browse all 152 templates with live previews in the template gallery, read the quick start guide, or skim the source at github.com/codecoradev/cosy.

If you want the bigger argument about when deterministic pipelines beat generative ones, that is the follow-up post: deterministic vs generative image pipelines.

Frequently asked questions

Is Cosy free to use?

The binaries on GitHub Releases are free to download and run. Cosy is source-available under the BSL license, which converts to an open-source license in 2029.

What image formats does the Cosy CLI output?

PNG. The pipeline renders SVG to PNG through resvg. JPEG and WebP support is on the roadmap.

Can I make my own Cosy templates?

Yes. A template is an SVG file with minijinja placeholders plus a JSON schema describing its fields. The template authoring guide in the docs walks through the full anatomy.

Does it need a browser or display server?

No. The whole pipeline is pure Rust in a single binary, which is why it runs in minimal Docker containers and CI jobs with no headless Chrome anywhere in sight.