Documentation

Everything you need to get started with expo-ci-doctor.

Installation

Install expo-ci-doctor globally or use it directly with npx:

Installation

# Using npx (recommended)\nnpx expo-ci-doctor doctor\n\n# Or install globally\nnpm install -g expo-ci-doctor\n\n# Or add as a dev dependency\nnpm install -D expo-ci-doctor

Commands

check

Run basic configuration checks. Scans app.json, eas.json, package.json and validates structure, required fields, and compatibility.

npx expo-ci-doctor check\nnpx expo-ci-doctor check --json  # JSON output

analyze

Advanced CI failure analysis. Matches your project against 50+ known failure patterns with confidence scoring. Requires a license.

npx expo-ci-doctor analyze\nnpx expo-ci-doctor analyze --ci  # CI mode (non-interactive)

doctor

Full diagnostic. Runs all checks, analysis, and provides a weighted verdict (PASS / WARN / FAIL) with actionable fix suggestions. Requires a license.

npx expo-ci-doctor doctor
npx expo-ci-doctor doctor --ci          # CI mode
npx expo-ci-doctor doctor --json        # JSON output
npx expo-ci-doctor doctor --ci-strict   # Fail on warnings

activate

Activate your license key. The key is verified once and stored locally.

npx expo-ci-doctor activate ecd_your_license_key_here

CI Integration

Add expo-ci-doctor as a pre-build step in your CI pipeline to catch issues before they waste build minutes.

GitHub Actions

.github/workflows/build.yml

name: EAS Build
on:
  push:
    branches: [main]
  pull_request:

jobs:
  diagnose-and-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 18

      - name: Install dependencies
        run: npm ci

      - name: Run expo-ci-doctor
        env:
          EXPO_CI_DOCTOR_LICENSE_KEY: ${{ secrets.ECD_LICENSE_KEY }}
        run: npx expo-ci-doctor doctor --ci-strict

      - name: Build with EAS
        run: npx eas-cli build --platform all --non-interactive

Environment Variable

In CI, set the license key as an environment variable instead of using the activate command:

export EXPO_CI_DOCTOR_LICENSE_KEY=ecd_your_license_key_here

Exit Codes

Use exit codes to control your CI pipeline behavior:

Code	Meaning	Action
0	All checks passed	Safe to build
1	Warnings found	Build may succeed but review warnings
2	Errors found	Build likely to fail, fix before building
3	Tool error	expo-ci-doctor itself encountered an error

License Activation

After purchasing, you'll receive a license key starting with ecd_. Activate it in one of two ways:

Method 1: CLI Activation

npx expo-ci-doctor activate ecd_your_license_key_here

This stores the key locally in ~/.expo-ci-doctor/license.

Method 2: Environment Variable

# In .env or CI secrets
EXPO_CI_DOCTOR_LICENSE_KEY=ecd_your_license_key_here

The environment variable takes priority over the local activation.

Configuration

Customize expo-ci-doctor behavior with a .expo-ci-doctor.json file in your project root:

.expo-ci-doctor.json

{
  "ignore": [
    "native-module-version",
    "expo-sdk-mismatch"
  ],
  "thresholds": {
    "doctor-score": 60,
    "confidence": 70
  },
  "monorepo": {
    "root": "../..",
    "packages": ["packages/*", "apps/*"]
  }
}

Ready to get started?

Get your lifetime license and start catching build failures today.

Buy lifetime license