Build a CLI executable with pear make

pear make packages a command-line app's JavaScript and its dependencies into one executable per OS and architecture. The executable runs on its own: users don't need Node.js, Bare, or the Pear CLI installed. Use it for CLIs, REPLs, TUIs, and other headless apps written for Bare, such as one started from the hello-pear-bare template.

Under the hood, pear make runs pear-make, a separate Pear CLI app that calls bare-build in standalone mode. It builds the executable and nothing else. To ship it over the air, you still assemble a deployment directory and stage it (see Where to go next). For an Electron desktop app, follow Build desktop distributables instead.

Before you beginCopy Anchor Link

• Pear 3.7.0 or newer.
• A project written for Bare, with a package.json. A Node.js app needs its built-ins swapped for bare-* modules first; see Migrate a Node.js app to Bare.
• Its dependencies installed with npm install. pear make bundles them from node_modules.
• Network access on the first run, to install pear-make from peers.

{
  "name": "hello-cli",
  "version": "1.0.0",
  "description": "Greet a peer from the terminal",
  "bin": "bin.mjs",
  "scripts": {
    "start": "bare bin.mjs"
  },
  "dependencies": {
    "bare-path": "^3.1.3",
    "paparam": "^1.15.0"
  },
  "devDependencies": {
    "bare": "^1.37.1"
  }
}

import { command, arg, flag, summary } from 'paparam'
import path from 'bare-path'
import pkg from './package.json'

// True under `bare bin.mjs`, false in the built executable
const isDev = path.basename(Bare.argv[0], path.extname(Bare.argv[0])) === 'bare'

const cmd = command(
  pkg.name,
  summary(pkg.description),
  arg('[name]', 'Who to greet'),
  flag('--shout|-s', 'Print the greeting in uppercase')
)

cmd.parse(Bare.argv.slice(isDev ? 2 : 1))
if (cmd.flags.help) Bare.exit()

const greeting = `Hello, ${cmd.args.name || 'peer'}!`
console.log(`${cmd.flags.shout ? greeting.toUpperCase() : greeting} (${pkg.name} v${pkg.version})`)

npm install

npx bare bin.mjs Ada

pear make -v

⚠️ The pear-make CLI needs to be installed. To confirm type "INSTALL"
Install pear-make?

v1.1.0
Success

pear install pear://u3d888539k964t6omfzxdmf1a9c4jx4iiprm8jyt56x91izm78sy

pear make --name hello-cli --path out/make

pear-make v1.1.0
/path/to/hello-cli/out/make/hello-cli

Build finished.

Success

./out/make/hello-cli Ada --shout

HELLO, ADA! (hello-cli v1.0.0)

for host in darwin-arm64 darwin-x64 linux-arm64 linux-x64 win32-arm64 win32-x64; do
  pear make --host "$host" --name hello-cli --path "out/make/$host"
done

foreach ($h in 'darwin-arm64','darwin-x64','linux-arm64','linux-x64','win32-arm64','win32-x64') {
  pear make --host $h --name hello-cli --path "out/make/$h"
}

Run it in CI or a scriptCopy Anchor Link

Without a terminal, pear make can't ask before installing pear-make, so a missing pear-make fails the run:

✖ The pear-make CLI was not found. Please install using: pear install pear://u3d888539k964t6omfzxdmf1a9c4jx4iiprm8jyt56x91izm78sy

Pass --install to install pear-make without asking, but only on a runner that doesn't have it yet. When a copy is already installed, pear install refuses to overwrite it, printing Refusing to overwrite existing: (Already installed: on Windows), and pear make exits with status 1. Don't combine --install with --json either: in Pear 3.7.0 the install's progress lines go into the JSON stream as plain text.

On a runner that keeps its home directory between jobs, install pear-make only when it is missing. In a bash step:

command -v pear-make >/dev/null || pear install pear://u3d888539k964t6omfzxdmf1a9c4jx4iiprm8jyt56x91izm78sy
pear make --no-install --name hello-cli --path out/make

In PowerShell, the default shell on Windows runners:

