Altretta is your local-first, encrypted second brain — a knowledge vault with a semantic engine that runs on your machine. This CLI is how you build and sign the plugins that extend it.

Install

npx @apilium/altretta-plugin keygen --out author.key
npx @apilium/altretta-plugin pack . --key author.key --out my-plugin.altplugin --deny-warnings
npx @apilium/altretta-plugin verify my-plugin.altplugin

One npx and it runs. The binary is resolved per-platform at run time (see below), so there is no postinstall and no network at install time.

The Altretta plugin model

A plugin is one JavaScript file plus a manifest.json. It runs in a hardened sandbox — a frozen SES compartment inside a worker, with no DOM, no network, and no filesystem. Its only way to reach the app is one injected altretta object, and every call goes through a permission check. Plugins can't betray you — not by policy, by construction:

• Signed. Every plugin carries an author signature over its exact code and manifest. Change one byte and it stops verifying.
• Verifiable. Apilium reviews a plugin and counter-signs the same bytes for the Verified badge, without ever seeing the author's private key.
• Revocable. A compromised plugin is disabled everywhere through a signed revocation list, with anti-downgrade protection.
• Scoped. Grant a plugin ReadNotes and WriteNotes and it can never open a socket. The permissions you see are the whole contract.

This CLI is the toolchain behind that trust model: it mints your author key, packs your code into a signed .altplugin, and verifies the result.

Scaffold a plugin in seconds

Don't start from scratch. The scaffolder wires this CLI in as a devDependency so a fresh project is ready to pack:

npx @apilium/create-altretta-plugin my-plugin
cd my-plugin
npm install
npm run keygen     # once: creates author.key
npm run pack       # builds, then signs into my-plugin.altplugin (--deny-warnings)
npm run verify     # confirms author_ok: true

Then load it in Altretta → Plugins → Developer Mode → Load plugin folder, consent to its permissions, and watch it run.

Commands

| Command | What it does | | --- | --- | | keygen --out <file> | Generate an Ed25519 author signing key. | | pack <dir> --key <file> --out <file> [--deny-warnings] | Pack a plugin folder into a signed .altplugin. | | countersign <file> --key <apilium-key> --out <sig> | Apilium-side: counter-sign reviewed bytes for the Verified badge. | | verify <file> [--apilium-sig <sig>] | Confirm the author (and Apilium) signature. | | bundle <file> --out <dir> | Produce a Hub-ready bundle folder. |

Per-platform binaries

This package is a thin launcher — it ships no binary itself. Each supported platform has a companion package carrying the matching prebuilt native binary, declared as optionalDependencies so npm install fetches only the one that matches your machine (the esbuild / Biome distribution model):

| Platform | Package | | --- | --- | | macOS (Apple Silicon) | @apilium/altretta-plugin-darwin-arm64 | | macOS (Intel) | @apilium/altretta-plugin-darwin-x64 | | Linux (x64) | @apilium/altretta-plugin-linux-x64 | | Windows (x64) | @apilium/altretta-plugin-win32-x64 |

On an unsupported platform the launcher prints a clear message naming the <platform>-<arch> combo and how to request it.

No terminal? Use the app

The same signing engine is built into the Altretta desktop app. If you prefer a GUI, use Package & sign in Altretta Developer Mode: it creates your author identity once, packs, verifies, and saves a .altplugin for you.

The bigger picture

Altretta is more than plugins — it's a connected second brain:

• 🧠 Altretta — the local-first, encrypted vault with a semantic engine. Your notes, decisions, and knowledge, on your machine.
• 🤖 Altretta Skill — give your AI a second brain. One command (npx skills add ApiliumCode/altretta-skill) connects your vault to Claude Code, Codex, Cursor, Gemini CLI, and 60+ more agents, with cited, grounded retrieval.
• 🧩 Altretta Plugins — the official catalog of signed, sandboxed, permission-scoped extensions. This CLI is how you author them.

License

Apache-2.0 OR Commercial. Built by Apilium.