FAQs | Vibgrate
Frequently asked questions about software migration and modernization.
Can I run Vibgrate without internet access?
Yes. Use --offline with --package-manifest ./latest-packages.zip (pre-downloaded manifest). Download the manifest from github.com/vibgrate/manifests on a connected machine, transfer to your air-gapped environment, then run offline scans. Offline scores are as current as the manifest file. Dashboard push is unavailable in offline mode.
Can I switch from monthly to annual billing?
Yes, you can switch from monthly to annual billing at any time from your account settings. When you switch, you'll receive a prorated credit for any unused time on your current monthly subscription, which is applied to your annual payment. The annual plan begins immediately and you'll start saving right away.
Can I use Vibgrate programmatically in my own code?
Yes. Import types from @vibgrate/cli for type-safe access to scan artifacts: import type { VibgrateConfig, ScanArtifact, DriftScore, Finding } from '@vibgrate/cli'. Read .vibgrate/scan_result.json as JSON and type it as ScanArtifact. Schema is versioned (schemaVersion: '1.0') for stability.
Does Vibgrate support monorepos?
Yes. Vibgrate automatically discovers all projects in your workspace (multiple package.json files, .csproj files, etc.). For npm/pnpm/yarn workspaces, each package is scanned individually and scores are aggregated. Use exclude patterns in vibgrate.config.ts to skip directories like examples/** or legacy/**.
How do I cancel my Vibgrate subscription?
To cancel, go to your Dashboard at dash.vibgrate.com, navigate to Settings > Billing, and click 'Cancel Subscription'. Your access continues until the end of your current billing period. You won't be charged again after cancellation. Your data is retained for 30 days after expiration in case you decide to resubscribe.
How do I compare two scan results?
Use vibgrate sbom delta --from old-scan.json --to new-scan.json to see dependencies added, removed, and changed between scans. For drift score comparison, use baselines: create a baseline, run a new scan with --baseline .vibgrate/baseline.json, and the output shows the delta. Dashboard also shows historical trends.
How do I configure Vibgrate?
Create a vibgrate.config.ts (or .js/.json) file in your project root. Configure exclude patterns to skip directories, thresholds to control finding severity (eolDays, frameworkMajorLag, dependencyTwoPlusPercent), and scanners to enable/disable extended scanners. Run vibgrate init to generate a default config file.
How do I create a drift baseline?
Run vibgrate baseline . to perform a full scan and save the result to .vibgrate/baseline.json. This snapshot becomes your reference point for measuring whether drift is improving or worsening. Commit the baseline to version control so all branches compare against the same reference. Use vibgrate init . --baseline to create both config and baseline in one step.
How do I export SBOMs from Vibgrate scans?
Use vibgrate sbom export to emit CycloneDX or SPDX SBOMs from scan artifacts. Example: vibgrate sbom export --format cyclonedx --out sbom.cdx.json. Use vibgrate sbom delta --from old.json --to new.json to compare dependencies between two scans, showing packages added, removed, or changed.
How do I fix permission denied errors on macOS?
For npm global packages: avoid sudo, instead fix ownership with sudo chown -R $(whoami) ~/.npm and sudo chown -R $(whoami) /usr/local/lib/node_modules. For project files: chmod -R u+rw your-project/. If using nvm, permission issues are rare since packages install in your home directory. For EACCES on .vibgrate folder: chmod -R 755 .vibgrate.
How do I fix permission denied errors on Windows?
Run terminal as Administrator (right-click > Run as Administrator). For persistent issues: check folder permissions (Properties > Security tab), ensure your user has Full Control. For npm global packages: consider using nvm-windows which avoids permission issues. If antivirus is blocking: add node.exe and your project folder to exclusions. For file locking errors: close VS Code or other editors accessing the files.
How do I generate a DSN token?
Run vibgrate dsn create --workspace ws-abc123 to generate an HMAC-signed DSN token. Use --region eu for EU data residency. Use --write .vibgrate/.dsn to save to a file (add to .gitignore). The DSN format is: vibgrate+https://<key_id>:<secret>@<ingest_host>/<workspace_id>. Never commit DSN tokens to source control.
How do I generate reports from existing scans?
Use vibgrate report to render existing scan artifacts into different formats without re-scanning. By default, it reads .vibgrate/scan_result.json. Use --in path/to/artifact.json for a specific file. Use --format md for Markdown (great for PRs), --format text, or --format json. The report command never runs a new scan.
How do I install Node.js on macOS?
Use Homebrew (recommended): brew install node@22. Alternatively, use nvm for version management: curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash then nvm install 22. You can also download the installer directly from nodejs.org. After installation, verify with node --version to ensure you have version 20 or higher.
How do I install Node.js on Windows?
Use winget (recommended): winget install OpenJS.NodeJS.LTS. Alternatively, download the Windows installer from nodejs.org and run it. You can also use Chocolatey: choco install nodejs-lts. After installation, open a new terminal and verify with node --version. Note: You may need to restart your terminal or computer for PATH changes to take effect.
How do I install Node.js to run the Vibgrate CLI?
The Vibgrate CLI requires Node.js >= 20.0.0. On macOS, install via Homebrew: brew install node@22. On Windows, download from nodejs.org or use winget install OpenJS.NodeJS.LTS. On Linux, use your package manager or nvm: nvm install 22. Verify installation with node --version.
How do I install the Vibgrate CLI?
Install as a dev dependency in your project: npm install -D @vibgrate/cli (or use pnpm, yarn, bun). You can also run without installing using npx: npx @vibgrate/cli scan . For global installation: npm install -g @vibgrate/cli. After installation, run vibgrate --help to see available commands.
How do I integrate Vibgrate into CI/CD pipelines?
The CLI requires no login for scanning and returns meaningful exit codes (0=success, 2=threshold exceeded). Basic CI integration: npx @vibgrate/cli scan . --fail-on error. For drift budgets: add --baseline .vibgrate/baseline.json --drift-budget 40. For SARIF upload (GitHub Code Scanning): add --format sarif --out vibgrate.sarif. Works with GitHub Actions, Azure DevOps, GitLab CI, Jenkins, and any CI system with Node.js.
How do I interpret scan findings?
Findings have three severity levels: error (critical issues like EOL runtime, 3+ major framework lag), warning (moderate issues like 2 major framework lag, 30%+ deps behind), and info (informational items). Each finding includes a rule ID, message, description, and location. Address error-level findings first, then warnings.
How do I run my first scan?
Run vibgrate scan . in your project directory. The scan recursively discovers projects (package.json, .csproj, pom.xml, requirements.txt), detects runtime versions and dependencies, queries registries for latest versions, computes drift, and generates findings. The default output is a colored, human-readable report in your terminal.
How do I run Vibgrate in Jenkins?
Use node:22 Docker image or ensure Node.js 22+ is installed on agents. Run npx @vibgrate/cli scan . --format sarif --out vibgrate.sarif --fail-on error. Archive vibgrate.sarif as artifact. The CLI returns exit code 2 on threshold failures, which Jenkins interprets as build failure. No special plugin required.
How do I scan a .NET project?
Run vibgrate scan /path/to/dotnet-solution. Vibgrate discovers .sln and .csproj files, evaluates target framework version (net6.0, net7.0, net8.0), .NET SDK version from global.json, NuGet packages from PackageReference elements, and EOL risk for .NET versions. Each project gets its own drift score, with aggregate scores for solutions.
How do I scan a Java project?
Run vibgrate scan /path/to/java-project. Vibgrate discovers pom.xml (Maven) and build.gradle/build.gradle.kts (Gradle) files. It analyzes Java version, all dependencies, package version lag against Maven Central, framework versions (Spring Boot, Quarkus, etc.), and EOL risk. Multi-module projects are fully supported.
How do I scan a Node.js or TypeScript project?
Run vibgrate scan . in your project directory. Vibgrate detects package.json files, lockfiles (npm, pnpm, yarn), .nvmrc/.node-version, and tsconfig.json. It analyzes runtime version, framework versions (React, Next.js, etc.), all dependencies from package.json, lockfile duplicates, and TypeScript modernity. Works with monorepos automatically.
How do I scan a Python project?
Run vibgrate scan /path/to/python-project. Vibgrate detects requirements.txt, pyproject.toml, setup.py, and Pipfile. It analyzes Python version from .python-version or pyproject.toml, all dependencies, package version lag against PyPI, and EOL risk for Python versions. Supports Poetry, PEP 621, and Pipenv formats.
How do I scan a specific directory instead of the whole project?
Pass the path as an argument: vibgrate scan ./packages/api or vibgrate scan /absolute/path/to/project. The scan will discover projects recursively from that path. To exclude subdirectories, use the exclude array in vibgrate.config.ts.
How do I set environment variables on macOS?
For zsh (default on modern macOS): add export VIBGRATE_DSN="your-dsn" to ~/.zshrc, then run source ~/.zshrc. For bash: add to ~/.bash_profile or ~/.bashrc. For a single session: run export VIBGRATE_DSN="your-dsn" directly in terminal. Project-level: create a .env file with VIBGRATE_DSN=your-dsn and use a tool like direnv or dotenv to load it.
How do I set environment variables on Windows?
GUI method: Search 'Environment Variables' > Edit system environment variables > Environment Variables button > User variables > New > Name: VIBGRATE_DSN, Value: your-dsn. Command line (current session): set VIBGRATE_DSN=your-dsn (cmd) or $env:VIBGRATE_DSN="your-dsn" (PowerShell). Persistent via PowerShell: [Environment]::SetEnvironmentVariable('VIBGRATE_DSN', 'your-dsn', 'User'). Restart terminals after changes.
How do I set up the DSN (Data Source Name) for dashboard uploads?
Set the VIBGRATE_DSN environment variable with your DSN token. System-wide: add export VIBGRATE_DSN="your-dsn" to ~/.zshrc or ~/.bashrc (macOS/Linux) or set via System Properties > Environment Variables (Windows). Project-level: add to your .env file (never commit this). In CI, store as a secret (GitHub Secrets, Azure DevOps Variables, GitLab CI Variables).
How do I set up Vibgrate in Azure DevOps?
Add NodeTool@0 task with versionSpec: '22.x', then run npx @vibgrate/cli scan . --fail-on error. For SARIF artifacts: add --format sarif --out vibgrate.sarif, then use PublishBuildArtifacts@1 task. Store VIBGRATE_DSN in pipeline variables for dashboard push. Works with both classic and YAML pipelines.
How do I set up Vibgrate in GitLab CI?
Use node:22 image and run npx @vibgrate/cli scan . --format sarif --out vibgrate.sarif --fail-on error. Add artifacts.reports.sast: vibgrate.sarif for SAST integration. Findings appear in Security Dashboard and merge requests. Store VIBGRATE_DSN in CI/CD variables for dashboard push.
How do I update my payment information?
To update your payment method, log into the Vibgrate Dashboard at dash.vibgrate.com, navigate to Settings > Billing, and click 'Update Payment Method'. You can add a new card or update your existing card details. Changes take effect immediately. You'll also receive email notifications before any payment is processed.
How do I update the Vibgrate CLI?
Run vibgrate update to check for and install updates. Use --check to see if updates are available without installing. For project installs: npm update @vibgrate/cli or reinstall with npm install -D @vibgrate/cli@latest. For npx users, it automatically fetches the latest version each time.
How do I upload SARIF results to GitHub Code Scanning?
Run scan with SARIF output: npx @vibgrate/cli scan . --format sarif --out vibgrate.sarif --fail-on error. Then use github/codeql-action/upload-sarif@v3 with sarif_file: vibgrate.sarif. Requires security-events: write permission. Findings appear in the Security tab and inline on PRs.
How do I upload scan results to the dashboard?
Use vibgrate push after running a scan, or combine them with vibgrate scan . --push. The DSN is read from VIBGRATE_DSN environment variable or pass with --dsn. Use --strict to fail if upload fails (for CI). Use --region eu for EU data residency. Dashboard upload is always optional — the CLI provides full value locally.
How does proration work when I upgrade or downgrade my plan?
When you upgrade, you're charged immediately for the difference between your current plan and the new plan, prorated for the remaining time in your billing cycle. When you downgrade, you'll receive a credit toward future invoices for the unused portion of your current plan. Changes take effect immediately.
How does Vibgrate analyze TypeScript configuration?
Vibgrate reads tsconfig.json to assess TypeScript modernity: TypeScript version, strict mode flags (strict, noImplicitAny, strictNullChecks), module system (module, moduleResolution, target), and ESM vs CJS classification. Strict TypeScript configurations score higher in the modernity assessment. This is part of the extended scanners.
I'm getting network timeout errors during scans. How do I fix this?
Network timeouts usually occur when querying package registries. Solutions: increase timeout with --timeout 60000, reduce concurrency with --concurrency 4, or use offline mode with a pre-downloaded manifest. If behind a corporate proxy, ensure npm is configured: npm config set proxy http://proxy:port. Check your network connectivity to registry.npmjs.org.
I'm getting Node.js version errors. What should I do?
Vibgrate requires Node.js >= 20.0.0. Check your version: node --version. If too old, upgrade using nvm (nvm install 22), Homebrew (brew upgrade node), or download from nodejs.org. If you have multiple Node versions, use nvm or similar to switch: nvm use 22. CI environments should specify node-version: 22 in their setup steps.
Should I add .vibgrate to .gitignore?
Add .vibgrate/scan_result.json to .gitignore (it changes on every scan). Keep .vibgrate/baseline.json in version control so CI can compare against it and all branches use the same reference. The generated vibgrate.config.ts should also be committed.
Should I use npx or install Vibgrate globally?
Use npx @vibgrate/cli scan . for one-off scans without installation — always gets the latest version. For projects, install as devDependency (npm install -D @vibgrate/cli) for reproducible scans with a pinned version. Avoid global install (npm install -g) in CI; prefer npx or project-local install for consistency.
The scan mentions missing security scanners. What should I do?
Extended security scanners check for installed tools like npm audit. If tools are missing, you can use --install-tools to auto-install via Homebrew (macOS). On other platforms, manually install the recommended tools. These scanners are optional — core drift analysis runs regardless of whether security tools are installed.
The scan says lockfile not found. Is that a problem?
Lockfile warnings indicate you don't have a package-lock.json, yarn.lock, pnpm-lock.yaml, or bun.lockb. This affects dependency graph analysis and duplicate detection but won't block the scan. For full analysis, generate a lockfile: npm install (creates package-lock.json), yarn install (creates yarn.lock), or pnpm install (creates pnpm-lock.yaml).
What are common errors when running the CLI on macOS?
Common issues: 'command not found: vibgrate' (package not installed globally or npx not used). Permission denied (use sudo cautiously or fix with sudo chown -R $(whoami) ~/.npm). EACCES errors (npm cache permissions — run npm cache clean --force). SSL certificate errors (try npm config set strict-ssl false temporarily). xcode-select errors (run xcode-select --install).
What are common errors when running the CLI on Windows?
Common issues: 'node' is not recognized (Node.js not in PATH — restart terminal or reinstall). Execution policy errors in PowerShell (run Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned). Long path errors (enable long paths: registry key HKLM\SYSTEM\CurrentControlSet\Control\FileSystem LongPathsEnabled=1). Permission denied on node_modules (run terminal as Administrator or fix folder permissions).
What are EOL (End of Life) findings?
EOL findings alert you when your runtime (Node.js, .NET, Python) is approaching or past its end-of-life date. Running unsupported runtimes poses security risks. Default threshold: error if EOL is within 180 days. Adjust in vibgrate.config.ts under thresholds.failOnError.eolDays. Check nodejs.org/en/about/releases for Node.js EOL dates.
What are extended scanners?
Beyond core drift scoring, Vibgrate runs extended scanners: Platform Matrix (detects OS-specific dependencies), Dependency Risk (deprecated packages, native modules), TypeScript Modernity (strict mode analysis), Security Posture (lockfile presence, .gitignore coverage), Build & Deploy (CI systems, Docker, IaC detection), and more. All are read-only and can be individually toggled in config.
What are native module warnings?
Native module warnings indicate your project depends on packages that compile native code (e.g., sharp, bcrypt, node-gyp). These can cause issues when building on different architectures (ARM vs x64) or operating systems. The Platform Matrix scanner detects these to help predict where builds might break during CI runner or container migrations.
What are the best practices for managing the VIBGRATE_DSN?
Never commit DSN tokens to source control. Store DSNs as CI/CD secrets. Use separate DSNs for different environments (dev, staging, production) if needed. Rotate DSN tokens periodically. For local development, add VIBGRATE_DSN to your .env file and ensure .env is in .gitignore. In CI, always use the secret manager provided by your platform.
What currency is Vibgrate billed in, and is tax included?
All Vibgrate subscriptions are billed in US Dollars (USD). Prices shown on the pricing page are exclusive of tax. Depending on your location, applicable sales tax, VAT, or GST may be added to your invoice at checkout. Tax amounts are calculated automatically by Stripe based on your billing address.
What data does Vibgrate collect?
Vibgrate is privacy-first. It NEVER reads source code (only manifest/config files), never scans for secrets, never reads environment values, never accesses git identity data. It DOES collect package names and versions, config structure flags (e.g., strict: true), file names/sizes (not contents), and public registry metadata. Use --max-privacy for minimal collection.
What data residency options are available for the dashboard?
Vibgrate supports US (default, us.ingest.vibgrate.com) and EU (eu.ingest.vibgrate.com) data residency. Use --region eu with the push command to route data to the EU endpoint. You can also specify the region when creating a DSN: vibgrate dsn create --workspace ws-123 --region eu.
What do deprecated package warnings mean?
Deprecated package warnings appear when the npm registry marks a package as deprecated. This usually means the package is unmaintained, has security issues, or has been replaced by a better alternative. Common examples: request, node-sass, tslint, moment. Replace these packages to improve your drift score and reduce security risk.
What do the CLI exit codes mean?
Exit code 0: Success (scan completed, all gates passed). Exit code 1: Runtime error (invalid flags, missing files, crash). Exit code 2: Threshold exceeded (--fail-on severity gate or drift budget/worsening gate triggered). Use these codes to control CI pipeline flow.
What do the Drift Score risk levels mean?
Scores of 70–100 indicate Low risk (you're in good shape). Scores of 40–69 indicate Moderate risk (some attention needed). Scores of 0–39 indicate High risk (significant upgrade debt). The score is deterministic — the same inputs always produce the same score, making it suitable for CI quality gates.
What does --max-privacy mode do?
--max-privacy enables hardened privacy mode: runs only minimal scanners, writes no local artifacts (.vibgrate/*.json), and reduces data collection to the bare minimum needed for drift scoring. Use this in highly regulated environments or when you want to minimize any local file writes.
What does --strict do on the push command?
When --strict is set, the push command exits with error code if the dashboard upload fails (network error, authentication problem, etc.). Without --strict, push failures are logged but don't affect the exit code. Use --strict in CI when you want builds to fail if metrics can't be uploaded to the dashboard.
What does the --changed-only flag do?
The --changed-only flag scans only files that have changed (typically detected via git diff). This speeds up scans in CI by skipping unchanged projects in monorepos. Useful for pull request checks where you only care about drift in modified code. Still compares against full baseline for accurate regression detection.
What does the scan command analyze?
The scan analyzes: runtime versions (Node.js, .NET, Python, Java), framework versions (React, Next.js, Angular, Vue, NestJS, etc.), all dependencies from package.json, .csproj, requirements.txt, or pom.xml, lockfile data (duplicates, phantom deps), TypeScript configuration (strict mode, module system), and end-of-life risk for runtimes. Core analysis reads only manifest/config files — no source code execution.
What does the Vibgrate Dashboard show?
The Dashboard provides a shared view of drift across your projects, including historical trend charts, portfolio-level risk assessment, and team visibility. You can track drift scores over time, compare projects, and monitor improvement trends. Dashboard upload is always optional — the CLI provides full value locally without any server connection.
What does the vibgrate init command do?
The vibgrate init command sets up Vibgrate in your project by creating a .vibgrate/ directory for scan artifacts and baselines, plus a vibgrate.config.ts file with sensible defaults. Use --baseline to also create an initial drift baseline. Use --yes to skip confirmation prompts. This is typically the first command when adopting Vibgrate.
What flags does the scan command support?
Key flags: --format (text/json/sarif/md), --out (output file), --fail-on (error/warn - exit code 2 if findings exist), --baseline (compare against baseline), --drift-budget (fail if score exceeds value), --drift-worsening (fail if drift worsens by %), --push (upload to dashboard), --dsn (DSN for push), --offline (no network calls), --max-privacy (minimal data collection).
What happens if my payment fails?
If a payment fails, we'll notify you by email and automatically retry the charge after 3 days. We'll make up to 3 retry attempts over 9 days. During this time, your service continues uninterrupted. If all retries fail, your subscription will be paused until you update your payment method in Settings > Billing.
What is a drift budget and how do I use it?
A drift budget sets a maximum acceptable drift score. Use --drift-budget 40 to fail the scan (exit code 2) if your drift score exceeds 40. Combine with --drift-worsening 5 to fail if drift has worsened by more than 5% compared to baseline. This creates 'fitness functions' that prevent drift regression in CI.
What is the baseline.json file for?
The .vibgrate/baseline.json file is a snapshot of your drift score at a point in time. It serves as a reference point for CI gates — you can fail builds if drift worsens beyond a threshold compared to baseline. Create it with vibgrate baseline . after your main branch is stable. Commit it to version control. Refresh after planned upgrade sprints.
What is the difference between monthly and annual billing?
Monthly billing charges your card each month at the listed price. Annual billing charges once per year at a discounted rate — you save the equivalent of 2 months by paying annually. For example, Starter is $49/month or $490/year (saving $98). You can switch between billing cycles at any time from your account settings.
What is the Drift Score and how is it calculated?
The Drift Score is a metric from 0–100 that represents how far behind your codebase is relative to current stable ecosystem baselines. Higher scores mean healthier upgrade posture. It's calculated from four weighted components: Runtime (Node.js/.NET version lag), Frameworks (major version distance for React, Next.js, etc.), Dependencies (age distribution across all deps), and EOL Risk (proximity to end-of-life dates).
What is the scan_result.json file?
The .vibgrate/scan_result.json file is the full output artifact from your most recent scan. It contains all raw data, scores, findings, and VCS metadata in a stable JSON schema (schemaVersion: '1.0'). Add it to .gitignore since it changes on every scan. Use it for programmatic consumption or to generate reports with vibgrate report.
What is Vibgrate?
Vibgrate is a command-line tool (CLI) that scans your codebase for upgrade drift — the gap between the dependency versions you run and the versions you should run. It produces a deterministic Drift Score (0–100) and actionable findings to help you maintain healthy, up-to-date software.
What is Vibgrate's refund policy?
We offer a full refund within 14 days of your initial purchase if you're not satisfied. For annual subscriptions, refund requests after 14 days are handled on a case-by-case basis with a prorated amount. To request a refund, contact support@vibgrate.com with your account details. Refunds are typically processed within 5-10 business days.
What languages and ecosystems does Vibgrate support?
Vibgrate supports Node.js/TypeScript (package.json, npm/pnpm/yarn/bun lockfiles), .NET (*.csproj, *.sln, NuGet), Python (requirements.txt, pyproject.toml, Pipfile, setup.py), and Java (pom.xml for Maven, build.gradle for Gradle). Each ecosystem gets drift analysis against its respective package registry (npm, NuGet, PyPI, Maven Central).
What output formats does the scan support?
Four formats: Text (default, colored human-readable), JSON (full artifact for automation), SARIF (for GitHub Code Scanning, Azure DevOps), and Markdown (for PRs, wikis, docs). Use --format json, --format sarif, or --format md. Use --out filename to write to a file instead of stdout.
What payment methods does Vibgrate accept?
Vibgrate accepts all major credit and debit cards including Visa, Mastercard, American Express, and Discover. Payments are processed securely through Stripe, a PCI-compliant payment processor. All transactions are charged in USD. For Enterprise plans, we can also accommodate invoicing and wire transfers upon request.
What's the difference between --fail-on error and --fail-on warn?
--fail-on error exits with code 2 only if error-level findings exist (e.g., runtime near EOL, framework 3+ majors behind). --fail-on warn exits with code 2 if warning-level OR error-level findings exist. Use --fail-on error in CI to catch critical issues; add --fail-on warn when you want stricter enforcement.
Where can I find my invoices and receipts?
All invoices and receipts are available in your Vibgrate Dashboard under Settings > Billing > Invoice History. You can view, download as PDF, or email any invoice to your accounts payable team. Invoices are also automatically sent to the billing email on file after each successful payment.
Why is the scan taking a long time?
Slow scans are usually due to registry network calls. Try --concurrency 16 to increase parallel registry requests. For repeated scans, results are cached. If scanning many projects in a monorepo, consider excluding irrelevant directories. For air-gapped or slow networks, use --offline with a pre-downloaded manifest.