Reference
CLI
The fiddle command runs, builds and publishes your app's stories.
bash
npm install -D @basswood/fiddleCommands
| Command | What it does |
|---|---|
fiddle login | Sign in this machine. Shows a code and opens Fiddle to approve it |
fiddle logout | Sign this machine out |
fiddle whoami | Who you're signed in as |
fiddle stories dev | Run your stories at http://localhost:6006/__fiddle/, reloading as you edit |
fiddle stories build | Build them as a static site in fiddle-stories/ |
fiddle stories publish | Build and upload them to Fiddle as a build of your branch |
fiddle --version | The installed version |
Options
| Option | Used by | What it does |
|---|---|---|
--root <dir> | stories | The app's root, where its Vite config is. Default: here |
--port <n> | dev | Port. Default 6006, or the next free one |
--out <dir> | build | Output folder. Default fiddle-stories |
--branch <name> | publish | Default: git's, or CI's |
--commit <sha> | publish | Default: git's HEAD, or CI's |
--app <id> | publish | Which app, if your Vite config doesn't say |
--upload-url <url> | publish | A URL from the create_build_upload_url MCP tool. How agents publish |
--key <fdl_…> | publish | A workspace API key, for CI. Or set FIDDLE_API_KEY |
Who's publishing
- You: run
npx fiddle loginonce 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 }}