Skip to content

CLI

The package installs one command, roundtable. It runs on Bun and says where to get Bun when Bun is missing. Inside a project, run it with bunx roundtable <command>.

Command What it does
roundtable init [dir] [--adapter discord|web] Creates a project in dir (default: the current directory) that talks through Discord (the default) or through the web chat.
roundtable doctor [--reachable] Checks the setup and says how to fix what is wrong.
roundtable start Runs the checks that need no network, then the bot.
roundtable add plugin <name> Adds plugins/<name>.ts and its test, and lists the plugin in the config. codex-images, dice, and release-notice are reserved for the official plugins.
roundtable add package <spec> Installs a Pi package with bun add, and adds a plugin that loads it and gives its tools to every agent turn.
roundtable upgrade [--write [--unchecked]] Shows roundtable.config.ts rewritten in the 0.9 form (owner and speakers as access, discord as an adapter) as a diff; --write writes it once it is checked to serve the same people.
roundtable principal list|show|create|link|unlink|grant|revoke|disable|enable Lists and changes the principals, their identities, and their roles in the database.

roundtable help and roundtable --help print this list. roundtable --version prints the package version.

Terminal window
npx pi-roundtable init my-bot # or: bunx pi-roundtable init my-bot

init writes a working project without asking for secrets. It creates these files in dir: package.json, .gitignore, roundtable.config.ts, biome.json, README.md, agents.ts, docker-compose.yml, persona/shared.md, .env.example, tsconfig.json, plugins/hello.ts, plugins/hello.test.ts, and plugins/self-compact.ts. plugins/self-compact.ts loads the Pi package pi-self-compact, which package.json pins: every session needs its compact_session tool, and start stops without it. The package.json pins the exact version of pi-roundtable that ran init. It prints three steps: install and fill .env, run doctor, run start.

init leaves the directory unchanged if either check fails:

  • Bun is missing or older than the range the package needs.
  • A file init would create already exists. The message lists the files and ends with Remove them or run init in an empty directory; nothing was written.

init takes at most one directory; a second argument is a usage error.

Terminal window
npx pi-roundtable init my-desk --adapter web

--adapter web writes a project without Discord around pi-roundtable-webchat. It leaves out agents.ts and persona/shared.md, and writes persona/assistant.md instead. Its roundtable.config.ts has no discord, listens on 127.0.0.1:3000, and lists webChat({ ... }) with an OpenID Connect verifier, a top-level access whose members and admins come from the token’s roles, and one persona whose selection names its tools. Its package.json also pins pi-roundtable-webchat at the core’s version, and its .env.example asks for OWNER_NAME, DATABASE_URL, MODEL, OIDC_ISSUER, OIDC_AUDIENCE, OIDC_JWKS_URL, CHAT_MEMBER_ROLES, and CHAT_ORIGINS. --adapter discord is the default; any other value is a usage error that lists discord, web and writes nothing.

doctor runs every check, in the order below, and prints one line for each. It leaves the setup unchanged and exits non-zero if any check fails.

✓ Bun: Bun 1.4.4
✗ environment: no value for DISCORD_TOKEN, ...
Copy .env.example to .env and fill them in; .env.example says where each one comes from.
- plugins: skipped, the configuration is not valid yet

A passed check starts with ✓ and may add a detail. A failed check starts with ✗, states the problem, and puts the fix on the indented lines under it. A check that cannot run because an earlier one failed starts with - and is skipped. A skipped check does not fail the run.

# Check What it looks at
1 Bun The running Bun’s version against the package’s engines.bun range.
2 environment Every uncommented variable in .env.example has a value.
3 configuration roundtable.config.ts loads, passes its schema, and assembles. The failing key is named.
4 plugins Every plugin loads, no two share a name (the built-in ones included), and the registration is valid.
5 access Whom access serves: the owners, and a warning when everyone: true admits everyone on every surface of a host with more than one.
6 image provider Whether a plugin fills the images slot. Having none is not a failure: agents’ avatars are composed characters and no longer drawn with it.
7 characters Whether canvas can rasterize SVG, which the agent server needs for the agents’ pictures.
8 PostgreSQL The database answers, and every plugin’s migrations run. They run inside a transaction that is always rolled back, so the database is left as it was.
9 principals A dry run of the principals the next start makes from the people the database already knows; a configured owner’s identity linked to someone else fails, and a disabled owner is a warning.
10 Discord token Discord accepts the bot token.
11 Discord guild The bot is a member of discord.guild.
12 Discord intents The Message Content intent is on.
13 Discord channel The entry channel exists in the guild, and the bot holds the permissions below in it.
14 model login A login exists for the provider of model.
15 public URL http.publicUrl is a well-formed http:// or https:// address.

A project without Discord skips checks 10 to 13, with the reason no Discord is configured, and check 15 when http.publicUrl has no value; a Discord adapter in adapters is checked as the top-level discord is.

The permissions that check 12 requires in the entry channel are View Channel, Send Messages, Send Messages in Threads, Read Message History, Embed Links, Attach Files, Pin Messages, Create Public Threads, Manage Channels, and Manage Webhooks. When the bot is not in the guild, the fix is an invitation link that asks for exactly these permissions.

