flusterduck-cli

The command line for Flusterduck, the automatic UX friction detector. Set up the SDK, read confusion scores and issues, manage issues, and record deploys from your terminal or CI. The binary answers to both flusterduck and duck.

Install

npm install -g flusterduck-cli

Or skip the install and run any command through npx flusterduck-cli <command>.

Set up a project

flusterduck init

Detects your framework (Next.js, React, Vue, SvelteKit, Nuxt, or vanilla), signs you in with your browser to pick or create a site, installs the right packages, injects the init call, and then watches for the first real event so you know the install works.

Sign in once

duck login     # browser sign-in mints a key for this terminal, or paste one
duck logout

The key is verified against the API before it is saved to a 0600 file under your config directory. After login, commands need no --key, and a site-scoped key makes --site optional too.

Everyday commands

duck                                 # bare: site health, top issues, last deploy verdict
duck scores                          # per-page confusion scores
duck issues --status open            # ranked UX issues, full titles + ids
duck fix                             # worst open issue: diagnosis + recommended fix
duck fix <id> --prompt               # agent-ready fix brief, pipe it into any coding agent
duck issue show <id>                 # full write-up, recommended fix, evidence
duck issue resolve <id> --note "Fixed in #142"
duck insights --days 30              # confused-vs-calm conversion gap
duck sites                           # every site in the org, scores + sparklines
duck top                             # live view, refreshing until q
duck context                         # the whole picture as markdown for agents
duck status --wait                   # is data flowing for a publishable key?
duck deploy notify                   # record a deploy for fix verification (run in CI)
duck deploy watch                    # wait for the before/after confusion verdict

Every command takes --json for machine-readable output, exit codes are honest, and piped output drops colors and wrapping, so the CLI works as well for agents and scripts as it does for people. deploy notify auto-detects commit metadata on GitHub Actions, Vercel, GitLab, and Bitbucket.

Full documentation: docs.flusterduck.com/cli