if (-not (Get-Command pear-make -ErrorAction SilentlyContinue)) { pear install pear://u3d888539k964t6omfzxdmf1a9c4jx4iiprm8jyt56x91izm78sy }
pear make --no-install --name hello-cli --path out/make

Put the install directory on the job's PATH before the first pear command, because that command starts the sidecar (see the warning in Install pear-make). It is ~/.local/bin on macOS and Linux, and %LOCALAPPDATA%\Programs\pear-make on Windows, where pear install adds it only to the user PATH in the registry, which a running job doesn't read. On GitHub Actions, append it in an earlier step: echo "$HOME/.local/bin" >> "$GITHUB_PATH" in bash, or "$env:LOCALAPPDATA\Programs\pear-make" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append in PowerShell.

For machine-readable output, pass --json. Each piece of pear-make output arrives as a make object, and the stream ends with a final object or, on failure, an error object:

{"cmd":"make","tag":"make","data":{"chunk":"pear-make v1.1.0\n"}}
{"cmd":"make","tag":"make","data":{"chunk":"/path/to/hello-cli/out/make/hello-cli\n\nBuild finished.\n\n"}}
{"cmd":"make","tag":"final","data":{"success":true}}

In Pear 3.7.0 the objects are written back to back, with no newline between them (they're shown one per line here). jq reads them as they are, but tools that split on lines don't. To print the build log:

set -o pipefail
pear make --json --name hello-cli --path out/make | jq -rj 'if .tag == "make" then .data.chunk elif .tag == "error" then .data.message + "\n" else empty end'

A failed build exits with status 1. set -o pipefail keeps that status through the pipe, which the default run shell on GitHub Actions doesn't do, and the filter also prints the message of an error object, such as the ENOENT one Pear emits when it can't start pear-make.

Sign the executableCopy Anchor Link

Sign and notarize the executable before you hand it to users. pear make has no signing options, so either sign the file it wrote with your platform's tools, or build with bare-build --standalone directly and use its signing flags. The npm run make of the hello-pear-bare and hello-pear-qvac-tui templates takes the second route, with the MAC_CODESIGN_IDENTITY, KEYCHAIN_PROFILE, and WINDOWS_CERT_SHA1 variables (see Build a standalone binary). To notarize a macOS executable you sign yourself, sign it with the hardened runtime (codesign --options runtime) and the com.apple.security.cs.allow-jit and com.apple.security.cs.allow-unsigned-executable-memory entitlements, the ones bare-build adds when it signs with the hardened runtime. In CI, the make-pear-app action provides the same credentials.

TroubleshootingCopy Anchor Link

• ✖ package.json not found in <dir>. Run pear make from the project root, or pass the entry file as the argument.
• ✖ bin field not found in package.json Add a bin field that points at your entry file, or pass the entry file as the argument.
• ✖ no such file or directory The sidecar can't find pear-make on its PATH. This happens when pear-make was installed, or its directory added to PATH, after the sidecar started, and when --no-install is passed with no pear-make installed. Check that command -v pear-make (Get-Command pear-make in PowerShell) finds it, then run pear sidecar shutdown, which also stops any running pear seed, and build again.
• ✖ pear-make failed with exit code <n> pear-make itself failed, and the lines before this one are its error. MODULE_NOT_FOUND: Cannot find module 'file:///…' means the entry file doesn't exist. Unknown host '<host>' means pear-make doesn't recognize the --host id.
• Refusing to overwrite existing: (Already installed: on Windows) You passed --install with pear-make already installed. Drop --install.
• The executable is called app. Pass --name; see Build for your machine.

Where to go nextCopy Anchor Link

• Deploy your application: set the upgrade link, then assemble your executables into a deployment directory with pear build, stage, provision, and seed. Users then install with pear install pear://<key>.
• Start a terminal app from the hello-pear-bare template and Start a short-lived CLI from the hello-pear-daemon template: CLI apps that already update themselves over the air.
• Bundle a Bare app: what bare-build does underneath, and the options pear make doesn't expose.
• pear make reference: every flag and error.