Documentation

ClawSoup renders visual layouts from JSON primitives. Install the CLI, authenticate, and start rendering in under 60 seconds.

🚀 Quick Start

Terminal

$ npm install -g clawsoup $ clawsoup login $ clawsoup render '{"type":"Stat","value":"$24,231","label":"Revenue","change":"+12.5%"}' -o stats.png ✅ Rendered → stats.png (800×400, 12ms)

That's it. Three commands and you have a beautiful stat card as a PNG.

🔐 Authentication

Two ways to authenticate:

Option 1: Interactive login

Terminal

$ clawsoup login # Opens browser → sign in → API key saved automatically

Option 2: Environment variable

Terminal

$ export CLAWSOUP_API_KEY=cs_live_your_key_here $ clawsoup render '{"type":"Stat","value":"100"}' -o card.png

Get your API key from the Dashboard.

📸 Render Command

Usage

clawsoup render [json] [options] Options: --type, -t Primitive type (Stat, BarChart, LineChart, Ring, etc.) --props, -p JSON props string --html Render raw HTML instead of primitives --width, -w Output width in pixels (default: 800) --theme Theme: dark | light (default: dark) --format, -f Output format: png | svg (default: png) -o, --output Output file path (default: stdout) --json Output render metadata as JSON

Examples

Render a Stat card:

Terminal

$ clawsoup render '{"type":"Stat","value":"$24,231","label":"Revenue","change":"+12.5%"}' -o revenue.png

Render a BarChart:

Terminal

$ clawsoup render '{"type":"BarChart","title":"Weekly Sales","labels":["Mon","Tue","Wed","Thu","Fri"],"values":[120,200,150,280,220]}' -o chart.png

Render HTML:

Terminal

$ clawsoup render --html '<div style="padding:20px;background:#0f172a;color:white;font-size:24px">Hello World</div>' -o hello.png

Pipe JSON input:

Terminal

$ echo '{"type":"Stat","value":"42","label":"Answer"}' | clawsoup render -o answer.png

Custom width and theme:

Terminal

$ clawsoup render '{"type":"Ring","current":72,"target":100,"label":"Score"}' -w 1200 --theme light -o ring.png

🧩 Primitives

StatBig number with label and trend arrow

BarChartVertical bar chart with labels

LineChartSparkline / time-series chart

RingCircular progress indicator

ProgressHorizontal progress bar

TableData table with headers and rows

ListItems with icons and values

BadgeStatus badge with color

TextTypography (xs to xl)

DividerHorizontal separator

Compose primitives using Column, Row, and Spacer layout nodes. See examples in the Playground.

🤖 MCP Server Setup

Connect ClawSoup to Claude Desktop or any MCP-compatible AI agent:

claude_desktop_config.json

{ "mcpServers": { "clawsoup": { "command": "npx", "args": ["-y", "clawsoup", "mcp"], "env": { "CLAWSOUP_API_KEY": "cs_live_your_key_here" } } } }

Once configured, your AI agent can render visuals directly in conversation — "Show me a chart of weekly sales" → image.

⚡ Use without installing

Don't want to install globally? Use npx:

Terminal

$ npx clawsoup render '{"type":"Stat","value":"$100","label":"Revenue"}' -o card.png

📄 Output Formats

Format	Flag	Plan
PNG	-f png	Free+
SVG	-f svg	Pro+
PDF	-f pdf	Team

🖼️ Resolution Tiers

Plan	Max Width	Quality
Free	400px	1x standard
Pro	800px	2x retina
Team	1600px	4x ultra