kyro

kyro is a lightweight, super-fast React Native environment and project health checker CLI. It helps React Native developers quickly diagnose issues with their local environment or project structures.

Features

• Blazing Fast: No heavy React Native dependencies to load—starts and finishes checks in milliseconds.
• Cross-Platform: Works seamlessly on macOS, Windows, and Linux.
• Clear UI: Clean table layouts, aligned columns, colored symbols, and actionable suggestions.
• JSON Support: Export system configurations easily using standard JSON flags.

Installation

You can run kyro directly using npx (without installing it globally):

npx kyro doctor

Or install it globally:

npm install -g kyro
# or via yarn
yarn global add kyro
# or via pnpm
pnpm add -g kyro

Usage

Run the CLI using the binary command kyro:

kyro <command> [options]

Commands

1. kyro doctor

Runs comprehensive checks for your local environment (Node, Package Managers, Java, Android, iOS on macOS) and project folder configuration (detects react-native dependency, version, and platform folders ios/android).

2. kyro info

Outputs detailed information about your system and local configuration.

Options:

• --json: Outputs details in standardized JSON format.

3. kyro explain

Analyzes the React Native project and environment configurations, executing diagnostic rules to explain why things are failing, what is impacted (symptoms), and how to resolve them. It also calculates a Project Health Score (0-100).

Options:

• --json: Outputs the score and diagnostics list in JSON format.

4. kyro repair

Automatically detects and safely fixes common configuration issues, out-of-sync dependencies, and build caches.

Options:

• --dry-run: Show what issues would be repaired without applying changes.
• --json: Output repair execution results in JSON format.
• --yes: Automatically execute all repairs without interactive confirmation prompts.

5. kyro sync [platform]

Ensures all project dependencies and native configurations are synchronized correctly (package managers installation, ios pod install on macOS, Android gradle wrapper and local.properties setup, post-sync diagnostics validation).

Options:

• --dry-run: Show planned tasks without running them.
• --json: Output synchronization task execution results in JSON format.
• --verbose: Print verbose logs, timings, command stdout, and command stderr.

6. kyro install <package>

Intelligently installs a React Native library, runs required platform synchronizations, and prints custom native configuration setup guidance and next-steps recommendations.

Options:

• --dry-run: Simulate the installation planning and native validation checks.
• --json: Output installation report details in JSON format.
• --verbose: Print detailed installation command subprocess logs.
• --dev: Save the package as a development dependency.

7. kyro analyze

Performs a deep project analysis, scanning total dependencies, native modules, version mismatches, missing peer dependencies, and known package configuration warnings. Generates an overall Project Health Score from 0 to 100.

Options:

• --json: Output analysis metrics and warnings list in JSON format.

8. kyro prebuild [platform]

Generates native project directories (ios/ and android/) using a strategy-based generation pattern. For Expo Managed projects, it runs expo prebuild via the task runner. For React Native CLI projects, it bootstraps a clean minimal native configuration skeleton.

Options:

• --dry-run: Show planned prebuild actions without executing them.
• --json: Output prebuild results in JSON format.
• --force: Force regeneration of native directories even if they already exist (requires confirmation).

9. kyro run [platform]

Builds, installs, and runs the application in development/debug mode.

• Resolves target platforms (Android/iOS) interactively or defaults to Android on Windows/Linux.
• Detects and prompts to auto-install missing expo-dev-client packages.
• Features Port Conflict Auto-Resolver (verifies port 8081 and prompts to kill blocking processes).
• Sets up ADB Port Reversing with Auto-Recovery (clears stale forwards, restarts local adb daemon on failure).
• Launches Metro bundler hands-free using the auto-start --android/--ios flags.
• Displays iOS provisioning profile wizards and Keychain certificates selection.

Options:

• --mode <mode>: Run mode (debug or release).
• --device <device>: Connected device ID or simulator name.
• --scheme <scheme>: Xcode scheme to compile (iOS only).

10. kyro build [platform]

Builds native application binaries.

