Command Line Interface (CLI)

The Command Line Interface is the primary interface for Pear Development.

Install & upgrade

The fastest way to install Pear is the installer at install.pears.com—it also works via npx if you'd rather go through npm:

curl https://install.pears.com/pear.sh | sh

irm https://install.pears.com/pear.ps1 | iex

npx pear

docker run -it --rm tetherto/pear

This bootstraps Pear onto the system. Complete the setup by following the PATH instructions the installer prints, then run pear directly. To install it globally through npm instead, use npm i -g pear—and every pear <cmd> also works as npx pear <cmd>, which is handy for running commands from a directory other than the one you installed into. npm and Node.js are only the delivery mechanism: after install, pear runs on Bare, not Node.

The tetherto/pear Docker image runs Pear inside Ubuntu 24.04 with pear and pear-install ready to go—a low-risk way to try out Pear apps without installing anything on the host.

Moving from Pear v2 to v3

Run npx pear to move onto the v3 platform. From v3 on, the CLI is a standalone binary that keeps itself up to date over the air through Pear OTA—so you no longer reinstall from npm for platform updates. Several commands were removed in v3 (see the removed badges below); if your application relied on the removed pear run runtime or the global Pear API, follow Migrate from pear run to Pear OTA and review the Release Overview.

Scripting with --json

Most commands accept --json—use it for anything that parses a command's result. The default, human-readable output is meant for a person at a terminal and can change wording or formatting between releases; the JSON shape is the stable contract to script against.

--json output is newline-delimited JSON (NDJSON): one object per line, each shaped {"cmd", "tag", "data"}. Intermediate tags are command-specific—pear changelog --json tags each release "changelog", for example—so filter on tag rather than assuming a fixed number of lines.

Most commands close the stream with a tag: "final" object whose data carries success alongside any result fields, as pear touch --json does with {"success": true, "key": "…", "link": "pear://…"}. Two exceptions to code defensively around: some commands emit no final object at all—pear versions --json emits only its platform, runtimes, libraries, and modules tags—and some emit a bare final with no data, as pear multisig keys list --json does. Treat a missing success as "no status reported" rather than as failure.

For commands that take a subcommand, where you put --json matters—and it is not the same for all of them, because each command declares the flag at a different level of its tree:

The wrong position is rejected with ✖ Unrecognized Flag: --json, so a script that guesses will fail loudly rather than silently emit human-readable text.

Building and staging

Generate a link, assemble a deployment folder, and sync it to the network—in that order, since build and stage both need a link to work with.

pear touch [flags]

Creates a Pear link. Pear links hold a key, this is the basis for application discovery.

Default output is just the pear://<key> link on its own line—safe to capture directly in a script (LINK=$(pear touch)) without needing --json.

  --json              Newline delimited JSON output
  --vanity <vanity>   Generate a link starting with this z32 prefix
  --help|-h           Show help

pear build [flags]

Create a project deployment folder.

Assembles per-OS electron-forge makes—one per target architecture—into the multi-architecture deployment directory that pear stage reads from disk: a package.json plus a by-arch/<platform-arch>/app/ tree.

Each make runs on its own OS, so transfer the per-platform outputs to one machine first, then pass each via its --<platform-arch>-app flag. Run pear build from outside the application source tree (or point --target at a sibling folder) so the deployment output is never re-staged into itself—see stage size increases. If you omit --target, the directory is auto-named <name>-<version> from package.json.

  --package [path]               Path to project package.json
  --target [path]                Target build dir
  --config [path]                Path to project pear.json (mandatory for mobile)
  --darwin-arm64-app [path]      Path to Mac ARM64 app
  --darwin-x64-app [path]        Path to Mac x64 app
  --linux-arm64-app [path]       Path to Linux ARM64 app
  --linux-x64-app [path]         Path to Linux x64 app
  --win32-x64-app [path]         Path to Windows x64 app
  --win32-arm64-app [path]       Path to Windows ARM64 app
  --ios-arm64 [path]             Path to iOS ARM64 folder (ota bundle and assets)
  --ios-arm64-simulator [path]   Path to iOS ARM64-Simulator folder (ota bundle and assets)
  --ios-x64-simulator [path]     Path to iOS x64-Simulator folder (ota bundle and assets)
  --android-arm64 [path]         Path to Android ARM64 folder (ota bundle and assets)
  --json                         Newline delimited JSON output
  --help|-h                      Show help

