docs · reference

CLI.

The rune CLI handles everything outside the running server: scaffolding a new Rune, packaging it for distribution, publishing to the registry, and installing one onto a server. It reads rune.toml, talks to the Runebook API, and operates against a personal access token you issue from your dashboard.

Authentication

The CLI authenticates to Runebook with a personal access token. Mint one at your dashboard, then save it.

rune login                # prompts for the token
rune login --token rune_pat_...   # non-interactive
rune logout
rune whoami               # prints the username the token belongs to

The token is stored at ~/.config/rune/token (owner-readable only) and sent as Authorization: Bearer rune_pat_*.

Project lifecycle

rune init

Scaffold a new Rune project in the current directory.

rune init                              # uses dir name
rune init --name hello                  # explicit name
rune init --language wasm               # default is typescript
rune init --force                       # overwrite existing files

Emits rune.toml, rune.jsonc, tsconfig.json, package.json, and an index.ts with a working listener.

rune pack

Build a publishable archive. Computes per-file sha256 hashes, assembles the canonical manifest, and writes a zstd-compressed archive into the output directory.

rune pack                          # writes to ./dist/
rune pack --out ./build            # custom output dir
rune pack --dir ./scripts/ward     # pack a different project

The archive is content-addressed — pack the same source twice and the hashes match. Useful for verifying a published artifact: rune pack locally, compare the hash on the Runebook detail page.

rune publish

Pack and upload in one step. The CLI sends the manifest first, gets pre-signed R2 URLs for any blobs the registry hasn't seen, uploads them, then finalizes.

rune publish                       # ship as a stable version
rune publish --draft               # publish but pre-yank for testing
rune publish --yes                 # skip the confirmation prompt
rune publish --registry https://...   # alternate registry

Blobs are deduplicated across every Rune. Two versions that share a file upload that file once; the second publish sees it's already in storage and skips it.

Server-side commands

These run from inside a Paper server root — plugins/Rune/ needs to be present.

rune add

Install a published Rune into plugins/Rune/scripts/. Resolves the latest stable version unless you pin one.

rune add ward
rune add ward@0.1.0
rune add @yourname/foo
rune add ward --scripts ./plugins/Rune/scripts
rune add ward --force                 # overwrite if already installed

rune remove

Uninstall a Rune by name. The CLI deletes its script directory; rune.store() data is preserved by default.

rune remove ward
rune remove ward --yes              # skip confirmation

In-server commands

Some commands are run inside Paper, against the running host, not the CLI:

/rune reload — re-evaluate every script. The iteration loop. Doesn't restart the server.
/rune list — show every script the host is currently running, with its version.
/rune info <name> — show a script's manifest, declared capabilities, and current uptime.
/rune new-script --name <name> — scaffold a new script directly inside the server (convenience equivalent to running rune init from the scripts dir).

rune yank

Soft-delete a published version. Yanked versions remain installable for operators who pinned them, but disappear from the default resolver and show a banner on the detail page.

rune yank @yourname/ward@0.1.0 --reason "broken on 1.21.4"

Use yank when you ship a broken version. Don't use it to un-publish — published is forever. The right move for a bad publish is to yank it and ship a fixed patch version.