• Prompts for target build type (apk or aab on Android).
• Renames and copies compiled artifacts to the project's root folder under android-build/ using app name metadata: {app-name}-{build-variant}-{version-name}-({version-code}).apk/aab.
• Runs Keystore Generation Wizard on Release builds if signing keys are missing.
• Automatically detects project configuration type (Groovy/Kotlin DSL) to display precise build.gradle copy instructions.
• Includes Auto-Uninstall Recovery Wizard: on signature mismatch conflicts, offers to wipe older builds across all user profiles (pm uninstall --user all) and retries.
• Prompts for optional local device deployment post-build.

Options:

• --mode <mode>: Build mode (debug or release).
• --type <type>: Build artifact type (apk or aab).
• --device <device>: Device ID to deploy to.
• --install / --no-install: Enable/Disable automatic device installation.

Supported Project Types

kyro automatically detects your project configuration layout and selects the matching prebuilding strategy:

• React Native CLI (react-native-cli)
  • Indicators: react-native dependency is present, and expo is absent.
  • Behavior: Prompts or generates minimal native skeleton templates (ios with basic Podfile and xcodeproj, android with gradle files) to satisfy native verification checks.
• Expo Managed (expo-managed)
  • Indicators: expo dependency is present, ios and android directories are missing, and at least one of app.json, app.config.js, or app.config.ts exists.
  • Behavior: Spawns npx expo prebuild through the sequential task runner to scaffold native codebases, then synchronizes package manager dependencies.
• Expo Bare (expo-bare)
  • Indicators: expo dependency is present, and native ios/ and android/ folders already exist in the project root.
  • Behavior: Native codebases are already present. The tool will display a message and skip generation unless --force is supplied.

Examples

kyro doctor

kyro doctor

Output:

React Native Health Report

Environment
  ✓ Node.js                        24.15.0
  ✓ npm                            11.12.1
  ⚠ yarn                           Not found
  ⚠ pnpm                           Not found
  ✓ Java SDK                       v21
  ✓ Java Compiler (javac)          v21.0.11
  ✓ ANDROID_HOME                   /Users/sanjay/Library/Android/sdk
  ✓ ANDROID_SDK_ROOT               Not set (optional)
  ✓ Android adb tool               v1.0.41
  ✓ Xcode                          v26.5
  ✓ CocoaPods (pod)                v1.16.2

Project
  ✓ React Native                   0.72.4
  ✓ ios                            Exists
  ✓ android                        Exists

Summary
Passed:   12
Warnings: 2
Errors:   0

kyro info

kyro info

Output:

System Information
  OS:          darwin (arm64)
  CPU:         Apple M1 Pro

Binaries
  Node.js:     24.15.0
  Java:        21

Project Configuration
  React Native: 0.72.4

kyro info --json

kyro info --json

Output:

{
  "os": {
    "platform": "darwin",
    "arch": "arm64"
  },
  "node": {
    "version": "24.15.0"
  },
  "java": {
    "version": "21"
  },
  "reactNative": {
    "version": "0.72.4"
  }
}

kyro explain

kyro explain

Output:

React Native Project Health Diagnostics

Health Score: 60/100

Potential Problems Detected

1. [Error] React Native Not Detected

Detected:
  package.json exists, but 'react-native' is missing from dependencies and devDependencies.

Why this matters:
  The core React Native dependency is missing. This project cannot build or run as a React Native application.

Likely symptoms:
  * npm/yarn/pnpm run commands for iOS and Android fail to execute
  * React Native CLI features are unavailable

Suggested fix:
  * Verify you are in the correct repository folder.
  * Install the react-native package by running 'npm install react-native'.

Documentation:
  https://reactnative.dev/docs/environment-setup

────────────────────────────────────────────────────────────

2. [Warning] Missing iOS Directory

Detected:
  The 'ios' directory is missing in the project root.

Why this matters:
  The 'ios' directory contains native Xcode project and workspace configurations. Without it, you cannot build a native iOS application locally.

Likely symptoms:
  * Cannot compile or execute iOS native builds using Xcode or CLI

