Reference

CLI

The fiddle command runs, builds and publishes your app's stories.

bash
npm install -D @basswood/fiddle

Commands

CommandWhat it does
fiddle loginSign in this machine. Shows a code and opens Fiddle to approve it
fiddle logoutSign this machine out
fiddle whoamiWho you're signed in as
fiddle stories devRun your stories at http://localhost:6006/__fiddle/, reloading as you edit
fiddle stories buildBuild them as a static site in fiddle-stories/
fiddle stories publishBuild and upload them to Fiddle as a build of your branch
fiddle --versionThe installed version

Options

OptionUsed byWhat it does
--root <dir>storiesThe app's root, where its Vite config is. Default: here
--port <n>devPort. Default 6006, or the next free one
--out <dir>buildOutput folder. Default fiddle-stories
--branch <name>publishDefault: git's, or CI's
--commit <sha>publishDefault: git's HEAD, or CI's
--app <id>publishWhich app, if your Vite config doesn't say
--upload-url <url>publishA URL from the create_build_upload_url MCP tool. How agents publish
--key <fdl_…>publishA workspace API key, for CI. Or set FIDDLE_API_KEY

Who's publishing

  • You: run npx fiddle login once per machine. Over SSH, open the printed link anywhere.
  • Your agent: it gets an upload URL from MCP and passes --upload-url. The URL is good for that app and branch for an hour.
  • CI: put a key from Settings → API keys in FIDDLE_API_KEY.
.github/workflows/stories.yml
- run: npx fiddle stories publish
  env:
    FIDDLE_API_KEY: ${{ secrets.FIDDLE_API_KEY }}