Getting started

Arol catches deprecated third-party APIs, SDKs, and model ids in your code — exact file and line — before their sunset dates. It's two commands: npx arol-ai scan audits the repo you're standing in right now, and npx arol-ai init makes it continuous: a gate on every PR plus a weekly scheduled scan, so the next deprecation finds you before its shutdown date does. One is the audition, the other is the point.

Install

No install needed — npx runs the latest version:

npx arol-ai scan

Prefer a global install (Node 18+):

npm install -g arol-ai
arol-ai scan

Your first scan

Run it from the root of any repository:

npx arol-ai scan

This scans the directory you're standing in: it walks your source files (.js .ts .jsx .tsx .py .go and friends), checks real usage against the deprecation dataset, and prints a report — typically in a few seconds. Everything runs locally; your code is never uploaded.

To scan somewhere else without changing directories, pass a path:

npx arol-ai scan ./my-repo

Useful when you keep several repos side by side, or in scripts that scan a checkout at a known location. Everything else on this page works identically with or without the path argument.

Reading the report

● OpenAI · Assistants API (beta)  HIGH
  references a deprecated API · sunsets 2026-08-26 (in 40 days)
  found in:
    src/agents/run.ts:42  →  beta.assistants
  → migrate: https://platform.openai.com/docs/assistants/migration

Top to bottom: what's deprecated and how severe · when it breaks · the exact lines in your code · the vendor's migration guide. A clean scan prints ✓ No upcoming deprecations detected. For what to do with a finding, see Handling scan failures.

Everyday options

Skipping paths: --ignore and .arolignore

npx arol-ai scan --ignore 'docs/**' --ignore '**/*.gen.ts'

Dependency and build directories (node_modules, dist, .venv, vendor, …) are skipped automatically — --ignore is for your paths: generated code, vendored examples, fixture folders, anything you can't or won't fix. The flag is repeatable and takes gitignore-style globs.

For permanent exclusions, put the same globs in a .arolignore file at the repo root so every scan (local and CI) agrees:

# generated SDK examples we never run
examples/
**/*.gen.ts

Comments (#), leading / anchoring, and trailing / for directories all work like .gitignore. --ignore flags and .arolignore combine — you never need to choose.

Machine-readable output: --json

npx arol-ai scan --json

Emits the full scan as JSON instead of the report: file counts, dataset provenance (origin, fetchedAt), severity counts, and every finding with its id, severity, status, dates, vendor source URL, confidence, and exact file/line matches. Exit codes behave identically, so you can keep the CI gate and feed dashboards or custom tooling:

# e.g. list finding ids with their sunset dates
npx arol-ai scan --json | jq -r '.findings[] | "\(.id)  \(.sunset_date)"'

The schema is treated as a public interface: fields get added over time, never renamed or removed — safe to build scripts against.

Plain text: --no-color

npx arol-ai scan --no-color

Disables ANSI colors for log archives and text diffs. You rarely need it explicitly: colors already auto-disable when output isn't a terminal (piped or redirected), and the standard NO_COLOR environment variable is respected. The inverse exists too — FORCE_COLOR=1 keeps colors on in CI systems that render them.

Adding it to CI

GitHub Actions: one command

npx arol-ai init

This writes .github/workflows/arol.yml — review it in your diff, commit, and push. The generated workflow scans every pull request and push to main/master, and runs a weekly scheduled scan. The schedule matters more than it looks: deprecations land on repos where nobody is pushing, and GitHub emails you when a scheduled run fails — that email is your early warning.

init is deliberately cautious: it never overwrites an existing workflow (use --force to regenerate), it recognizes a hand-written arol workflow under any other filename and leaves it alone, and it writes nothing when the repo's remotes aren't GitHub.

After writing the workflow, init offers to finish monitoring setup in the same breath: paste a token from arol.ai/dashboard/tokens and it does two things. First, it saves the token for this repo only — into .git/arol-token, which git can never commit or push — so local scans of this repo report to your dashboard immediately (rm .git/arol-token turns that off). Second, if you have the GitHub CLI installed, it sets the AROL_REPORT_TOKEN repo secret on the spot so CI scans report too; without gh, it prints your repo's exact secrets-settings link instead. The prompt only appears in interactive terminals (CI runs skip it), Enter skips it, --token <token> supplies it non-interactively, and re-running arol-ai init later brings the offer back.

The scope rule is deliberate: only the repo you configured reports — from your laptop or from CI. Every other repo you scan stays fully local. There is no global token and no machine-wide state; scanning a repo you never ran init in uploads nothing, ever.

Everywhere else: one line

npx arol-ai scan is the only line that matters — it works identically in GitLab CI, CircleCI, Jenkins, or a cron job. GitLab, for instance:

arol:
  image: node:20
  script: npx arol-ai scan

Tuning the CI gate

Exit codes are designed so a red build always means something real:

Code	Meaning
0	Clean, or warn-only findings (printed, not build-breaking).
1	An actionable finding — see below.
2	Misconfiguration: bad path, unreadable dataset, or zero scannable files (a mis-pointed scan must not go green).

A finding is actionable when it is high severity and not yet retired, or scheduled to sunset within the window (--within <days>, default 30). Medium/low findings outside the window, dateless deprecations, and already-retired items are warn-only. Findings whose only evidence is in test files never fail the build.

npx arol-ai scan --within 7        # only fail when a sunset is < 1 week out
npx arol-ai scan --fail-on-retired # also fail on already-past high-severity sunsets

Advanced: dataset freshness & restricted environments

Before scanning, the CLI refreshes its deprecation dataset (one public JSON file, at most once per 24h, cached in ~/.cache/arol). This is fail-soft: network trouble means the cached/bundled dataset is used and the scan proceeds — a build can never break because a download did. The report header shows which was used (dataset: updated today / dataset: bundled).

Forcing a refresh: arol-ai update

arol-ai update

Fetches the latest dataset right now, ignoring the 24-hour window. The download is validated before it replaces your cache — a truncated or corrupt file can never overwrite a good one. Unlike scan, this command is deliberately loud: it exits 2 on failure so you know the refresh didn't happen. Use it when a new deprecation was just announced and you want to scan for it immediately, or in CI setups that pre-warm caches.

Going fully offline: --offline

npx arol-ai scan --offline

Disables all network use for this run — behavior identical to versions before auto-refresh existed. The scan uses the cached dataset if one exists, otherwise the copy bundled with the CLI, and the report header says so (· offline). For CI runners and air-gapped machines, set it environment-wide instead:

AROL_OFFLINE=1 npx arol-ai scan

AROL_CACHE_DIR relocates the cache directory when ~/.cache isn't writable or you want the dataset vendored alongside your pipeline.

Continuous monitoring: --report

npx arol-ai scan --report <token>

Opt-in reporting for the Arol dashboard: each scan uploads results and your dependency inventory so new deprecations can alert you without a re-scan. Full setup, payload details, and findings vs notifications: Continuous monitoring. Privacy of what gets sent: Privacy & network.

In CI, set AROL_REPORT_TOKEN as a repo secret (the arol-ai init workflow already reads it). --report-name <name> overrides the dashboard repo name. No token means nothing is ever sent; an unreachable endpoint never affects the scan or its exit code.

Bringing your own dataset: --data

npx arol-ai scan --data ./our-deprecations.json

Scans against your own file — same schema as the bundled dataset, so you can track deprecations of internal APIs, or pin an exact reviewed dataset snapshot in regulated environments. --data replaces the public dataset rather than merging with it, and auto-refresh is skipped entirely: you control that file's freshness. Schema details: Dataset reference.