JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 42
  • Score
    100M100P100Q85845F
  • License MIT

Reusable iOS CLI for listing devices and building/running Xcode projects

Package Exports

    This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@rabithua/xcdev) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

    Readme

    xcdev

    A publishable npm CLI for:

    • listing simulators and connected real devices
    • building iOS projects with profiles
    • running apps on simulator or real device

    Prerequisites

    • OS: macOS
    • Node.js: >= 18
    • Xcode: 15 or higher (relies on xcodebuild, xcrun simctl, xcrun xctrace, and xcrun devicectl).
    • Project: A valid iOS project (.xcodeproj or .xcworkspace) with a buildable scheme.

    Install

    npm install -g @rabithua/xcdev

    Commands

    The xcdev CLI offers the following commands for managing devices and building/running your iOS project.

    Listing Devices and Profiles

    • xcdev list devices: Lists all available simulator and connected real devices.
    • xcdev list devices sim: Lists only the available iOS simulators.
    • xcdev list devices real: Lists only the currently connected real iOS devices.
    • xcdev list profiles: Displays all the device profiles (e.g., specific simulators or real devices) that you have defined or are available as defaults.

    Setting Default Targets

    You can assign a specific device name or pattern to your default sim and real profiles. This is useful for quickly targeting a preferred device.

    • xcdev set sim "iPhone Air": Sets the default simulator profile target to a simulator named "iPhone Air".
    • xcdev set real "Huawei Air": Sets the default real device profile target to a connected device matching "Huawei Air".

    Building the Project

    Builds the project for the specified profile without installing or running it.

    • xcdev build sim: Compiles the project targeting the default simulator.
    • xcdev build real: Compiles the project targeting the default connected real device.

    Running the Project

    Builds (if necessary), installs, and launches the app on the target device.

    • xcdev run sim: Runs your application on the default simulator. By default, it boots the simulator and opens Simulator.app for the selected device.
    • xcdev run real: Runs your application on the default real device.

    Use xcdev run --no-open-simulator sim if you want to keep the simulator app hidden while still running on the booted device.

    (Note: sim and real are recommended default profile names. Any custom profile name, such as office-phone, can be used if defined in .xcdev.env.)

    sim / real are recommended default profiles. Any profile name (such as air, office-phone) is user-defined in .xcdev.env. If real target is not set, xcdev uses the first connected real device.

    Project Config

    The CLI auto-discovers .xcdev.env by searching upward from current directory. If no config is found, it still works with auto-detected project/scheme and default profiles.

    Create .xcdev.env in the project root if you want stable project-specific settings. You can start from:

    templates/.xcdev.env.example

    Required keys:

    • IOS_PROJECT
    • IOS_SCHEME

    Common optional keys:

    • IOS_CONFIGURATION
    • IOS_BUNDLE_ID
    • IOS_PROFILE_<NAME>_MODE
    • IOS_PROFILE_<NAME>_TARGET
    • IOS_OPEN_SIMULATOR (YES by default; set to NO to avoid opening Simulator.app during run)

    Example:

    IOS_PROFILE_SIM_MODE="sim"
IOS_PROFILE_SIM_TARGET="iPhone"

IOS_PROFILE_REAL_MODE="real"
IOS_PROFILE_REAL_TARGET=".*"