For the full release walkthrough, see Deploy a Pear desktop app and Build desktop distributables.

pear stage <link> [dir]

Synchronize local changes to pear hypercores.

To generate a link, see pear touch.

Pear links hold a key, this is the basis for application discovery.

Outputs diff information and project link.

Each time new changes are staged, the length will increase. This change can be replicated to any peer who know the link and is connected. If they run pear info <link>, they will see the length update even if the application is not being seeded. Connections can potentially linger after seeding an application but will eventually close.

  --dry-run|-d       Execute a stage without writing
  --ignore <paths>   Don't stage these comma-separated paths
  --purge            Also delete already-staged files that now match the ignore list
  --only <paths>     Only stage these comma-separated paths
  --truncate <n>     Advanced. Truncate the project to this version length. Destructive — later versions are dropped
  --json             Newline delimited JSON output
  --help|-h          Show help

--ignore supports glob patterns (*, **) and a leading ! to un-ignore. --only does not—it matches by exact path or directory prefix. Both add to rather than replace the corresponding list in pear.json, and --purge also switches on automatically when pear.json sets stage.purge.

<dir> defaults to the directory you run the command from. If that directory has no package.json, Pear searches upward through its parents for one. Passing a versioned verlink as <link> is accepted, but only its key is used—staging always targets the current head and ignores the version segment. --truncate's n is the length segment of a verlink (pear://<fork>.<length>.<key>).

Production releases

Advance a staged build to a quorum-signed production release, replacing the single-key pear release command removed in v3.

pear provision <source-verlink> <target-link> <production-verlink>

Pre-production block sync.

Synchronizes blocks from a source link to a pre-production target link. The target can then be multi-signed against a production link. Use pear touch to generate the target link first.

Arguments:
  <source-verlink>       Versioned source link
  <target-link>          Target link to sync to, as generated by pear touch
  <production-verlink>   Versioned production link to sync against

Flags:
  --dry-run|-d           Execute provision to a disposable target
  --json                 Newline delimited JSON output
  --help|-h              Show help

Both <source-verlink> and <production-verlink> must carry a version—pear://<fork>.<length>.<key>. A bare link is rejected, because it resolves to the latest content instead of pinning one version.

pear multisig [command]

Production signing coordination. Gate production releases behind a quorum of signing keys instead of a single machine's key. Since Pear v3 removed the single-key pear release command, quorum multisig (together with pear provision) is the path to production. See Set up multisig and Sign with multisig for the end-to-end flow.

  --config [./pear.json]                 Path to the project's pear.json. Defaults to ./pear.json
  --peer-update-timeout <milliseconds>   How long to wait for peers to update, in milliseconds
  --force                                Skip sanity checks (request)
  --vanity <vanity>                      Generate a link starting with this z32 prefix (link)
  --json                                 Newline delimited JSON output
  --help|-h                              Show help

--config points at a file that must carry a multisig field with publicKeys, quorum, and namespace—see Pear Application Configuration.

--peer-update-timeout defaults to 5000 milliseconds and only matters when --force is not set: it bounds the pre-commit checks that --force skips entirely. The wait for remote seeders after a commit takes no timeout at all and can block indefinitely—on any commit, not just the first—with Ctrl-C the only way out. --force skips verifying that the source drive's db and blobs cores are reachable and fully seeded at the requested version; without it, that step can block or fail when the source is poorly seeded.

sign's [name] selects the encrypted private key file created by keys get <name>, and signing prompts for the exact password used when that key was generated—there is no recovery if it is forgotten.

A key <name> must match ^[\w-]+$—letters, numbers, hyphens, and underscores only. keys add's <public-key> must be z32-encoded, the same format keys get prints, whether passed as a literal string or as a path to a file holding one; passing the private key as a path keeps it out of shell history. keys paths prints its paths unconditionally and never checks that a key by that name was created. keys remove deletes both the public key file and, when present, the private key file.

pear release <link> [dir]

Deprecated in Pear v2.6.5, removed as of Pear v3.

The single-key release pointer has been replaced by quorum-based production releases. Use pear provision to block-sync a pre-production target and pear multisig to cosign it onto a production link.

Distributing and running apps

Seed a link so peers can fetch it, then install the app it points to. pear run launched an app directly from a link in v2; apps now embed Pear OTA instead.

pear seed <link>

