CLI

The MotionScore CLI runs animation performance audits from your terminal. It launches a local headless browser, analyses scroll and mount animations, measures GPU pressure, and detects thrashing across both mobile and desktop viewports.

At the end of the audit you'll receive a grade for your animation performance, plus a sharable URL.

Install

No installation required. Run directly with npx:

npx motionscore https://example.com

Local audits run the browser on your own machine and are free and unlimited:

npx motionscore https://example.com --no-upload

By default a run also uploads the report to score.motion.dev and prints a sharable results URL. Uploads count against your monthly audit allowance, and need an identity to meter against: run inside a git repository, or provide an API token.

Authentication

All paid accounts can generate an API token. Set it as a MOTIONSCORE_TOKEN environment variable, or pass --token:

export MOTIONSCORE_TOKEN=your-token
npx motionscore https://example.com

CI/CD integration

MotionScore Guard fails builds that don't meet your performance standard. See the Guard guide for GitHub Actions setup and PR comments.

npx motionscore https://example.com --threshold A

Guard runs are local and unmetered: they consume none of your monthly audit allowance.

Cloud audits

By default, the CLI launches a local Chromium instance. Pro users can use the --cloud option to run the audit on MotionScore's cloud infrastructure instead. This is useful in CI environments where you don't want to install a browser on each run.

npx motionscore https://example.com --cloud

Private audits

By default, audit results are publicly accessible. Pro users can use the --private option to keep audits private, especially useful when auditing staging URLs.

npx motionscore https://example.com --private

Options

--no-upload

Audit locally without uploading. Free, unlimited, and needs no account.

--threshold

Paid plan required.

MotionScore Guard: exit with code 1 if the overall tier is worse than the provided grade.

npx motionscore https://example.com --threshold B

Accepts: S, A, B, C, D, F. Local and unmetered; add --upload to also upload the result (which consumes an audit slot).

--summary

Write a compact JSON summary of the run (grades, section tiers, top findings) to a file. Powers the GitHub Action's PR comment.

npx motionscore https://example.com --summary result.json

--json

Paid plan required.

Returns the raw JSON report instead of the formatted human-readable report.

--cloud

Pro accounts only.

Run the audit on the cloud instead of a local Puppeteer instance.

--private

Pro accounts only.

Marks the audit as private. Unauthenticated users will see a 404 page when visiting this URL.

--mobile-only

Only audit the mobile viewport.

--desktop-only

Only audit the desktop viewport.

--strict

If the CLI cannot reach api.motion.dev to verify your plan, a local run warns and continues rather than failing your build. Pass --strict to fail instead.

--help

Show all available options.

Exit codes

• 0: audit completed, threshold met (or no threshold set)
• 1: overall grade is below --threshold
• 2: error: bad configuration, entitlement rejected, or the audit failed