@canvora/cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Canvora
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# Canvora – visuals for AI agents
+
+Turn any idea, URL, doc, or PDF into on-brand visuals: **100+ formats** (posts, carousels, decks, ads, documents), generated natively in **150+ languages**. Brand kits keep colors, fonts, logo, and tone consistent per client.
+
+This repo is the agent-facing toolkit for [Canvora](https://canvora.ai/for-agents):
+
+- **Remote MCP server** — for Claude, ChatGPT, Cursor, and any MCP client. Nothing to install.
+- **`canvora` CLI** — for OpenClaw, Hermes, cron jobs, CI, and anything that runs shell commands. Zero dependencies.
+- **OpenClaw skill** — in [`skills/canvora/`](skills/canvora/SKILL.md).
+
+> The Canvora service itself is hosted; this repo contains client tooling and docs only.
+
+## Option 1 — MCP (Claude, ChatGPT, any MCP client)
+
+One remote server, OAuth sign-in, 16 tools your agent discovers on connect:
+
+| | |
+|---|---|
+| **Server URL** | `https://api.canvora.ai/mcp` (streamable HTTP) |
+| **Claude** | Settings → Connectors → Add custom connector → OAuth Client ID `claude_mcp` |
+| **ChatGPT** | Settings → Apps → Developer mode → Create app → OAuth Client ID `chatgpt_mcp` |
+| **Registry** | `ai.canvora/canvora` on the [official MCP Registry](https://registry.modelcontextprotocol.io) |
+
+Step-by-step: [canvora.ai/help/integrations/mcp-setup](https://canvora.ai/help/integrations/mcp-setup)
+
+## Option 2 — CLI (OpenClaw, Hermes, shell-native agents)
+
+```bash
+npm install -g @canvora/cli
+
+# or install the agent skill (Claude Code, Cursor, Codex, OpenCode and 60+ agents):
+npx skills add canvora/canvora-mcp
+
+export CANVORA_API_KEY=vd_...   # create at canvora.ai → Integrations → API Keys
+
+# one atomic command: generates, polls, exits with the output URLs
+canvora generate \
+  --idea "5 tips for remote work" \
+  --format linkedin_carousel --slides linkedin_carousel=5 \
+  --wait --json
+```
+
+### Commands
+
+| Command | What it does |
+|---|---|
+| `canvora generate` | Create visuals from an `--idea` (short concept, Canvora develops it), `--input` (your full content text), `--url`, or `--file-url` (PDF). `--wait` polls to completion and prints output URLs. |
+| `canvora status <id>` | Check a generation and list its output URLs |
+| `canvora download <id> --dir out/` | Save all output files locally |
+| `canvora formats` | All 100+ format IDs with dimensions |
+| `canvora brands` | Your brand kits (pass one via `--brand <uuid>`) |
+| `canvora credits` | Credit balance (10 credits per visual, 15 per carousel/deck slide) |
+
+Every command takes `--json` for machine-readable stdout; progress and errors go to stderr, so piping stays clean. Exit codes: `0` success, `1` failure, `2` usage error.
+
+### Generate flags
+
+```
+--idea "concept"          short concept - Canvora develops it into content
+--input "text"            your full content text, used as the source material
+--url <url>               extract content from a webpage
+--file-url <pdf-url>      extract content from a PDF
+--format <id>[,<id>...]   output formats (see: canvora formats)
+--slides <format>=<n>     slide count for carousel/deck formats (1-10)
+--brand <uuid>            apply a brand kit
+--style <name>            modern | minimal | bold | elegant | playful | corporate | creative | dark
+--resolution 2K|4K        4K on paid plans
+--wait                    poll until done (--timeout 600, --poll 5 seconds)
+--json                    machine-readable output
+```
+
+## Option 3 — Raw REST
+
+```bash
+curl -X POST https://api.canvora.ai/api/generations \
+  -H "X-API-Key: vd_YOUR_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "inputType": "text",
+    "inputContent": "5 tips for remote work",
+    "outputFormats": ["linkedin_carousel"],
+    "carouselCounts": {"linkedin_carousel": 5}
+  }'
+```
+
+Full API guide: [canvora.ai/help/integrations/api-keys](https://canvora.ai/help/integrations/api-keys)
+
+## Built to be called by software
+
+- **Predictable costs** — flat credit pricing (10/visual, 15/slide); `canvora credits` before big jobs; failed generations auto-refund.
+- **Human in the loop** — everything an agent creates lands in the Canvora dashboard for review, editing, and export.
+- **Scoped, revocable keys** — hashed at rest, per-key usage tracking, one-click revoke.
+- **Outputs on a CDN** — stable URLs your agent can post, embed, or hand to a scheduler.
+- **Works on every plan** — API and MCP access included on Free (free credits, no card).
+
+## Links
+
+- [canvora.ai/for-agents](https://canvora.ai/for-agents) — the agent overview
+- [MCP setup guide](https://canvora.ai/help/integrations/mcp-setup) · [API guide](https://canvora.ai/help/integrations/api-keys)
+- [Pricing](https://canvora.ai/pricing)
+
+MIT licensed (CLI and docs in this repo).

package/bin/canvora.js

@@ -0,0 +1,333 @@
+#!/usr/bin/env node
+/**
+ * canvora — CLI for the Canvora API (https://canvora.ai)
+ *
+ * Turn any idea, URL, doc, or PDF into on-brand visuals: 100+ formats,
+ * native in 150+ languages. Built for agents and automation: every command
+ * supports --json (machine-readable stdout; progress goes to stderr).
+ *
+ * Auth:    CANVORA_API_KEY  (vd_... API key from canvora.ai -> Integrations -> API Keys,
+ *                            or an OAuth access token)
+ * Server:  CANVORA_API_URL  (default https://api.canvora.ai)
+ *
+ * Zero runtime dependencies. Node 18+.
+ */
+
+'use strict';
+
+// Agents pipe output constantly (| head, | jq). A closed pipe must be a clean
+// exit, not an EPIPE crash.
+process.stdout.on('error', (e) => { if (e.code === 'EPIPE') process.exit(0); throw e; });
+process.stderr.on('error', (e) => { if (e.code === 'EPIPE') process.exit(0); throw e; });
+
+const fs = require('fs');
+const path = require('path');
+const VERSION = '1.0.0';
+const API_URL = (process.env.CANVORA_API_URL || 'https://api.canvora.ai').replace(/\/+$/, '');
+const API_KEY = process.env.CANVORA_API_KEY || '';
+const REQUEST_TIMEOUT_MS = 60000;
+
+// ---------------------------------------------------------------------------
+// arg parsing (tiny, no deps): flags may be --k v, --k=v, or boolean
+// ---------------------------------------------------------------------------
+function parseArgs(argv) {
+  const args = { _: [], flags: {} };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const eq = a.indexOf('=');
+      if (eq !== -1) {
+        addFlag(args.flags, a.slice(2, eq), a.slice(eq + 1));
+      } else {
+        const key = a.slice(2);
+        const next = argv[i + 1];
+        if (next !== undefined && !next.startsWith('--')) {
+          addFlag(args.flags, key, next);
+          i++;
+        } else {
+          addFlag(args.flags, key, true);
+        }
+      }
+    } else {
+      args._.push(a);
+    }
+  }
+  return args;
+}
+function addFlag(flags, key, value) {
+  if (flags[key] === undefined) flags[key] = value;
+  else if (Array.isArray(flags[key])) flags[key].push(value);
+  else flags[key] = [flags[key], value];
+}
+const asArray = (v) => (v === undefined ? [] : Array.isArray(v) ? v : [v]);
+
+// ---------------------------------------------------------------------------
+// output helpers: stdout = result, stderr = progress/errors
+// ---------------------------------------------------------------------------
+const say = (msg) => process.stderr.write(msg + '\n');
+const emit = (data, json, human) => {
+  if (json) process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+  else human(data);
+};
+function fail(message, code = 1) {
+  say(`error: ${message}`);
+  process.exit(code);
+}
+
+// ---------------------------------------------------------------------------
+// API client
+// ---------------------------------------------------------------------------
+function authHeaders() {
+  if (!API_KEY) return {};
+  // vd_ keys go in X-API-Key; anything else (OAuth token) as Bearer
+  return API_KEY.startsWith('vd_')
+    ? { 'X-API-Key': API_KEY }
+    : { Authorization: `Bearer ${API_KEY}` };
+}
+
+async function api(pathname, { method = 'GET', body } = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  let res;
+  try {
+    res = await fetch(`${API_URL}${pathname}`, {
+      method,
+      signal: controller.signal,
+      headers: {
+        'Content-Type': 'application/json',
+        'User-Agent': `canvora-cli/${VERSION}`,
+        ...authHeaders()
+      },
+      body: body ? JSON.stringify(body) : undefined
+    });
+  } catch (e) {
+    clearTimeout(timer);
+    if (e.name === 'AbortError') throw new Error(`request timed out after ${REQUEST_TIMEOUT_MS / 1000}s: ${method} ${pathname}`);
+    throw new Error(`network error: ${e.message}`);
+  }
+  clearTimeout(timer);
+
+  let data = null;
+  const text = await res.text();
+  try { data = text ? JSON.parse(text) : null; } catch { /* non-JSON body */ }
+
+  if (!res.ok) {
+    const apiMsg = data && (data.message || data.error) ? `${data.error ? data.error + ': ' : ''}${data.message || ''}`.trim() : text.slice(0, 200);
+    if (res.status === 401) throw new Error('unauthorized. Set CANVORA_API_KEY (create one at canvora.ai -> Integrations -> API Keys).');
+    if (res.status === 402) throw new Error(`insufficient credits. ${apiMsg}`);
+    throw new Error(`API ${res.status}: ${apiMsg || 'request failed'}`);
+  }
+  return data;
+}
+
+function requireKey() {
+  if (!API_KEY) fail('CANVORA_API_KEY is not set. Create a key at canvora.ai -> Integrations -> API Keys.', 2);
+}
+
+// ---------------------------------------------------------------------------
+// commands
+// ---------------------------------------------------------------------------
+async function cmdFormats(flags) {
+  const data = await api('/api/formats');
+  emit(data, flags.json, (d) => {
+    for (const f of d.formats) {
+      process.stdout.write(`${f.id.padEnd(34)} ${String(f.dimensions).padEnd(12)} ${f.category}${f.is_carousel ? '  (carousel)' : ''}\n`);
+    }
+    process.stdout.write(`\n${d.count} formats. Carousel formats accept per-format slide counts via --slides.\n`);
+  });
+}
+
+async function cmdCredits(flags) {
+  requireKey();
+  const d = await api('/api/credits/balance');
+  emit(d, flags.json, () => {
+    process.stdout.write(`balance:  ${d.balance}\n`);
+    if (d.packBalance) process.stdout.write(`  pack:    ${d.packBalance}${d.nextPackExpiry ? ` (expires ${d.nextPackExpiry.slice(0, 10)})` : ''}\n`);
+    process.stdout.write(`  monthly: ${d.monthlyBalance ?? 0}\n  bonus:   ${d.topupBalance ?? 0}\n`);
+  });
+}
+
+async function cmdBrands(flags) {
+  requireKey();
+  const d = await api('/api/brands');
+  emit(d, flags.json, () => {
+    for (const b of d.brands || []) {
+      process.stdout.write(`${b.id}  ${b.name || '(unnamed)'}${b.isDefault || b.is_default ? '  [default]' : ''}\n`);
+    }
+    if (!(d.brands || []).length) process.stdout.write('no brand kits yet. Create one at canvora.ai/brands\n');
+  });
+}
+
+function parseSlides(flags) {
+  // --slides linkedin_carousel=7 (repeatable)
+  const counts = {};
+  for (const s of asArray(flags.slides)) {
+    const [fmt, n] = String(s).split('=');
+    const num = parseInt(n, 10);
+    if (!fmt || !Number.isInteger(num) || num < 1 || num > 10) fail(`invalid --slides "${s}" (expected format_id=1..10)`, 2);
+    counts[fmt] = num;
+  }
+  return counts;
+}
+
+async function cmdGenerate(flags) {
+  requireKey();
+  const formats = asArray(flags.format).flatMap((f) => String(f).split(',')).map((s) => s.trim()).filter(Boolean);
+  if (!formats.length) fail('at least one --format is required (see: canvora formats)', 2);
+
+  const body = { outputFormats: formats };
+  if (flags.url) { body.inputType = 'url'; body.inputUrl = String(flags.url); }
+  else if (flags['file-url']) { body.inputType = 'pdf'; body.inputFileUrl = String(flags['file-url']); }
+  else if (flags.idea) { body.inputType = 'idea'; body.inputContent = String(flags.idea); }
+  else if (flags.input) {
+    const text = String(flags.input);
+    // The API's text mode expects source MATERIAL (>=50 chars). Short prompts are
+    // ideas: the idea path expands them into content instead of rejecting them.
+    if (text.trim().length < 50) {
+      fail(`--input expects real content (50+ chars of text to visualize). For a short concept like "${text.slice(0, 40)}", use --idea instead - Canvora will develop it into content.`, 2);
+    }
+    body.inputType = 'text'; body.inputContent = text;
+  }
+  else fail('provide --idea "concept", --input "content text", --url <url>, or --file-url <pdf-url>', 2);
+
+  const carouselCounts = parseSlides(flags);
+  if (Object.keys(carouselCounts).length) body.carouselCounts = carouselCounts;
+  if (flags.brand) body.brandId = String(flags.brand);
+  if (flags.style) body.visualStyle = String(flags.style);
+  if (flags.resolution) body.resolution = String(flags.resolution);
+  if (flags.title) body.title = String(flags.title);
+
+  const created = await api('/api/generations', { method: 'POST', body });
+  const gen = created.generation;
+  say(`generation ${gen.id} started (${gen.creditsCharged} credits)`);
+
+  if (!flags.wait) {
+    emit(created, flags.json, () => {
+      process.stdout.write(`${gen.id}\n`);
+      process.stdout.write(`check progress: canvora status ${gen.id}\n`);
+    });
+    return;
+  }
+
+  // --wait: poll until terminal state
+  const timeoutMs = (parseInt(flags.timeout, 10) || 600) * 1000;
+  const pollMs = (parseInt(flags.poll, 10) || 5) * 1000;
+  const started = Date.now();
+  let last = null;
+
+  while (Date.now() - started < timeoutMs) {
+    await new Promise((r) => setTimeout(r, pollMs));
+    last = await api(`/api/generations/${gen.id}`);
+    const g = last.generation;
+    say(`  ${g.status}${g.progress != null ? ` ${g.progress}%` : ''}`);
+    if (['completed', 'failed', 'partial', 'cancelled'].includes(g.status)) {
+      emit(last, flags.json, () => {
+        for (const o of g.outputs || []) {
+          if (o.fileUrl) process.stdout.write(`${o.fileUrl}\n`);
+        }
+      });
+      if (g.status === 'failed' || g.status === 'cancelled') {
+        fail(`generation ${g.status}${g.errorMessage ? `: ${g.errorMessage}` : ''}`);
+      }
+      return;
+    }
+  }
+  fail(`timed out after ${timeoutMs / 1000}s waiting for generation ${gen.id} (it may still complete: canvora status ${gen.id})`);
+}
+
+async function cmdStatus(flags, id) {
+  requireKey();
+  if (!id) fail('usage: canvora status <generationId>', 2);
+  const d = await api(`/api/generations/${id}`);
+  emit(d, flags.json, () => {
+    const g = d.generation;
+    process.stdout.write(`status: ${g.status}${g.progress != null ? ` (${g.progress}%)` : ''}\n`);
+    for (const o of g.outputs || []) {
+      if (o.fileUrl) process.stdout.write(`${o.fileUrl}\n`);
+    }
+  });
+}
+
+async function cmdDownload(flags, id) {
+  requireKey();
+  if (!id) fail('usage: canvora download <generationId> [--dir <path>]', 2);
+  const d = await api(`/api/generations/${id}`);
+  const g = d.generation;
+  if (g.status !== 'completed' && g.status !== 'partial') {
+    fail(`generation is ${g.status}, nothing to download yet`);
+  }
+  const dir = path.resolve(String(flags.dir || '.'));
+  fs.mkdirSync(dir, { recursive: true });
+  const saved = [];
+  for (const o of g.outputs || []) {
+    const url = o.fileUrl;
+    if (!url) continue;
+    // path.basename after decode: a hostile/compromised URL must never be able
+    // to write outside --dir (e.g. a segment decoding to "../../.zshrc").
+    const rawName = decodeURIComponent(new URL(url).pathname.split('/').pop() || `${o.id}.png`);
+    const name = path.basename(rawName).replace(/[^\w.\-]/g, '_') || `${o.id}.png`;
+    const dest = path.join(dir, name);
+    const res = await fetch(url);
+    if (!res.ok) { say(`skip ${name}: HTTP ${res.status}`); continue; }
+    fs.writeFileSync(dest, Buffer.from(await res.arrayBuffer()));
+    saved.push(dest);
+    say(`saved ${dest}`);
+  }
+  emit({ saved }, flags.json, () => {
+    process.stdout.write(saved.map((s) => s + '\n').join(''));
+  });
+}
+
+// ---------------------------------------------------------------------------
+const HELP = `canvora ${VERSION} - on-brand visuals for agents and automation
+
+usage: canvora <command> [flags]
+
+commands:
+  generate    create visuals        --idea "concept" | --input "content text" |
+                                    --url <url> | --file-url <pdf>
+                                    --format <id>[,<id>...]   (see: canvora formats)
+                                    [--slides <format>=<n>] [--brand <uuid>]
+                                    [--style modern|minimal|bold|elegant|playful|corporate|creative|dark]
+                                    [--resolution 2K|4K] [--title <t>]
+                                    [--wait [--timeout 600] [--poll 5]]
+  status      check a generation    canvora status <generationId>
+  download    save output files     canvora download <generationId> [--dir out/]
+  formats     list all format IDs
+  brands      list your brand kits
+  credits     show credit balance
+  version     print version
+
+flags: --json on any command prints machine-readable JSON to stdout
+       (progress and errors always go to stderr)
+
+auth:  export CANVORA_API_KEY=vd_...   create at canvora.ai -> Integrations -> API Keys
+env:   CANVORA_API_URL to override the API host
+
+examples:
+  canvora generate --idea "5 tips for remote work" --format linkedin_carousel --slides linkedin_carousel=5 --wait --json
+  canvora generate --url https://yourblog.com/post --format instagram_post,blog_header --brand <uuid> --wait
+  canvora download <generationId> --dir ./visuals
+`;
+
+async function main() {
+  const { _: pos, flags } = parseArgs(process.argv.slice(2));
+  const cmd = pos[0];
+  try {
+    switch (cmd) {
+      case 'generate': return await cmdGenerate(flags);
+      case 'status': return await cmdStatus(flags, pos[1]);
+      case 'download': return await cmdDownload(flags, pos[1]);
+      case 'formats': return await cmdFormats(flags);
+      case 'brands': return await cmdBrands(flags);
+      case 'credits': return await cmdCredits(flags);
+      case 'version': return process.stdout.write(VERSION + '\n');
+      case 'help': case undefined: return process.stdout.write(HELP);
+      default: fail(`unknown command "${cmd}" (see: canvora help)`, 2);
+    }
+  } catch (e) {
+    fail(e.message);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@canvora/cli",
+  "version": "1.0.0",
+  "description": "CLI for Canvora (canvora.ai): turn any idea, URL, doc, or PDF into on-brand visuals in 100+ formats, native in 150+ languages. Built for AI agents and automation.",
+  "bin": { "canvora": "bin/canvora.js" },
+  "files": ["bin", "README.md", "LICENSE"],
+  "engines": { "node": ">=18" },
+  "keywords": ["canvora", "ai", "agents", "mcp", "image-generation", "visuals", "design", "openclaw", "social-media", "carousel"],
+  "homepage": "https://canvora.ai/for-agents",
+  "repository": { "type": "git", "url": "git+https://github.com/canvora/canvora-mcp.git" },
+  "bugs": { "url": "https://github.com/canvora/canvora-mcp/issues" },
+  "license": "MIT"
+}