Announce a project link on the network and serve its blocks to peers. Runs until you exit, or until every --until-sync peer has fully synced.

Seeding will sparsely replicate the application. This means the entire history of the link is available, but most likely only the most recent version will be replicated.

  --no-tty                          Print plain log lines instead of the live terminal UI
  --until-sync <key>                Exit once this peer has synced. Pass multiple flags to wait for more peers
  --stats-interval <milliseconds>   Stats refresh interval in milliseconds
  --json                            Newline delimited JSON output
  --help|-h                         Show help

<link> accepts a versioned verlink, but only its key is used—pear seed always replicates the full, latest history and is never pinned to that version. --stats-interval defaults to 500 milliseconds with the live UI on, or 3000 milliseconds under --no-tty.

New in 3.2.0 --until-sync <key> takes a peer's public key (z32) and exits automatically once every specified peer has fully synced—pass the flag multiple times to wait for more than one peer. Useful for scripting a seed session that should end on its own instead of running indefinitely. The live view lists Seeding, Drive Key, Drive Length, Discovery Key, Content Key, Firewalled, NAT Type, Whoami and Network above an unlabelled log; the key to pass here is the one printed after each peer join or peer sync line.

pear install <link>

Install a Pear application—or the Pear platform itself—from a pear:// link.

pear install pear://<key> installs any application built with pear build, pulling it from the swarm and wiring it up locally so it can be launched and kept up to date over the air. It works for both applications and binaries. Installs go directly into the OS application folder.

  --only <paths>          Advanced. Filter by app filenames
  --timeout <seconds>     Advanced. Override network timeout (30s)
  --to <dir>              Advanced. Override install target directory
  --dht-bootstrap <nodes> Advanced. Custom DHT bootstrap
  --json                  Newline delimited JSON output
  --help|-h               Show help

pear install pear://<key>

pear run [flags] <link|dir> [...app-args]

Deprecated in Pear v2.6.5, removed as of Pear v3.

Running pear run now exits with:

pear run has been removed.
Use the pear-runtime module instead: https://www.npmjs.com/package/pear-runtime

Applications are now launched by embedding the Pear OTA (pear-runtime) library, which provides over-the-air peer-to-peer updates, application storage, and Bare workers. See Migrate from pear run to Pear OTA for the move.

Inspecting apps and links

Read-only lookups against a project, an installed app, or the local platform state—none of these write anything.

pear changelog [link]

View project changelog

Supply a link to view an application's changelog, read from the CHANGELOG.md at its drive root. Any Pear app can ship one—see Publish a changelog for your app for the file format and how to stage it.

Shows the Pear platform changelog by default (no link).

  --max|-m <n=10>    Maximum number of entries to show
  --of <semver=^*>   Only show entries matching this semver range. Default: latest major
  --full             Show entire changelog
  --json             Newline delimited JSON output
  --help|-h          Show help