Suggested fix:
  * If using Expo: This is expected in a managed workflow. Run 'npx expo prebuild' to generate native folders when ejecting or preparing for native builds.
  * If standard React Native: Re-checkout the directory from version control (e.g. git checkout) or re-run initialization template files.

Documentation:
  https://reactnative.dev/docs/environment-setup

────────────────────────────────────────────────────────────

kyro explain --json

kyro explain --json

Output:

{
  "score": 60,
  "diagnostics": [
    {
      "id": "react-native-missing",
      "title": "React Native Not Detected",
      "severity": "error",
      "detected": "package.json exists, but 'react-native' is missing from dependencies and devDependencies.",
      "explanation": "The core React Native dependency is missing. This project cannot build or run as a React Native application.",
      "symptoms": [
        "npm/yarn/pnpm run commands for iOS and Android fail to execute",
        "React Native CLI features are unavailable"
      ],
      "fixes": [
        "Verify you are in the correct repository folder.",
        "Install the react-native package by running 'npm install react-native'."
      ],
      "documentationUrl": "https://reactnative.dev/docs/environment-setup"
    }
  ]
}

kyro repair --dry-run

kyro repair --dry-run

Output:

Planned Repairs

  ✓ Clean Metro Cache (Safe)
    Clears Metro bundler cache by deleting local package caches and temp directories.
  ✓ Clean Xcode Derived Data (Requires confirmation)
    Cleans Xcode DerivedData caches on macOS to solve indexing or linker issues.

No changes were made. (Dry run)

kyro repair

kyro repair

Output:

React Native Repair

Repairs Executed
  ✓ Clean Metro Cache completed
    Cleared Metro caches (cleaned 2 files/directories).
  ✓ Clean Xcode Derived Data completed
    Xcode DerivedData cleaned successfully.

Summary
Successful Repairs: 2
Failed Repairs:     0

kyro sync --dry-run

kyro sync --dry-run

Output:

Planned Tasks

  ✓ pnpm install
  ✓ Validate package installation
  ✓ pod install
  ✓ Android validation
  ✓ Native dependency audit
  ✓ Post-sync project validation

No actions executed. (Dry run)

kyro sync

kyro sync

Output:

React Native Sync

  ✓ Package Manager: pnpm

Running Tasks

  ✓ pnpm install
  ✓ Validate package installation
  ✓ pod install
  ✓ Android validation
  ✓ Native dependency audit
  ✓ Post-sync project validation

Summary

Tasks completed: 6
Warnings:        1
Errors:          0

Total time:      8.2s

kyro install --dry-run

kyro install react-native-maps --dry-run

Output:

Planned Actions

  ✓ Install package
  ✓ Synchronize native dependencies
  ✓ Validate project

No changes executed. (Dry run)

kyro install

kyro install react-native-maps

Output:

Package Installed
  react-native-maps (v1.7.1)

Synchronization
  ✓ Dependencies installed via pnpm
  ✓ Pods synchronized successfully
  ✓ Android validated successfully

Additional Setup Required
iOS
  * Configure Google Maps SDK configuration in AppDelegate (GMSServices API Key setup).
  * Add NSLocationWhenInUseUsageDescription inside ios/Info.plist for map location features.
Android
  * Configure Google Maps API key in android/app/src/main/AndroidManifest.xml using a <meta-data> tag.

Documentation
  https://github.com/react-native-maps/react-native-maps/blob/master/docs/installation.md

Recommended Next Steps
  1. Add Google Maps API key inside your android/AndroidManifest.xml.
  2. Add Google Maps SDK GMSServices API Key inside ios/AppDelegate.
  3. Run 'kyro doctor' or 'kyro explain' to verify project configuration health.

kyro analyze

kyro analyze

Output:

Project Analysis

React Native   0.82.1
Dependencies   83
Native Modules 14

Warnings
  ⚠ react-native-maps may require iOS 15+
  ⚠ react-native-reanimated Babel plugin not detected
  ⚠ Firebase package requires native configuration

Project Health Score 70/100

kyro analyze --json

kyro analyze --json

Output:

