Desktop apps, extensions and CLIs playbook

A desktop apps playbook for software that people install on their own computer. It covers Mac, Windows and Linux apps, whether native or built with Electron or Tauri, plus browser extensions and command-line tools. The chapters cover signing and notarisation, safe updates, web code inside desktop apps, browser extensions, and command-line tools.

Installed software runs with the user's own rights. A stolen signing key or a hijacked update reaches every user at once. Most rules here guard the path from your build to their computer. Phone apps have their own rules in the mobile apps playbook, and these rules link to them where the method is the same.

AI agents run command-line tools more than people do. A tool with honest exit codes, JSON output and no surprise prompts lets an agent use it correctly on the first try.

Chapters

1. Signing and notarisation

   Sign every build for each platform, notarise Mac builds, keep signing keys in hardware, and check every signature in CI before anyone downloads it.

   • Required 2
   • Recommended 3

2. Update integrity

   Install only updates signed by your own key and never an older version. Roll each update out in stages, with a switch that stops it.

   • Required 1
   • Recommended 3

3. Web code inside desktop apps

   Apps built with Electron or Tauri run web code next to the operating system. Isolate the page, check every message and link, and store tokens in the keychain.

   • Required 1
   • Recommended 3

4. Browser extensions

   Ask for the fewest permissions, ship every line of code in the package, distrust web pages, and fill in each store's data forms truthfully.

   • Required 2
   • Recommended 4

5. Command-line tools

   Exit codes, clean output streams, JSON output and no surprise prompts let scripts, CI jobs and AI agents use a command-line tool safely.

   • Required 1
   • Recommended 6

All 26 rules on one page

This is a lot to check. An Expert can check it for you.

Related playbooks

• Signing and release

  In the Mobile apps playbook. Signing keys, CI signing and staged releases work the same way for phone apps.

• Supply chain and setup

  In the Adversarial testing playbook. Locked dependencies and safe publishing keep a bad package out of your installer.

• Build, test and deploy

  In the Engineering playbook. Build in CI, stamp the version and release to a small share first.

• Sign-in methods

  In the Accounts and identity playbook. Sign-in for a command-line tool without a browser on the same machine.