@zuroku/cli
Advanced tools
Command-line publisher for zuroku — upload AI-generated graphic-recording HTML + assets to your zuroku instance.
Command-line publisher for zuroku — uploads an HTML page plus its image assets to a zuroku instance and returns a shareable URL.
Designed for AI agents (Claude Code, etc.) and humans who generate static graphic-recording / explainer pages and want a one-shot deploy step.
npm install -g @zuroku/cli
# or
pnpm add -g @zuroku/cli
Requires Node.js 20+.
The CLI defaults to the AIDD-managed instance at https://app.zuroku.masao.ai. Pass --base-url to point at a self-hosted instance.
# 1. Get an API key from your zuroku app's Web UI → Settings → API keys,
# then register it once (creates ~/.config/zuroku/config.json, mode 0600).
zuroku auth login --token zrk_live_xxx
# self-hosted instance:
# zuroku auth login --token zrk_live_xxx --base-url https://zuroku.example.com
# 2. Collect the HTML and its images into one directory and publish.
# `images/<file>` references are auto-normalized to `img/<file>` for your
# provided assets — no manual sed needed.
mkdir -p /tmp/zuroku-deploy
cp /path/to/index.html /path/to/images/*.png /tmp/zuroku-deploy/
cd /tmp/zuroku-deploy
zuroku publish ./index.html ./*.png --title "..."
# - assets are compressed to WebP client-side (sharp, 85% quality, max 2000px long-edge)
# - `images/foo.png` / `img/foo.png` are auto-rewritten to `img/foo.webp` (anchored to
# your provided assets — external URLs that contain `images/` are left intact)
# - stdout last line is the public URL
Do not run a bare
sed 's|images/|img/|g'. It rewrites the substringimages/everywhere, including external image URLs likehttps://.../images/foo.webp, turning them into broken.../img/...links (404). The CLI normalizes local references safely on its own. If you must hand-edit a different prefix (e.g.assets/), anchor tosrc="assets/so external URLs are untouched.
| Command | Purpose |
|---|---|
zuroku auth login | Save the API token to ~/.config/zuroku/config.json (mode 0600). |
zuroku publish <html> <assets...> | Upload an HTML page and its referenced images. |
zuroku update <slug-or-id> <html> [images...] | Republish an existing project, keeping its slug / URL (full asset replacement). |
zuroku list | List the publishes owned by the current token. |
zuroku delete <slug> | Soft-delete a publish. |
zuroku config (get|set|unset) <key> | Read / write per-user CLI defaults (e.g. default-visibility). |
Run zuroku <command> --help for the full flag list.
zuroku update republishes the same slug / URL (no -2 suffix). The asset set is fully replaced — pass every image you want present after the update.
# slug or id (both work). HTML auto-rewrite & preflight are identical to publish.
zuroku update my-cool-page ./index.html ./img/*.png
Use this when you tweak the HTML or swap images but want the URL stable. To get a brand-new URL instead, zuroku publish again.
<img src> must use the img/ relative prefix (e.g. <img src="img/foo.png">); served route is /p/:slug/img/:filename.<img src> from .png / .jpg to .webp to keep references valid (since v0.1.1).--no-compress to keep the original PNG/JPEG bytes and filenames intact (skip WebP). Useful when source images are already optimised.The CLI parses the HTML and verifies that every <img src="img/..."> resolves to a positional asset argument, fail-fast with tagged error messages:
| Tag | Meaning |
|---|---|
[MISSING] | HTML references an image not in the asset list. |
[UNUSED] | Asset passed in but not referenced from HTML. |
[WRONG-PATH] | <img src> does not start with img/. |
LOCAL_PATH_LEAK | HTML body contains an author-machine path (/Users/…, /home/…, file://, C:\Users\…, /var/folders/…). These 404 for viewers — strip them before publishing. Bypass with ZUROKU_SKIP_PREFLIGHT=1 (debug only). |
Each publish has a visibility:
private — only the owner can view.curator — viewable by Discord members with the configured curator role.public — viewable by anyone with the link (not just curators). Still kept out of the in-app timeline/search, and served with X-Robots-Tag: noindex,nofollow (link sharing / SNS unfurl only, no SEO indexing).Order of precedence: CLI flag (--private > --visibility) → per-user config default-visibility → server default (curator).
# Per-user default
zuroku config set default-visibility private
zuroku config unset default-visibility # back to server default
zuroku config get # show current settings
public can be set per publish (zuroku publish … --visibility public), but cannot be stored as a default-visibility config value — public exposure should always be a deliberate per-publish choice, never a silent default. You can also toggle visibility (including to/from public) later from the web UI.
zuroku publish writes the bare URL as the last line of stdout. Progress, info, and success messages go to stderr.
URL=$(zuroku publish ./index.html ./img/*.png --title "..." 2>/dev/null | tail -1)
A ready-to-use Claude Code skill ships under skills/zuroku-publish/. It lets an AI agent drive zuroku publish end-to-end (HTML rewrite, asset check, fail-fast preflight) without further prompting.
Install it once via skills:
# install all skills from this repo to the agents you choose
npx skills add AI-Driven-R-D-Dept/zuroku-cli
# or pick just this skill
npx skills add AI-Driven-R-D-Dept/zuroku-cli --skill zuroku-publish
# global (~/<agent>/skills/) install for Claude Code only
npx skills add AI-Driven-R-D-Dept/zuroku-cli -s zuroku-publish -a claude-code -g
Manual install also works: copy skills/zuroku-publish/SKILL.md into your project's .claude/skills/zuroku-publish/SKILL.md.
This repo is also a Claude Code plugin marketplace. Installing the plugin bundles the zuroku-publish skill under a zuroku: namespace.
# in Claude Code
/plugin marketplace add AI-Driven-R-D-Dept/zuroku-cli
/plugin install zuroku@zuroku
# → /zuroku:zuroku-publish becomes available
The plugin manifest lives in .claude-plugin/ (plugin.json + marketplace.json).
The plugin ships the skills only — it does not bundle the
zurokuCLI. Install the CLI separately (npm i -g @zuroku/cli) so the skill'szuroku …calls resolve. If it's missing, the skill warns and points you to the install command.
MIT — see LICENSE.
FAQs
Command-line publisher for zuroku — upload AI-generated graphic-recording HTML + assets to your zuroku instance.
We found that @zuroku/cli demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
A mini Shai-Hulud campaign compromised Red Hat Cloud Services npm packages to steal developer and CI/CD secrets during installation.
Research
/Security News
The North Korean malware loader hides in a Packagist-listed package and its GitHub branch to fetch and execute remote code in a likely Contagious Interview-style lure.
Security News
The Rust project is moving toward formal rules on LLM use in contributions after months of internal debate over maintainer burden, code quality, and contributor experience.