{
  "reactNativeVersion": "0.82.1",
  "totalDependencies": 83,
  "nativeModulesCount": 14,
  "nativeModules": [
    "react-native-maps",
    "react-native-reanimated",
    "@react-native-firebase/app"
  ],
  "healthScore": 70,
  "warnings": [
    {
      "id": "maps-ios-target",
      "text": "react-native-maps may require iOS 15+"
    },
    {
      "id": "reanimated-babel-plugin",
      "text": "react-native-reanimated Babel plugin not detected"
    },
    {
      "id": "firebase-config-missing",
      "text": "Firebase package requires native configuration"
    }
  ],
  "errors": []
}

kyro prebuild (Expo Managed workflow example)

kyro prebuild

Output:

React Native Prebuild

Detected Project
  expo-managed

Strategy
  Expo Prebuild

Tasks
  ✓ Running expo prebuild (12.4s)
  ✓ Synchronize dependencies (1.5s)
  ✓ Validate project (0.8s)

Summary
Tasks completed: 3
Warnings:        0
Errors:          0
Total time:      14.7s

kyro prebuild --dry-run

kyro prebuild --dry-run

Output:

React Native Prebuild

Detected Project
  expo-managed

Strategy
  Expo Prebuild

Planned Actions:
  ✓ Run expo prebuild
  ✓ Synchronize dependencies
  ✓ Validate project

No actions executed. (Dry run)

kyro sync prebuild integration prompt

kyro sync

Output:

Expo Managed project detected. Native projects have not been generated. Generate native projects now using Expo Prebuild?
Select option (1-2):
  1. Yes
  2. No

Known Packages Intelligence

The kyro install command includes built-in integration intelligence for:

• react-native-maps: Guides API keys set up in Manifest and GMSServices in iOS AppDelegate.
• react-native-firebase (including scoped packages): Guides downloading and placing plist/json config files.
• react-native-reanimated: Reminds users to add the Babel worklets compiler plugin to configurations.
• react-native-vision-camera: Guides plist description permission strings and Manifest Camera requirements.
• react-native-mmkv: Summarizes native JSI compilation details.
• react-native-webview: Highlights AndroidX compatibility requirements.

Safety Guarantees

The kyro repair, kyro sync, and kyro install commands are built with safety as a core principle. They will never:

• Delete custom application source files.
• Delete or replace package.json files.
• Modify application source logic automatically.
• Edit App.tsx, Info.plist, AndroidManifest.xml, or app.json files.
• Execute hazardous or unverified shell commands.
• Modify system settings or require administrative/sudo privileges.

All changes that involve building, cleaning native caches, or installing dependencies will prompt for confirmation unless --yes is supplied.

Limitations

• No Auto-Code-Modification: The command does not edit your code automatically to inject import lines or configuration tags. All integrations must be completed manually following the printed report.
• No Global Installations: It will not download global native runtimes (Java SDK, Node, Xcode, Android Studio) on the host computer.

Development

To set up the project locally for development:

1. Clone the repository:

   git clone https://github.com/your-username/kyro.git
   cd kyro

2. Install dependencies:

   bun install
   # or
   npm install

3. Run local dev mode:

   npm run dev doctor
   # or
   npm run dev info

4. Build the production bundle:

   npm run build

   This generates the compiled ESM output in the dist/ directory.

5. Run test suite: We use Vitest for testing:

   npm run test

Roadmap

• v0.2.x:
  • Check for Watchman presence.
  • Check CocoaPods lockfile installation state.
  • Improve SDK version detection details for Android API levels.
• v0.3.x:
  • Add deep dependency integrity validation (detect conflicting transitive dependencies).
  • Integrate React Native Doctor checks into CI/CD pipelines.

CI/CD Integration (v0.12.0)

kyro is a first-class CI/CD quality gate.

CI Mode

Run analysis in CI mode — no colors, no spinners, no interactive prompts, deterministic output:

kyro analyze --ci

Output:

=== React Native Project Analysis ===
status:       PASS
score:        92/100
errors:       0
warnings:     1
infos:        0
issueCount:   1
reason:       Score 92/100 meets threshold. No blocking issues found.
generatedAt:  2024-06-01T12:00:00.000Z

