# Local native capture and packaging

Preview: not generally available yet.

Debug a native story locally before sending a build to hosted capture.

## Local prerequisites
Install the native uploader described in [native CI](/native-ci/). Local capture requires the appropriate development tools: Xcode and an installed simulator on macOS for iOS, or Android SDK tools and a suitable emulator for Android.

These local commands do not use Framecheck's hosted API. Your local runtime can render differently from the hosted device, so a local result is not a replacement for the project's CI check.

## Capture an Android app
```sh
node framecheck-native.mjs capture --platform android \
  --app ./app-framecheck.apk --app-id com.example.storybook \
  --serial emulator-5554 --out ./framecheck-local
```

Use your emulator's serial. If you want the CLI to select or start an AVD, use the supported `--avd NAME` option instead. The app still needs the native capture entry and bundled stories.

## Capture an iOS app
```sh
node framecheck-native.mjs capture --platform ios \
  --app ./YourApp.app --udid "$SIMULATOR_UDID" \
  --out ./framecheck-local
```

Supply the identifier of the simulator you intend to use. Its app must be a compatible simulator build.

## Filter and compare
`--only REGEX` limits capture to matching stories. `--baseline DIR` compares with a directory of reference captures. `--color-scheme light` or `dark` selects one appearance, and `--light-and-dark` requests both. Local capture exits nonzero if it finishes with errors or differences.

Keep output directories out of version control unless your team deliberately manages local screenshot references there.

## Attach to an existing development app
Instead of `--app`, use `--open-url URL --app-id ID` when the app is already installed and the URL loads your capture-mode bundle. This can support a development client during local debugging. Hosted capture still needs the standalone bundled app; it cannot connect to your laptop's Metro server.

## Package without uploading
```sh
node framecheck-native.mjs pack --platform ios \
  --app ./YourApp.app --out ./framecheck-ios.tgz
```

Use `--platform android` and an APK for Android. Packaging validates the app format and architecture. `--app-id` supplies an explicit identifier if it cannot be read from the build. Do not assume the `upload --app` option accepts an arbitrary archive: the documented hosted upload input is the app/APK and it packages that input for you.