Skip to content
popii

CLI

popii init
popii dev [entry]
popii sync [entry]
popii test [...bunArgs]
popii generate <type> <name>
popii doctor [--json]
popii console [entry]
popii plugin <add|remove|search|list>
popii db <generate|migrate|status>
popii upgrade <check|plan|apply|verify>
popii deploy <railway|fly|vps>
popii web check
popii secret generate web

Terminal experience

Section titled “Terminal experience”

Cakemix uses one presentation system for help, progress, health checks, lists, successes, warnings, and actionable failures. Color is enabled only for an interactive terminal, respects NO_COLOR, FORCE_COLOR, TERM=dumb, and CI, and is never the only way a status is communicated.

Global automation controls are available before the command:

popii --json plugin list
popii --quiet web check
popii --no-color doctor

--json emits a stable { schemaVersion, ok, data | error } envelope. --quiet removes progress and nonessential success messages while retaining requested values and errors. --no-color guarantees ANSI-free output. Secret generation remains a single raw value unless JSON is explicitly requested.

Help output includes the Cakemix release identity, grouped commands and options, concise examples, and the documentation URL. Unknown commands receive Commander suggestions; removed commands receive their exact 1.0 replacement.

Interactive initialization is a branded multi-step Cakemix flow and finishes with the created location, file count, dependency state, and exact next commands. Plugin installation shows the resolved package, version, publisher, metadata status, and configuration target before or after installation. Deployment generation lists every created file and its next deployment command.

Synchronization reports whether Discord was updated or already current, the command count, and global or guild scope. Test runs retain Bun’s detailed output and add an elapsed-time result. Development mode reports watched directories and reload events, while the console uses the cakemix> prompt. Doctor checks are grouped into Runtime, Discord, and Data sections.

Output adapts at narrow terminal widths by stacking labels and descriptions. Set POPII_ASCII=1 for ASCII-only status symbols and separators.

Popii 1.0 removed raw GitHub installation and moved plugin and database operations into command groups. Invalid commands return a nonzero exit code.

popii init accepts --name, --yes, --no-install, --preset, --plugins, and --no-plugins. Interactive setup starts with a Dashboard Core, Community, Moderation, Music, Full Dashboard, or Minimal pack and then opens a categorized built-in plugin selector. Popii resolves required plugins, conflicts, optional packages, environment placeholders, and pending dashboard setup before writing files. --yes defaults to Dashboard Core. Noninteractive automation supplies the token through DISCORD_TOKEN, never a command-line argument that would remain in shell history. If dependency installation fails, the newly created project directory is removed.

Plugin installation resolves an exact npm version, edits popii.config.ts through the TypeScript parser, writes atomically, and removes the package again if configuration cannot be committed.

Only npm package names are accepted. URLs, filesystem paths, GitHub shorthands, and raw source installations fail before network or package-manager access. Generated configuration is parsed again before the atomic rename.

popii sync waits for Discord command registration to finish, reports failures, times out after 30 seconds, destroys the Discord connection, and never terminates the host process itself. popii console similarly has a bounded readiness wait. Development watchers are owned by the client and close during graceful shutdown.

Database commands delegate to Drizzle Kit when drizzle.config.ts exists. Without a Drizzle project, db migrate applies the transactional core SQLite baseline; generation requires an explicit Drizzle configuration.

Exit code 0 means success, 1 means validation or operational failure, 2 identifies a removed legacy invocation, and 130 means an interactive operation was cancelled.

Upgrade an existing project

Section titled “Upgrade an existing project”
popii upgrade check [--from <version>]
popii upgrade plan [--from <version>]
popii upgrade apply [--from <version>] [--dry-run] [--yes]
popii upgrade verify [--from <version>]

check is read-only. plan writes popii-upgrade-report.md. apply updates only recognized package scripts, the Popii dependency range, and retired built-in plugin entries after creating .popii-upgrade/<timestamp>/. verify repeats discovery and runs the project’s typecheck script when present.

All four commands support root --json. Findings use stable UPG000–UPG012 codes linked to the complete migration guide. Upgrade blockers return 2, execution or verification failures return 1, and cancelled application returns 130.