Pear DocsCommand Line Interface (CLI)
Pear CLI: stage, seed, build, install, and day-to-day development commands.
The Command Line Interface is the primary interface for Pear Development.
This page tracks Pear 3.1.0. Several commands were removed in v3—most notably pear run, which is replaced by embedding the Pear OTA (pear-runtime) library. Removed commands are kept below with a badge and migration guidance.
Anything a release adds or removes carries an inline badge—New in 3.1.0 or Removed in 3.1.0—so you can tell whether your build has it. Run pear versions to check what you are on, and see the Release Overview for the full history.
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 | shirm https://install.pears.com/pear.ps1 | iexnpx peardocker run -it --rm tetherto/pearThis 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.
pear touch is the practical exception: its default output is already nothing but the bare pear://<key> link on its own line, so it's safe to consume directly without --json—for example LINK=$(pear touch).
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:
| Command | Position | Works | Rejected |
|---|---|---|---|
pear data, pear gc | before the subcommand | pear data --json dht | pear data dht --json |
pear multisig | after the subcommand | pear multisig keys list --json | pear multisig --json keys list |
The wrong position is rejected with ✖ Unrecognized Flag: --json, so a script that guesses will fail loudly rather than silently emit human-readable text.
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.
As of Pear v3, pear build is provided by the standalone pear-build module and integrated into the CLI.
--package [path] Path to project package.json
--target [path] Target build dir
--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 helpFor 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> Comma-separated path ignore list
--purge Remove ignored files if present in previous stage
--only <paths> Filter by paths. Comma-separated
--truncate <n> Advanced. Truncate to version length n
--json Newline delimited JSON output
--help|-h Show helppear provision <source-verlink> <target-link> <production-verlink>
Pre-production block sync
Synchronize blocks to a pre-production target link
The target can then be multi-signed against a production link
Use pear touch to generate target link
Arguments:
<source-verlink> Versioned source link
<target-link> Target link to sync to
<production-verlink> Versioned link to sync against
Flags:
--dry-run|-d Execute provision without writing
--json Newline delimited JSON output
--help|-h Show helppear 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.
| Command | Description |
|---|---|
keys get [name=default] | Get a signing key, initializing it if needed (--secret also prints the private key) |
keys paths [name=default] | Print paths to the public & private key files |
keys list | List signing keys |
keys add <name> <public-key> [private-key] | Import a signing keypair or add a known public key |
keys remove <name> | Remove a signing key |
link | Print the project multisig link (derived from the multisig field in pear.json) |
request <verlink> | Create a multisig request from a versioned source link |
sign <request> [name=default] | Sign a multisig request with a local signing key |
verify <source-link> <request> [...responses] | Verify the request and responses (commit dry-run) |
commit <source-link> <request> [...responses] | Apply signatures to sync the source drive to the multisig drive (go live) |
--config [./pear.json] Config file path
--peer-update-timeout <ms> Peer update timeout in ms (request, verify, commit)
--force Skip sanity checks (request)
--vanity <vanity> Vanity link prefix (link)
--json Newline delimited JSON output
--help|-h Show help--vanity applies to the link subcommand only, deriving a multisig link whose key starts with the given prefix. New in 3.1.0 Not available on 3.0.1 or earlier.
pear seed <link>
Seed project or reseed key.
Specify link to seed a project or a remote link to reseed.
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 Disable tty features
--stats-interval <ms> Stats refresh interval in milliseconds
--json Newline delimited JSON output
--help|-h Show helppear release <link> [dir]
removed
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.
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 entries to show
--of <semver=^*> SemVer filter - default: latest major
--full Show entire changelog
--json Newline delimited JSON output
--help|-h Show helpCHANGELOG.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] is the project directory path (defaults to the current directory).
Supply a link to view application information.
Supply no argument to view platform information.
--metadata View metadata only
--manifest View app manifest only
--multisig View multisig info only
--key View key only
--json Newline delimited JSON output
--help|-h Show helpWith --json, output arrives as three tagged objects before the closing final:
| Tag | data |
|---|---|
retrieving | z32, onlyShowKey |
keys | project, content, discovery |
info | link, verlink, name, version, productName, upgrade |
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.
Fixed in 3.1.0 On 3.0.1 and earlier, pear info and pear changelog can fail outright with ✖ Cannot read properties of undefined (reading 'key').
pear dump [flags] <link> <dir>
Synchronize files from link to dir.
To dump to stdout, use - in place of <dir>.
<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 Execute a dump without writing
--checkout <n> Dump from specified checkout, n is version length
--only <paths> Filter by paths. Implies --no-prune. Comma-seperated
--force|-f Force overwrite existing files
--list List paths at link. Sets <dir> to -
--no-prune Prevent removal of existing paths
--json Newline delimited JSON output
--help|-h Show helppear 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 vanity link with this prefix
--help|-h Show help--vanity mines for a key whose z32-encoded form starts with the given prefix. The value must contain only z32 characters—anything else is rejected with Vanity key must contain only z32 characters—and generation slows sharply as the prefix grows. Prefixes longer than four characters print a warning, and because it goes to stderr rather than stdout, LINK=$(pear touch --vanity pear) still captures just the link. New in 3.1.0 Not available on 3.0.1 or earlier.
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.
| Command | Description |
|---|---|
shutdown | Shut down the running sidecar |
inspect | Enable the running sidecar inspector |
--log-level <level> Level to log at. 0,1,2,3 (OFF,ERR,INF,TRC)
--help|-h Show helpRemoved in 3.1.0 --log-labels, --log-fields, and --log-stacks were removed in 3.1.0; only --log-level remains. All three still work on 3.0.1 and earlier.
--log-level accepts either a number (0–3) or a name (OFF, ERR, INF, TRC); it defaults to INF.
Persisted logs
New in 3.1.0 Log output is written to a file as well as the terminal, so sidecar errors and stack traces survive the process exiting—previously they were lost once it died.
-
Location:
pear.login the Pear platform directory. -
Rotation: at 10 MB the current file is moved to
pear.old.log, replacing any previouspear.old.log. Only those two files are ever kept. -
Line format: the level padded to five characters, an ISO-8601 timestamp, the label in brackets, then the message:
INF 2026-07-28T18:29:43.869Z [ sidecar ] - Sidecar BootedThe terminal prints the same entry with the timestamp first (
2026-07-28T18:29:43.869Z INF [ sidecar ] …), so parse the file rather than captured console output.
Entries above the active --log-level are dropped from both the file and the terminal, so raise the level before reproducing a fault you want captured.
pear versions
Output version information.
--modules|-m Include module versions
--json Newline delimited JSON output
--help|-h Show helppear 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.
pear presets [flags] [command]
removed
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>
removed
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]
removed
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 gc [flags] [command]
Perform garbage collection and remove unused resources.
| Commands | Description |
|---|---|
| sidecars | Clear running sidecars |
cores [link] | Clear corestore cores (optionally by link) |
--json Newline delimited JSON output
--help|-h Show helppear cores
List platform corestore cores.
New in 3.1.0 On 3.0.1 and earlier, pear cores fails with ✖ Unrecognized Argument at index 0 with value cores.
Prints one line per core—the core's pear:// link, suffixed (writable) when this device holds its key pair—followed by a Total cores: <n> | Writable: <n> summary, or No cores when the store is empty.
--json Newline delimited JSON output
--help|-h Show helpWith --json, each core is emitted as a "tag": "core" object carrying { link, writable }, and the closing "tag": "final" object carries { count, writable }.
Distinct from pear gc cores, which clears corestore cores rather than listing them.
pear data [flags] [command]
Explore the platform database.
The database contains metadata stored on this device used by the Pear runtime.
| Commands | Description |
|---|---|
| dht | DHT known-nodes cache |
| multisig | Multisig records |
--json Newline delimited JSON output
--help|-h Show helppear init
removed
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.
To scaffold a project, clone the official template instead—holepunchto/hello-pear-electron—and follow Start from the hello-pear-electron template.
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 helpAs of Pear v3, pear install is part of the Pear CLI, provided by the standalone pear-install module. For example, install an application peer-to-peer with:
pear install pear://<key>See Storage and distribution for the install model and the direction described in Pear Evolution.
pear run [flags] <link|dir> [...app-args]
removed
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-runtimeApplications 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.
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-runtimelibrary that replacespear run.