Skip to main content

CLI: eyes-storybook arguments

Overview​

After completing the installation of the Applitools Eyes SDK for Storybook and defining the API key (see here), you will be able to execute npx eyes-storybook from the command line and it will capture screenshots of all your stories.

Use CLI flags when you need to run a subset, point at a specific Storybook URL, or tune runtime behavior without changing repo config—especially handy in CI or debugging sessions. The CLI reads your config and env vars, then applies its flags on top (highest precedence).

Usage​

npx eyes-storybook [options]

Flags (with context & examples)​

  • -f, --conf <path>
    Use a non‑standard config path (mono‑repos, examples):

    npx eyes-storybook --conf packages/ui/applitools.config.js

  • -u, --storybookUrl <url>
    Point to a running or static Storybook instead of having Eyes start one. Prefer this in CI:

    npx http-server storybook-static -p 6006 &
    npx eyes-storybook -u http://localhost:6006

  • -p, --storybookPort <number>, -h, --storybookHost <host>
    Tell Eyes how to start Storybook for you:

    npx eyes-storybook -p 9001 -h 0.0.0.0

  • -c, --storybookConfigDir <path>
    Non‑default .storybook location:

    npx eyes-storybook -c apps/marketing/.storybook

  • -s, --storybookStaticDir <path[,path]>
    Mount static asset folders (comma‑separated):

    npx eyes-storybook -s public,../shared-assets

  • --showStorybookOutput
    Pipe SB server logs for troubleshooting.

  • --readStoriesTimeout <ms>
    Increase when heavy addons delay story discovery (slow CI):

    npx eyes-storybook --readStoriesTimeout 120000

  • --include <title or /regex/>
    Run a subset to iterate faster:

    npx eyes-storybook --include "Button: Primary"
    npx eyes-storybook --include /Card:.*/

  • --networkBlockPatterns <csv>
    Block noisy third‑party calls:

    npx eyes-storybook --networkBlockPatterns "*/ads/*,*/analytics/*"

  • --browserCacheRequests
    Cache requests across stories for speed.

  • --navigationWaitUntil <load|domcontentloaded|networkidle0|networkidle2>
    Choose when SB navigation counts as done (complex async UIs often benefit from networkidle2).

  • -e, --exitcode
    Exit non‑zero on unresolved/failed tests—use to gate PRs in CI.

Quick recipes​

  • Serve static and run: 
    npm run build-storybook && npx http-server storybook-static -p 6006 &
    npx eyes-storybook -u http://localhost:6006 -e
  • Debug a single component: 
    npx eyes-storybook --include /Button:.*/ --showStorybookOutput

Notes​

  • Eyes can start Storybook for you (dev server) or you can point to a running/static URL with --storybookUrl.
  • For CI, prefer a static build (build-storybook) served on a predictable URL; then run npx eyes-storybook -u <url>.