ubd is Unbound's command line tool, published as @unbound-app/cli. It needs Bun.

bunx @unbound-app/cli --help

Every command takes --help for its flags and --json to print the raw result. ubd alone lists the commands; a group alone, such as ubd debug, lists the commands in it.

With --json, a failure prints { "ok": false, "text": ..., "error": { "code": ..., "message": ... } } on stdout, or the command's own data with error added. The error may also carry a hint, the field a rejected flag or argument names, and a stack. Scripts can branch on code: invalid-input, no-device, timeout, not-found, tool-failed and so on. Exit codes do not change: 1 for a failed command, 2 for a usage error or no connected device.

Layout

A command that moved into a group names its new place: ubd eval answers Did you mean ubd debug eval?.

Device Access

Make an Addon

1. Scaffold

   ubd create asks for anything you don't pass as a flag.

   ubd create --kind plugin --name hello-world --shape repository --git-init --install

   Flag	Meaning
   --kind	plugin or theme.
   --shape	repository for a workspace of several addons, or addon for one.
   --name	The addon name, in kebab-case.
   --id	The manifest id. Defaults to <author name>.<name>.
   --display-name, --description	The name and one-line description shown in Unbound.
   --author-name, --author-id	You, and your Discord id.
   --dir	Where to create it. Defaults to ./<name>.
   --git-init, --install	Initialize git and install dependencies. Repository shape only.

2. Build and Hot Reload

   Run these from the workspace.

   ubd build
   ubd dev

   Command	What it does
   ubd build	Builds every addon once and reports which succeeded. --verbose also logs each custom filter rewritten into a built-in one, with file and line.
   ubd dev	Watches every addon, rebuilds the one that changed, and reloads it on the device.
   ubd debug push <name>	Builds one plugin, installs it if missing, and hot reloads it. --build=false pushes the existing build.

3. Install for Cold Starts

   ubd device install copies a built plugin into Discord's plugin folder, so it loads on the next cold start. --restart restarts Discord right away.

   ubd device install hello-world --restart
   ubd device install hello-world --ios --restart

4. Publish

   Log in once by approving a code on the website, then submit the addon for review. Its build output must be committed and pushed.

   ubd auth login
   ubd publish

   Flag	Default
   --addon	Required when the workspace has several addons.
   --ref	The tag on HEAD, otherwise its commit.
   --repository	The origin remote.

   ubd auth logout deletes the stored credentials.

Check an Addon

ubd check runs every check ubd build runs, without writing a bundle. It also validates the manifest against the publish rules, runs the plugin lint with the nearest .oxlintrc.json, and runs the build's rollup plugins over the module graph.

ubd check                       # the addon holding the current directory
ubd check --plugin plugins/demo # another addon; repeat --plugin for several
ubd check --all                 # every addon in the workspace
ubd check --only lint,manifest  # just these checks

Each problem prints as file:line:column <path> <problem>. Fix: <fix>., grouped by file, errors first. A summary such as 3 errors, 1 warning in 2 files follows. ubd build prints the same way.

Build Report

After each plugin builds, ubd build prints what it ships and warns when a size passes its budget:

starred-users 1.2.0
  bundle      index.js            18.4 KB   (gzip 6.1 KB)   bytecode 41.2 KB
  inlined     en-US strings        1.1 KB
              svg (3)              2.4 KB
  shipped     i18n (2 locales)     2.0 KB
              assets (4)          12.8 KB
  metro       filters 9 keyed · 1 uncached  (src/index.tsx:12)
  ⚠ bundle over 50 KB budget (61.2 KB)

--verbose also lists the five largest source modules. --json prints the same data. ubd dev --report prints one line per rebuild, such as Built my-plugin: 18.4 KB · 1 uncached filter; without --report, ubd dev skips the report so each hot rebuild stays fast.

Budgets

The bundle budget is 50kb and the assets budget is 500kb. Change them in rollup.config.mjs:

import { unbound } from '@unbound-app/cli/rollup';

export default unbound(import.meta.url, { budget: { bundle: '80kb', assets: '1mb' } });

• A size over budget is a warning. --strict-budget fails the build instead.
• The report warns when the bundle contains a node_modules library the client already provides, such as a lodash file imported by path. Import it by name to use the client's copy.

Custom Report Lines

A rollup plugin adds a line by emitting reportLine(entry) with this.emitFile, from any hook up to generateBundle. The entries never reach dist.

import { reportLine } from '@unbound-app/cli/rollup';

this.emitFile(reportLine({ section: 'inlined', label: 'svg', unit: '', bytes: xml.length }));

Entries with the same section and label merge:

Translations

ubd i18n check checks a plugin's i18n/ folder against i18n/en-US.json. Every ubd i18n command runs in the plugin, or takes --plugin <dir>, and ends with this report. Per language it prints translated and missing keys, keys en-US.json lacks, and every ICU problem with file, line and position.

ubd i18n check
ubd i18n fix
ubd i18n unused
ubd i18n add GREETING "Hello, {name}!"
ubd i18n check --json

--json prints the report as JSON.

ICU problems are placeholders that differ from English, a plural or select without an other branch, and syntax errors.

Exit Codes

It exits 1 on any of these:

• An ICU problem.
• A key en-US.json does not have.
• A file it cannot read.
• For unused, a used key en-US.json lacks.

Missing translations fail only check --strict.

Untranslated Stubs

ubd i18n fix records each key it added in i18n/untranslated.jsonc, with the English text it wrote. Commit that file: the report counts those keys as missing until their text changes. The build never reads it. The next ubd i18n fix drops translated keys and updates stubs whose English changed.

Unused Key Detection

ubd i18n unused finds keys passed as string literals:

Keys built at run time, such as messages[name], are not found. The report counts these reads so you can verify its unused list.

Run and Reload

trace and hook record for --duration ms (default 3000) and describe the first --samples calls (default 10).

Inspect Native Code

Logs and Device State

ubd device logs tails Discord's log, filtered to Unbound, the JavaScript console and crashes. On Android it follows adb logcat for com.discord across restarts. On iOS it reads the unified log.

ubd device save, restore, snapshots and reset keep Discord's Unbound state, to test from a known start:

ubd device save clean
ubd device snapshots
ubd device restore clean --restart
ubd device reset

MCP Server

ubd mcp serves the ubd debug commands (except start and restart) and the ubd device commands (except logs) as tools of a stdio MCP server. A debug command keeps its name as a tool (eval); a device command takes a prefix (device_install). The rest stay CLI only. See AI Agents.

{
	"mcpServers": {
		"unbound": { "command": "bunx", "args": ["--bun", "@unbound-app/cli", "mcp"] }
	}
}