MotionScore

Audit animation performance from the command line. MotionScore loads your page in a real browser, measures animations, scroll animations, GPU pressure and layout thrashing across desktop and mobile viewports, and grades the result S through F.

npx motionscore https://example.com

No install, no account. Local audits run a headless browser on your machine and are free and unlimited:

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

By default a run uploads the report and prints a shareable results URL on score.motion.dev. Uploads are metered monthly; local --no-upload runs are not.

MotionScore Guard

Guard is the CI gate: fail the build when animation performance drops below a grade.

npx motionscore https://preview.example.com --threshold A --token $MOTIONSCORE_TOKEN

• Exits 1 when the overall grade is worse than the threshold, so your pipeline fails.
• Runs the browser on your own machine or CI runner. Guard runs are unmetered: they consume none of your monthly audit allowance.
• Requires a paid MotionScore plan (pricing). Get your API token from your Motion dashboard.
• If api.motion.dev cannot be reached to verify your plan, a local run warns and continues rather than failing your build. Pass --strict to fail instead.

GitHub Actions

Use the action for PR comments and a one-line setup. The grades comment is free on any repository (no token needed); threshold and token add the build gate. Create .github/workflows/motionscore.yml in your repository:

on: deployment_status
jobs:
  guard:
    if: github.event.deployment_status.state == 'success'
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: motiondivision/motionscore-guard@v1
        with:
          url: ${{ github.event.deployment_status.environment_url }}
          threshold: A
          token: ${{ secrets.MOTIONSCORE_TOKEN }}

See score.motion.dev/docs/guard for the full step-by-step guide, including auditing multiple pages and making the check required on your default branch.

Options

| Flag | Description | | --- | --- | | --no-upload | Audit locally without uploading. Unlimited, no account needed | | --upload | Upload a --threshold run's result (consumes an audit slot) | | --token <token> | Link results to your account (or set MOTIONSCORE_TOKEN) | | --threshold <tier> | Guard: exit 1 if the overall tier is worse (S/A/B/C/D/F) | | --summary <file> | Write a compact JSON summary (grades, section tiers, top findings) | | --json | Output the full report as JSON (paid plan) | | --cloud | Run the audit on MotionScore's infrastructure (paid plan) | | --private | Mark the uploaded audit as private (paid plan) | | --mobile-only / --desktop-only | Audit a single viewport | | --strict | Fail instead of continuing when api.motion.dev is unreachable |

Exit codes

| Code | Meaning | | --- | --- | | 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 |

Environment

• MOTIONSCORE_TOKEN: API token, equivalent to --token.
• MOTIONSCORE_NO_SANDBOX: set to any value to launch Chrome with --no-sandbox. Needed when the audit fails with No usable sandbox: modern Ubuntu (23.10+, including GitHub-hosted runners) and most containers block Chrome's sandbox for unprivileged processes. The GitHub Action sets this automatically.

How grading works

MotionScore uses a deductive cost model: each section starts at 100 and every animation or violation deducts a cost proportional to its render-pipeline impact (compositor vs paint vs layout, paint area, scroll linkage, thrashing chains, GPU pressure). Because the grade counts structural facts rather than sampled frame timings, it is stable between runs and machines. Full methodology: score.motion.dev/methodology.