# Migrate from pear run to Pear OTA





<Callout type="warn">
  **`pear run` was removed in Pear v3**, along with the ambient global `Pear` API. An unmigrated app is at its end of life—running `pear run` now exits with an error. Migrate onto **[Pear OTA](/pear/reference/pear/runtime)** (the `pear-runtime` library) to restore updates.
</Callout>

Pear has evolved from a runtime baked into the [Pear CLI](/pear/reference/pear/cli) (`pear run`) into an embeddable runtime library, **[Pear OTA](/pear/reference/pear/runtime)** (the `pear-runtime` module), that integrates into any JavaScript environment. The CLI keeps the deployment commands (`pear stage`, `pear build`, `pear provision`, `pear multisig`); the runtime moves into your own process. This exposes peer-to-peer over-the-air updates and Bare workers to any JS project instead of locking them behind the CLI runtime.

This page is the operator how-to for moving an existing v1 app across. To upgrade the CLI itself from v2, run `npx pear`—see [Install & upgrade](/pear/reference/pear/cli#install) in the CLI reference. For the background on why this changed, see [Runtime and languages](/pear/explanation/runtime-and-languages).

## Why this changed [#why-this-changed]

Running every app on a single vendor-signed Electron build made shipping trivial—no OS signing keys, no native compiling—but it turned out to be fragile. The same build served many apps, so it could not be tested against each one before an update; OS updates, virus scanners, and process managers did not expect the non-standard runtime; and Dock/Tray branding was glitchy (a restarted app could show the Pear icon). Splitting the runtime into a library lets the CLI focus on deployment and productionization while your app owns a standard, testable runtime.

## What changes [#what-changes]

| `pear run` (removed)                                                    | Pear OTA — `pear-runtime`                                                                                                                                         |
| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The CLI runtime launches the app and provides the ambient `Pear` global | You import [`pear-runtime`](/pear/reference/pear/runtime) in your own JS entrypoint                                                                               |
| `pear stage` deploys the app contents                                   | [`pear build`](/pear/how-to/operate-an-app/manual-deployment/deployment#4-build-the-deployment-directory) produces a build folder that *is* the deployment folder |
| `global.Pear.worker.run()` spawns workers                               | [`pear-runtime`](/pear/reference/pear/runtime)'s `run()` method (backed by `bare-sidecar`, which bundles the native Bare runtime)                                 |

## Steps [#steps]

<Steps>
  <Step>
    ### Start from the boilerplate [#start-from-the-boilerplate]

    The fastest migration is to scaffold a fresh Electron app that already has `pear-runtime` integrated, then move your code into it. Use the [`hello-pear-electron`](https://github.com/holepunchto/hello-pear-electron) boilerplate:

    ```bash skip="manual-walkthrough"
    git clone https://github.com/holepunchto/hello-pear-electron
    cd hello-pear-electron
    npm install
    npm start
    ```

    Move your HTML, JS, CSS, assets, and dependencies into the template's structure. For a guided tour of where each piece goes, see [Start from the hello-pear-electron template](/p2p/getting-started/from-a-template/start-from-hello-pear-electron).

    The build directory layout `pear-runtime` expects is produced by the [`pear build`](/pear/how-to/operate-an-app/manual-deployment/deployment#4-build-the-deployment-directory) command (Pear v2.5.0+). Your `package.json` needs an `upgrade` field set to the application's `pear://` link—see [Configuration](/pear/reference/pear/configuration#packagejson).
  </Step>

  <Step>
    ### Remove the global `Pear` API [#remove-the-global-pear-api]

    Any code using the `Pear` global must be removed and replaced. For Electron:

    | v1 global `Pear` API       | v2 replacement                                                                   |
    | -------------------------- | -------------------------------------------------------------------------------- |
    | `global.Pear.worker.run()` | [`pear-runtime`](/pear/reference/pear/runtime) `run()`                           |
    | `global.Pear.updates()`    | `pear.updater` `updating`/`updated` events                                       |
    | `global.Pear.exit()`       | `process.exit()`                                                                 |
    | `global.Pear.exitCode`     | `process.exitCode`                                                               |
    | `global.Pear.restart()`    | `app.relaunch()` (Electron)                                                      |
    | `global.Pear.teardown()`   | [`graceful-goodbye`](https://github.com/holepunchto/graceful-goodbye) or similar |
    | `global.Pear.app.args`     | `process.argv.slice(2)`                                                          |
    | `global.Pear.app.applink`  | `require('./package.json').upgrade`                                              |

    The remaining state on `global.Pear.app` (which supersedes the deprecated `global.Pear.config`) is either self-referential (no longer relevant) or link parsing—replace link parsing with direct deep-link protocol handling.
  </Step>

  <Step>
    ### Deploy with the production flow [#deploy-with-the-production-flow]

    `pear-runtime` pairs with the CLI's deployment commands rather than `pear run`. Use `pear stage` for internal previews, staging, and ephemeral variations—**not** for production. For production rigour, run `pear stage`, [`pear provision`](/pear/reference/pear/cli#pear-provision), and `pear multisig` in sequence:

    * [`pear provision`](/pear/reference/pear/cli#pear-provision) (Pear v2.6.0+) strips interim operations by block-syncing from a source drive, reducing the disk space an app needs. Use it to create a prerelease.
    * [`pear multisig`](/pear/reference/pear/cli#pear-multisig) manages cryptographic cosigning: define the signers, define the quorum, then sign against the prerelease.

    <Callout type="warn">
      Until you migrate to this deployment flow, you risk losing write access if something happens to the machine holding the key—with no way to recover, because there is no way to push an update that switches to a new application link. Unlike all other Pear application drives, a `pear multisig`'d drive is **not** machine-bound, which removes that single point of failure. Use `pear multisig` for any serious production sign-off.
    </Callout>

    See [Deploy your application](/pear/how-to/operate-an-app/manual-deployment/deployment) for the full step-by-step release flow.
  </Step>
</Steps>

## See also [#see-also]

* [`pear-runtime` reference](/pear/reference/pear/runtime)—the module that replaces the global `pear run` API.
* [Integrate Pear OTA into an existing Electron app](/pear/how-to/operate-an-app/integrate-pear-ota/electron)—once you've dropped `global.Pear`, this is the wiring itself.
* [Start from a template](/p2p/getting-started/from-a-template)—the desktop and terminal boilerplates to migrate into.
* [Deploy your application](/pear/how-to/operate-an-app/manual-deployment/deployment)—the stage → provision → multisig production flow.
* [Runtime and languages](/pear/explanation/runtime-and-languages)—why the runtime moved out of the CLI and into a library.
* [Configuration](/pear/reference/pear/configuration#packagejson)—where the `upgrade` link and entrypoint are declared.