doctor --reachable also requests the public URL, which fails unless the bot is running and the tunnel or proxy that publishes the address works. Without the flag, check 15 only confirms that the address is well formed. --reachable is the only flag, and only doctor accepts it. Any other argument is a usage error.

start runs the checks that need no network: Bun, environment, configuration, plugins, access, image provider, characters, model login, and public URL. If one fails, it prints the same lines doctor prints, to standard error, and exits with code 1 before anything reaches Discord. Otherwise it starts the bot.

The bot connects to PostgreSQL and Discord during boot. A wrong database address or a rejected token stops the process with a message and exit code 1. Run doctor first to find those problems with their fixes.

On SIGTERM or SIGINT the bot finishes running work before it stops. It waits for at most three minutes by default (drainSeconds in the configuration); whatever is still running after that is logged and given up on. See Startup and project setup for the order in which things start and stop.

Terminal window
bunx roundtable add plugin my-notes

add plugin creates plugins/my-notes.ts and plugins/my-notes.test.ts from the hello template, imports the plugin in roundtable.config.ts, and lists it in plugins.

Three names are reserved for the official plugins, codex-images, dice, and release-notice. For any of them, add plugin copies the ready-made plugin and its test and registers it the same way:

Terminal window
bunx roundtable add plugin dice

Any other valid name keeps the hello template, so a name such as dice-roller is a template plugin. The usage text lists the reserved names.

The command checks and renders everything before writing. It leaves the project untouched if:

  • The name is not lowercase words joined by dashes, such as my-notes.
  • roundtable.config.ts is not in the current directory.
  • plugins/<name>.ts or its test already exists.
  • The config file does not parse, has no plugins list it can find, or already uses the name for something else. The message says what to add by hand.

The command takes exactly one name; anything else prints usage: roundtable add plugin <name>, or roundtable add package <spec>.

Terminal window
bunx roundtable add package pi-web-access

add package installs a Pi package from npm and writes the plugin that uses it. It runs bun add <spec>, loads the package’s extensions to find the tools they register, and writes plugins/<name>.ts and plugins/<name>.test.ts, named after the package without its scope (@scope/pi-notes becomes plugins/pi-notes.ts). It then imports the plugin in roundtable.config.ts and lists it in plugins, as add plugin does.

The plugin lists the package in piPackages, so every conversation session loads it. It lists the tools in agentSelection, because a turn uses only the tools it selects, and in requiredTools, so startup fails when a newer version of the package drops one. It gives no tool a tier: a tool no other plugin gives a tier is the owner’s alone until you lower it with toolTiers in roundtable.config.ts. The command prints the tools it found.

The spec is a registry name, optionally scoped and with a version or tag: pi-web-access, pi-web-access@0.35.0, @scope/name. It refuses before installing, leaving the project untouched, if:

  • The spec is not a registry name, such as a git URL or a local path, or the name without its scope is not lowercase words joined by dashes.
  • roundtable.config.ts is not in the current directory.
  • plugins/<name>.ts or its test already exists.
  • The config file does not parse, has no plugins list it can find, or already uses the plugin’s name for something else.

Every refusal says how to do it by hand: install with bun add and list the package in a plugin’s piPackages. After installing, it writes no plugin and names the bun remove command when bun add fails, when the package’s package.json lists no extensions under pi and the package has no extensions folder, or when an extension fails to load. It finds only the tools an extension registers as it loads; a tool registered later, such as after a connection, has to be added to the list by hand.

Terminal window
bunx roundtable upgrade
bunx roundtable upgrade --write

upgrade prints roundtable.config.ts rewritten in the 0.9 form as a diff: owner and speakers become access, and discord becomes an adapter. It changes nothing without --write. --write first checks that the rewritten configuration serves the same people, which needs the environment the host runs with, and refuses when it cannot check. --write --unchecked writes it without that check, with a warning.

Terminal window
bunx roundtable principal list
bunx roundtable principal create --name Ada
bunx roundtable principal link <principal> discord:<user id>
bunx roundtable principal grant <principal> admin

principal lists and changes the people the host serves, in the database: list, show <principal>, create --name <name> [--pronouns he|she|they], link <principal> <provider>:<subject>, unlink <provider>:<subject>, grant and revoke <principal> member|admin|owner, and disable and enable <principal>. A <principal> is a principal id or an identity linked to it. list prints identities as access in roundtable.config.ts takes them. A running host sees a change within 30 seconds; a host that starts sees it at once.

Code When
0 The command succeeded: init, add plugin, and add package wrote their files, every doctor check passed or was skipped, help and --version printed, or the bot stopped cleanly.
1 A command refused or failed, a doctor check failed, a check made start stop, the arguments were wrong, the command is unknown, or no command was given (the usage is printed).

Usage errors print the message and then the usage text. When the bot is stopped by a signal, it exits with 1 if a listener, a service, or the database pool failed to stop, and with 0 otherwise.

For the messages the checks print and what fixes them, see Errors.