Documentation

Installation

Run directly with npx, or install globally or as a project dev dependency.

# Run without installing
npx expo-ci-doctor doctor

# Install globally
npm install -g expo-ci-doctor

# Add as a dev dependency (recommended for teams)
npm install -D expo-ci-doctor

Requires Node.js 18 or later. No additional native dependencies.

License Setup

Expo CI Doctor uses a subscription-based license tied to your account. Your license key starts with ecd_ and is available in your account dashboard.

Local Development

Use the login command to authenticate interactively. The key is stored in ~/.expo-ci-doctor/license.

npx expo-ci-doctor login

CI Environments

In CI, set the license key as a secret environment variable. The environment variable takes precedence over any locally stored key.

# Set as environment variable
export EXPO_CI_DOCTOR_KEY=ecd_your_license_key_here

# Or in your CI secrets and reference it as:
# EXPO_CI_DOCTOR_KEY: ${secrets.ECD_KEY}

The environment variable name is EXPO_CI_DOCTOR_KEY. If this variable is set, the tool will use it and skip any local key lookup.

Command Reference

All commands accept --help for inline flag documentation.

npx expo-ci-doctor check
npx expo-ci-doctor check --json          # JSON output for scripting
npx expo-ci-doctor check --format=md    # Markdown output

npx expo-ci-doctor analyze
npx expo-ci-doctor analyze --ci           # CI mode
npx expo-ci-doctor analyze --ci-summary  # Compact summary line for CI logs
npx expo-ci-doctor analyze --json        # JSON output
npx expo-ci-doctor analyze --format=md  # Markdown report

npx expo-ci-doctor doctor
npx expo-ci-doctor doctor --ci            # CI mode
npx expo-ci-doctor doctor --ci-strict    # Exit 1 on warnings, not just errors
npx expo-ci-doctor doctor --ci-summary  # Single-line CI summary
npx expo-ci-doctor doctor --json        # JSON output
npx expo-ci-doctor doctor --format=md  # Markdown report

npx expo-ci-doctor preflight
npx expo-ci-doctor preflight --ci
npx expo-ci-doctor preflight --format=md

# Take a snapshot
npx expo-ci-doctor diff --snapshot

# Compare current state against last snapshot
npx expo-ci-doctor diff

# Output diff as Markdown
npx expo-ci-doctor diff --format=md

npx expo-ci-doctor login
npx expo-ci-doctor logout
npx expo-ci-doctor whoami

Feature Deep Dives

npx expo-ci-doctor doctor --json | jq .score

npx expo-ci-doctor doctor --upgrade
npx expo-ci-doctor doctor --upgrade --format=md

npx expo-ci-doctor analyze --noise

# Save Markdown report to file
npx expo-ci-doctor doctor --format=md > build-report.md

# Or pipe directly to a command
npx expo-ci-doctor doctor --format=md | gh pr comment --body-file=-

CI Usage Guide

The tool is designed to run without human interaction in CI environments. Use --ci to suppress interactive prompts and spinners.

GitHub Actions — Standard Usage

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: 20

      - name: Install dependencies
        run: npm ci

      - name: Run Expo CI Doctor
        env:
          EXPO_CI_DOCTOR_KEY: ${{ secrets.ECD_KEY }}
        run: npx expo-ci-doctor doctor --ci --ci-strict

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

GitHub Actions — Markdown Report as PR Comment

      - name: Run Expo CI Doctor (Markdown)
        env:
          EXPO_CI_DOCTOR_KEY: ${{ secrets.ECD_KEY }}
        run: npx expo-ci-doctor doctor --ci --format=md > ecd-report.md

      - name: Post report to PR
        if: github.event_name == 'pull_request'
        uses: marocchino/sticky-pull-request-comment@v2
        with:
          path: ecd-report.md

Authentication in CI

Do not use npx expo-ci-doctor login in CI. Set the key as a secret environment variable instead:

# In GitHub Actions, add ECD_KEY as a repository secret
# Then reference it in your workflow:
env:
  EXPO_CI_DOCTOR_KEY: ${{ secrets.ECD_KEY }}

Compact CI Logging

Use --ci-summary for a single-line summary suitable for CI log readability and notifications:

npx expo-ci-doctor doctor --ci --ci-summary

Example output: PASS | Score: 91 | 0 errors, 1 warning | sdk-mismatch

Exit Codes

Exit codes allow CI pipelines to gate builds based on tool output.

Configuration File

Place a .expo-ci-doctor.json file in your project root to customize behavior. All fields are optional.

{
  "ignore": [
    "native-module-version",
    "expo-sdk-mismatch"
  ],
  "thresholds": {
    "doctor-score": 70,
    "confidence": 65
  },
  "monorepo": {
    "root": "../..",
    "packages": ["packages/*", "apps/*"]
  },
  "output": {
    "format": "md",
    "summaryOnly": false
  }
}

Plans and Licensing

Expo CI Doctor uses subscription-based licensing. The license key is verified on each run against the active subscription. No offline activation is supported.

How License Verification Works

On each command run, the CLI reads the license key from the environment variable EXPO_CI_DOCTOR_KEY or from the local key store at ~/.expo-ci-doctor/license. It makes a lightweight request to expocidoctor.dev/api/license/verify to confirm the key is valid and the subscription is active. The plan name is returned and used to gate Pro features.

If the subscription has lapsed or the key is invalid, gated commands will return an error and exit with code 3. The check command continues to work without a license.

No project data is sent during license verification. The only payload is the license key.