CHANGELOG.md must open with a header line (typically a # Title) followed by one release per ## <version> heading, newest first, where the first space-separated token of each heading is a SemVer version (a leading v is stripped). --of filters by that version, defaulting to the latest major; --full shows every entry. The parser is the pear-changelog module. To fetch the raw file instead, use pear dump pear://<key>/CHANGELOG.md.

pear info [link] [dir]

Read project information. [dir] currently has no effect—pear info never reads it; it inspects the given link, or platform information when no link is given.

Supply a link to view application information.

Supply no argument to view platform information.

  --metadata       Print the project metadata
  --manifest       Print the app manifest
  --multisig       Print the multisig quorum and signing keys
  --key            Print the view key
  --json           Newline delimited JSON output
  --help|-h        Show help

--key, --metadata, and --multisig select sections: name any of them and only those print, in the order key, metadata, multisig. --manifest is not a selector—it prints the manifest and stops, so pairing it with --metadata or --multisig yields the manifest alone, and pairing it with --key still prints the key above it.

With --json, output arrives as three tagged objects before the closing final:

Filter on "tag": "info" for the manifest values and "tag": "keys" for the key triplet, rather than relying on ordering. verlink is the versioned pear://<fork>.<length>.<key> form and was added in 3.1.0.

pear dump [flags] <link> [dir]

Synchronize files from a link to a directory.

<link> can contain a path portion to dump a subset of the files for the Pear application. For example, to dump only the CHANGELOG.md from an application into a dump-dir directory run:

pear dump pear://<key>/CHANGELOG.md dump-dir/

  --dry-run|-d     Preview without writing any changes
  --checkout <n>   Dump the project as it was at this version length
  --only <paths>   Only dump these comma-separated paths
  --force|-f       Force overwrite existing files
  --list           List the paths inside the link instead of writing any files
  --no-prune       Keep destination files that are missing from the source
  --json           Newline delimited JSON output
  --help|-h        Show help

Pruning is on unless --no-prune is set, so a plain dump deletes anything in <dir> that is not at <link>. --only does not turn that off: paths it matches are still deleted from <dir> when they no longer exist at <link>. Add --no-prune alongside it to filter without removing anything. New in 3.3.0 On 3.2.0 and earlier this flag's help text claimed it implied --no-prune.

--force only matters when <dir> already holds files; an empty or not-yet-created <dir> never needs it. --dry-run and --no-prune have no effect when <dir> is - or --list is set—those modes only read and print, so there is nothing to skip writing or to delete. --checkout's n is the length segment of a verlink (pear://<fork>.<length>.<key>).

myapp [core]  pear://<key> (length: 42, writable)
myapp [blobs] pear://<key> (length: 118, writable)
-     [core]  pear://<key> (length: 7)
Total cores: 3 | Writable: 2

  --all-cores   List all cores, including empty cores
  --json        Newline delimited JSON output
  --help|-h     Show help

pear data [flags] [command]

Explore the platform database.

The database contains metadata stored on this device used by the Pear runtime.

--json      Newline delimited JSON output
--help|-h   Show help

Platform maintenance and diagnostics

Manage the background sidecar process, reclaim disk space, and check what's installed.

pear sidecar [command]

The Pear Sidecar is a local-running IPC server for corestore access.

This command instructs any existing sidecar process to shutdown and then becomes the sidecar.

  --log-level <level>   Verbosity to log at — 0=off, 1=error, 2=info, or 3=trace
  --help|-h             Show help

--log-level accepts either a number (0–3) or a name (OFF, ERR, INF, TRC, matched case-insensitively, so inf works too); it defaults to INF.

pear gc [flags] [command]

Perform garbage collection and remove unused resources.

A core is a single append-only log in Pear's local corestore. pear gc cores deletes the blocks one core has stored on disk, freeing that space; the core itself stays in the corestore. It clears the link's metadata core first, then that core's content core if the first one cleared.

  --force|-f    Clear writable cores without confirmation
  --json        Newline delimited JSON output
  --help|-h     Show help

⚠️  WARNING one or more cores of <link|name> are writable, clearing them cannot be undone. To confirm type "CLEAR"
Clear <link|name> cores? 

pear versions

Output version information.

--modules|-m   Include module versions
--json         Newline delimited JSON output
--help|-h      Show help

--modules lists every package in Pear's own bundled dependencies (bare-*, hypercore-*, corestore, and so on)—not the dependencies of your project.

pear help [command]

View help for a command. With no argument, prints the full command overview.

Relatedly, running pear -v (no command) prints platform version information: the platform key as a versioned pear://<fork>.<length>.<key> link where available, plus the SemVer—or the dev root path on development installs. pear -v does not itself accept --json; for the machine-readable equivalent use pear versions --json instead.

Removed without a direct replacement

These four have no successor command—each is now rejected as an unrecognized command or argument rather than printing removal guidance.

pear presets [flags] [command]

Deprecated in Pear v2.6.5, removed as of Pear v3.

Per-command default flags are no longer configurable through the CLI.

pear shift [flags] <source> <destination>

Deprecated in Pear v2.6.5, removed as of Pear v3.

Moving user application storage between applications is no longer supported from the CLI.

pear drop [flags] [command]

Deprecated in Pear v2.6.5, removed as of Pear v3.

pear drop was tied to the removed pear run model. See Manage installed applications for resetting application storage.

pear init

pear init has been removed from the Pear CLI. Unlike pear run (which prints a dedicated removal message), init is no longer a recognized command, so it is rejected as an unknown argument—✖ Unrecognized Argument at index 0 with value init, followed by the top-level usage.

See also

• Release Overview—the curated record of the v3 command removals and other module changes.
• Manage installed applications—resetting and inspecting installed apps.
• Distribute as a binary—packaging a release built from these commands.
• Pear OTA reference—the pear-runtime library that replaces pear run.