# CLI

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

```bash
npm install -D @basswood/fiddle
```

## Commands

| 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 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`.

```yaml
- run: npx fiddle stories publish
  env:
    FIDDLE_API_KEY: ${{ secrets.FIDDLE_API_KEY }}
```