--- Issues ---
[WARN] [react-native-reanimated] react-native-reanimated Babel plugin not detected
  -> Add 'react-native-reanimated/plugin' to babel.config.js

=== End of Report ===

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success — all thresholds passed | | 1 | Critical errors found | | 2 | Warning threshold exceeded | | 3 | Invalid project configuration | | 4 | Internal runtime error |

Configuration

Create .kyro/config.json in your project root:

{
  "scoreThreshold": 70,
  "maxWarnings": 20,
  "failOnError": true
}

If the file is absent, defaults are used.

JSON Report Export

Write a full CiReport to a file:

kyro analyze --json-output reports/kyro-report.json

The parent directory is created automatically if missing.

SARIF Report

Generate a SARIF v2.1.0 report for GitHub Code Scanning:

kyro analyze --sarif
# Writes: kyro-analysis.sarif

Upload to GitHub Code Scanning:

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: kyro-analysis.sarif

Baseline Support

Generate a Baseline

Capture all current issues as the "known baseline" to suppress them in future runs:

kyro analyze --baseline
# Writes: .kyro/baseline.json

Commit baseline.json to your repository.

CI Runs with Baseline Filtering

In --ci mode, if baseline.json exists, only newly introduced issues trigger failures:

kyro analyze --ci
# [INFO] Baseline active: 3 pre-existing issue(s) suppressed.
# status: PASS

This workflow lets you adopt kyro in existing projects without needing to fix all pre-existing issues before CI can pass.

GitHub Actions Examples

Basic Quality Gate

name: React Native Quality Gate
on: [push, pull_request]

jobs:
  kyro-analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install kyro
        run: npm install -g kyro

      - name: Run RN Analysis
        run: kyro analyze --ci

With SARIF Code Scanning

name: React Native Code Scanning
on: [push, pull_request]

jobs:
  kyro-analyze:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install kyro
        run: npm install -g kyro

      - name: Analyze with SARIF
        run: kyro analyze --ci --sarif
        continue-on-error: true

      - name: Upload SARIF to GitHub
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: kyro-analysis.sarif

With JSON Report Artifact

- name: Run RN Analysis
  run: kyro analyze --ci --json-output reports/kyro-report.json
  continue-on-error: true

- name: Upload Report
  uses: actions/upload-artifact@v4
  with:
    name: kyro-analysis-report
    path: reports/kyro-report.json

Full Pipeline with Baseline

- name: Analyze (baseline-filtered)
  run: kyro analyze --ci --sarif --json-output reports/kyro-report.json

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  if: always()
  with:
    sarif_file: kyro-analysis.sarif

- name: Upload JSON report
  uses: actions/upload-artifact@v4
  if: always()
  with:
    name: kyro-analysis-report
    path: reports/kyro-report.json

Baseline Workflow (Recommended Adoption Path)

For existing projects with many pre-existing issues:

Step 1: Generate a baseline locally

kyro analyze --baseline
git add .kyro/baseline.json
git commit -m "chore: add kyro baseline"

Step 2: Configure thresholds

mkdir -p .kyro
cat > .kyro/config.json << 'EOF'
{
  "scoreThreshold": 60,
  "maxWarnings": 30,
  "failOnError": true
}
EOF
git add .kyro/config.json
git commit -m "chore: add kyro config"

Step 3: Add CI job — only new issues break the build

- name: RN Quality Gate
  run: kyro analyze --ci

Step 4: Gradually tighten thresholds as you fix issues.

CiReport Schema

{
  "status": "pass | fail",
  "score": 92,
  "errors": 0,
  "warnings": 1,
  "infos": 0,
  "issueCount": 1,
  "issues": [
    {
      "packageName": "react-native-reanimated",
      "severity": "warning",
      "message": "Babel plugin not detected",
      "recommendation": "Add reanimated plugin to babel.config.js"
    }
  ],
  "generatedAt": "2024-06-01T12:00:00.000Z"
}