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.
npx pi-roundtable init my-bot # or: bunx pi-roundtable init my-botinit 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
initwould create already exists. The message lists the files and ends withRemove them or run init in an empty directory; nothing was written.
init takes at most one directory; a second argument is a usage error.
--adapter web
Section titled “--adapter web”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
Section titled “doctor”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 yetA 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.
The --reachable flag
Section titled “The --reachable flag”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.
add plugin
Section titled “add plugin”bunx roundtable add plugin my-notesadd 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:
bunx roundtable add plugin diceAny 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.tsis not in the current directory.plugins/<name>.tsor its test already exists.- The config file does not parse, has no
pluginslist 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>.
add package
Section titled “add package”bunx roundtable add package pi-web-accessadd 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.tsis not in the current directory.plugins/<name>.tsor its test already exists.- The config file does not parse, has no
pluginslist 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.
upgrade
Section titled “upgrade”bunx roundtable upgradebunx roundtable upgrade --writeupgrade 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.
principal
Section titled “principal”bunx roundtable principal listbunx roundtable principal create --name Adabunx roundtable principal link <principal> discord:<user id>bunx roundtable principal grant <principal> adminprincipal 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.
Exit codes
Section titled “Exit codes”| 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.