canvas-cli: When an LLM Can Write Code but Cannot Draw a Box
You ask Claude Code or Cursor to "explain this with a diagram" and the answer comes back as ASCII art that breaks the moment it wraps, or a Mermaid block that does not fit your slide deck. The model can write a for loop, but it cannot natively produce a PNG. That gap is what canvas-cli fills.
TL;DR
canvas-cli is the "Canvas API for AI": a pure-Rust, zero-dependency library and CLI that turns a short DSL into a PNG. Use it when your model can write code but cannot ship an image, or when you want to batch-convert SVGs without spinning up a browser. Cross-platform (macOS / Linux / Windows), MIT, and the same code path works as both CLI and Rust library.
canvas-cli is a pure-Rust, zero-dependency Canvas-style drawing library and CLI. The model writes a tiny DSL — canvas 1080 200; fill_rect 0 0 1080 200; fill_text "..." 20 90 — and the tool renders a real PNG, no headless browser, no Puppeteer, no API key. In other words, a text-only LLM can now output images by writing code it already knows how to write.
By echosoar written in Rust, MIT licensed — free for commercial use.
x env use canvas-cliPlatform & Architecture
Platform
- Supports: macOS (universal binary) / Linux x64 / Windows x64
- Architecture: zero-dependency pure Rust, also runs in WASM and embedded targets
- Distribution: x-cmd (
x env use canvas-cli), GitHub Releases, orcargo install
How canvas-cli Differs From Other "AI Drawing" Tools
| Tool | What it does | Trade-off |
|---|---|---|
| canvas-cli | Model writes DSL → CLI renders PNG locally, no API | Text-only output, you compose the scene yourself |
| ComfyUI / Stable Diffusion | Generative image models (DALL-E / SD) | Needs GPU, API key, expensive, non-deterministic |
| Mermaid / PlantUML | Text → diagram as SVG | Renders to SVG, not PNG; limited chart types |
| Headless Chrome (Puppeteer) | HTML + CSS → screenshot | Heavy, needs Chrome, slow in CI |
| ImageMagick | CLI bitmap manipulation | No AI input, no drawing primitives |
The sweet spot for canvas-cli is "I want a model to produce a deterministic, scriptable image without a GPU or API key."
Core Capability: One DSL Line Produces a PNG
The DSL is intentionally small — just the Canvas 2D primitives most engineers already know:
# Read drawing commands from input.txt and output a PNG
canvas-cli --input=input.txt --output=output.png
# Pass drawing commands inline as a string
canvas-cli --input="canvas 1080 200; fill_rect 0 0 1080 200; fill_text 'Hello' 20 90" \
--output=output.png
# Output a base64 PNG data URL — ideal for Markdown / HTML embedding
canvas-cli --input="canvas 400 200; set_fill_style #2563EB; round_rect 50 40 300 120 24,24,24,24; fill" \
--output-data-urlA minimal DSL script:
canvas 1080 200
create_linear_gradient linear_bg 0 0 1080 0
add_color_stop linear_bg 0 #c3c3c3
add_color_stop linear_bg 1 #2b05b6
set_fill_gradient linear_bg
fill_rect 0 0 1080 200
set_fill_style #ffffff
set_font 32px common
fill_text "Make it so that no graph is difficult to generate." 20 90Feed the same DSL to an LLM, let it fill in fill_text and adjust coordinates based on the prompt, and you have a usable banner in seconds. The whole DSL is plain text, so it round-trips through the model without any custom tokenizer.
Output: What You Get Out
| Output | How to get it | When to use it |
|---|---|---|
| PNG file | --output=output.png | Embed in slides, READMEs, social posts |
| Base64 data URL | --output-data-url | Drop into Markdown / HTML without saving a file |
images::to_data_url(&canvas) (Rust API) | canvas_rs::images | Return an image from a web service in one line |
In-memory Vec{u8} (Rust API) | Canvas::to_png() | Stream the image into a response, a database BLOB, or S3 |
All output is deterministic given the same DSL — useful for cache keys, tests, and CI.
Anti-Aliasing: Smoother Lines and Text by Default
canvas-cli enables anti-aliasing by default (set_text_antialias_grid 4). The same text without anti-aliasing looks pixelated; with it, the output approaches a vector export. The grid level is configurable, and you can disable it entirely for a harder, stylized look.
Embed in Rust Projects: Use as Library or CLI
Behind the CLI sits the canvas_rs Rust crate, which any Rust project can import directly:
use canvas_rs::Canvas;
use canvas_rs::images;
let canvas = Canvas::new(1080, 200);
let mut ctx = canvas.get_context("2d").unwrap();
let png_bytes = std::fs::read("tests/image_220x200.png").expect("could not read PNG file");
let img_data = images::from_png(&png_bytes).expect("could not decode PNG");
ctx.draw_image(&img_data, 860.0, 0.0);
ctx.set_fill_style("black");
ctx.set_font("32px common");
ctx.fill_text("Make it so that no graph is difficult to generate.", 20.0, 90.0);
let url = images::to_data_url(&canvas);The library and the CLI share the same rendering path, so a layout that works in the CLI behaves identically when embedded. Zero external dependencies also means it builds cleanly in WASM and embedded environments — useful if you want to draw in a browser-side worker or on a tiny server.
SVG to PNG: Scriptable Batch Conversion
canvas-cli ships with built-in SVG input, so you can convert vector assets to PNG without a browser:
canvas-cli --input=bicycle.svg --output=bicycle.pngThis is the move for "I have 200 SVG icons in a front-end repo and I need PNG thumbnails for social media / slide decks / README cards" — one shell loop, no Chrome, no Puppeteer.
Typical Use Cases
- AI Coding Assistants Produce Architecture Diagrams
Let Claude Code, Cursor, or any model attach a real PNG when explaining a system. Add a
canvas-cliskill that says "draw in canvas-cli DSL," and the model emits the script you run.bash# Prompt template snippet: # "Use the canvas-cli skill to draw a system architecture diagram for an # e-commerce platform. Main colors: blue (#2563EB), cyan, gray." # Model output: canvas-cli --input=diagram.txt --output=diagram.png - Automated Doc Illustrations
When READMEs, design docs, or blog posts need a diagram, script
canvas-clito generate images from your content — no manual drag-and-drop in Figma.bash# Render 5 chapter banners in one go for ch in 01 02 03 04 05; do canvas-cli --input=banners/$ch.txt --output=site/img/banner-$ch.png done - Batch SVG-to-PNG Conversion
Front-end projects that maintain a library of SVG icons or illustrations can ship PNG exports for slides, social cards, or thumbnails in one line.
bash# Convert every SVG in icons/ to PNGs in png/ for svg in icons/*.svg; do out="png/$(basename "$svg" .svg).png" canvas-cli --input="$svg" --output="$out" done - Email / Report Image Generation
Embed
canvas_rsin a Rust service to generate report charts, invitations, or campaign posters from user data — no external API call, no added latency, no token cost.rustlet banner = render_invitation(user_name, event_date)?; email.attach(&banner, "invite.png")?;
In CI / CD
Render README diagrams on every push so the visual never goes stale with the code. The DSL is plain text, the PNG is deterministic, so a CI run becomes a pure build step.
# .github/workflows/docs.yml
name: Render diagrams
on: [push]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up x-cmd
run: curl -fsSL https://get.x-cmd.com | bash
- name: Render all DSL diagrams
run: |
x env use canvas-cli
mkdir -p docs/img
for f in diagrams/*.dsl; do
canvas-cli --input="$f" --output="docs/img/$(basename "$f" .dsl).png"
done
- name: Commit PNGs
run: |
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git add docs/img/
git commit -m "docs: regenerate diagrams" || true
git pushWhen to Use canvas-cli vs NOT
Use canvas-cli when:
- You want a text-only LLM to produce a real PNG without a GPU or API key.
- You need to batch-convert SVG assets in a headless / CI environment.
- You want a deterministic image output that round-trips through version control (DSL is plain text, PNG is reproducible).
- You are building a Rust service and want a zero-dependency image-rendering library that works in WASM.
Don't use canvas-cli when:
- You need photorealistic or generative images — pick ComfyUI, InvokeAI, or a hosted model instead.
- You need a one-off "draw a chart" GUI and have a designer handy — Figma / Excalidraw will be faster.
- Your output must be a vector format (PDF / SVG only) —
canvas-clioutputs PNG (though it can ingest SVG). - You need full Canvas 2D API coverage —
canvas-cliis a focused subset, not a 1:1 port.
Pro / Con / Verdict
| Dimension | Verdict |
|---|---|
| Pro | Truly zero-dependency; builds in WASM, embedded, and standard Rust targets |
| Pro | Same code path for CLI and library — what you script works the same when embedded |
| Pro | Deterministic output (DSL → PNG) makes it cacheable, testable, and diff-friendly |
| Pro | MIT licensed — OK for commercial and closed-source use |
| Con | New project (first commit 2026-03-29); API and DSL may evolve |
| Con | DSL is a Canvas 2D subset — no path text, no filters, no WebGL |
| Con | No real text shaping; rendering of complex scripts or right-to-left text is best-effort |
| Verdict | Recommended if you want a text-only LLM to ship a PNG, or if you need a zero-dep Rust image library. Hold off if you need generative AI or full Canvas 2D parity. |
Timeline
- 2026-05-23 —
main-8— current build, adds SVG parsing and rendering support - 2026-04-18 —
main-7— CLI cross-platform builds mature (macOS universal / Linux x64 / Windows x64) - 2026-04-15 —
main-5/6—round_rectprimitive added; CLI stabilizes around the public DSL surface - 2026-03-29 — Repository created — initial public commit by
echosoar; the "Canvas API for AI" idea lands as a Rust workspace (canvas+images+clicrates)
Caveat: the project uses content-hash release tags (
main-N-{sha}) rather than semver; pin to a specific tag if reproducibility matters.
Installation
x env use canvas-clix env use resolves the latest stable release for your platform (macOS / Linux / Windows) and puts canvas-cli on PATH. The first run prints the available subcommands and the supported DSL operations.
If you would rather build from source:
git clone https://github.com/echosoar/canvas-cli
cd canvas-cli
cargo install --path cliCommon Pitfalls
- Don't paste the DSL into a single-line
--inputwithout escaping quotes. Use--input=input.txt(file) for any non-trivial script; the shell will eat your quotes otherwise. canvas-clionly outputs PNG. If your downstream needs SVG / PDF, render the PNG and then re-trace, or pick a different tool —canvas-cliwill not give you a vector.- The DSL is a Canvas 2D subset, not the full API. No
filter, noshadowBlur, no path text. Check thecanvas_rscrate docs before assuming a familiar Canvas call exists. - No text shaping layer. Non-Latin scripts and right-to-left text are best-effort; if you ship CJK / Arabic in production, test the output first.
- Pinning releases uses content hashes, not semver.
x env use canvas-clialways points to the latest stable; for CI reproducibility, pin to a specificmain-N-{sha}tag.
Hidden / Lesser-Known Features
--output-data-urlis the single best way to drop a generated PNG into a Markdown table cell or adata:URI in an HTML email — no temp file, no asset host.set_text_antialias_gridaccepts an integer; raising it beyond 4 visibly smooths text at the cost of render time (handy for print-quality output).round_rect(added inmain-5) supports CSS-style radii: 1, 2, 3, or 4 numbers —{radii}syntax is24,24,24,24for uniform,12,4,12,4for asymmetric corners.- The same
canvas_rs::Canvasvalue can be drawn into, then re-used as anImagesource for another canvas — useful for layered compositions without leaving Rust.
Official Resources
- GitHub: https://github.com/echosoar/canvas-cli
- Releases: https://github.com/echosoar/canvas-cli/releases
canvas_rscrate docs: https://docs.rs/canvas_rsCargo.tomlworkspace root: https://github.com/echosoar/canvas-cli/blob/main/Cargo.toml- Author (
echosoar): https://github.com/echosoar
Related Tools
- AionUi — one GUI window that orchestrates Claude Code, Codex, and 20+ other AI CLIs
- aichat — multi-provider AI chat CLI that can take canvas-cli's PNG output and discuss it
- Claude-Code-Game-Studios — Claude Code orchestration pattern that pairs well with canvas-cli for diagram tasks
- ComfyUI — when you need generative image models instead of a deterministic DSL
- InvokeAI — Stable Diffusion UI for local image generation
- playwright-mcp — headless browser MCP server; the heavyweight alternative when canvas-cli's DSL is not enough
Source: