Download the PHP package knlab/pb-migrate without Composer

pb-migrate

日本語版 / Japanese

Command-line tool to manage existing AIML packages on Pandorabots, built on top of spontena/pb-php.

pb-migrate is the OSS rewrite of an in-house deployment CLI. The tool treats your local AIML files as the source of truth, registers existing package directories, and pushes them to Pandorabots' Developer Portal API.

Concepts

• Local registration is the source of truth. A bot must be registered locally (pb-migrate add) before it can be operated on remotely. Pandorabots-side state never authoritatively drives the local config.
• One project = one app_id. A pb-migrate.json file describes a project; all bots under it share one Pandorabots application ID. Multi-app_id setups are out of scope.
• Credentials live in .env, structure in pb-migrate.json. The JSON file is committable; the .env is gitignored. Both can be edited by the tool.
• Default push is destructive. It rewrites the remote bot to match local. Pass --keep-remote-only to opt out.

Features

• add / remove — register or unregister an existing AIML package directory
• config — interactively edit credentials (.env) for project or per-bot bot_keys
• bot:list — show registered bots (local, no API call)
• bot:remote — show bots on the Pandorabots account, annotated with registration state
• bot:create / bot:delete / bot:files — remote bot lifecycle (require local registration)
• compile — verify bots on Pandorabots
• push — upload local files (destructive: rewrites remote to match local)
• pull — download remote files into the local directory
• diff — show file-level changes (UPD/ADD/DEL grouped, color-coded)
• report — rich handoff report of pending changes
• status — local sync state vs. cache (no API)
• cat / file:delete — inspect or delete a single remote file
• talk / debug / atalk — converse with a bot from the terminal
• test — assert bot replies match expected outputs
• batch — run a runbook of pb-migrate commands
• alter:list / alter:set / alter:unset / alter:reset — persistent file-body overrides for debug-session probes
• Run pb-migrate with no arguments to drop into an interactive REPL

Requirements

• PHP 8.1+
• ext-json
• Composer

Installation

Install globally:

Make sure ~/.composer/vendor/bin (or the equivalent for your Composer setup) is on your $PATH.

Or pin it inside a project:

Quickstart

Configuration

pb-migrate.json holds the project structure (no credentials):

The $schema URL points at the published JSON Schema. VS Code, JetBrains IDEs, and most JSON-aware editors pick it up automatically — autocomplete on field names, hovers explaining what each field does, and instant warnings on typos like directry or invalid propertiesUpload values.

Per-bot fields:

Bot names must be alphanumeric (Pandorabots constraint).

Credentials (.env, tool-managed)

The tool writes a project-local .env (gitignored) using block markers so user-managed lines are preserved:

Edit via:

The interactive prompts show the current value; press Enter to keep it, type a new value to update, or type - to clear an optional field.

A note on atalk and bot_keys

atalk (anonymous talk) requires a per-bot bot_key. Pandorabots issues bot_keys through their dashboard UI (developer.pandorabots.com), not through the Developer Portal API.

Heads-up: bots created via the API (pb-migrate bot:create, or anything else hitting PUT /bot/...) do not appear in the dashboard's bot list during the API trial / Developer Portal tier we tested against. There seems to be no API endpoint that returns the bot_key either. The practical consequence: if you want atalk to work, create the bot on the dashboard first and pb-migrate add it locally, rather than using bot:create to spin it up via the API.

talk and debug use the regular user_key authentication and work fine for either path.

Commands

For --bot, a glob pattern (prod.*) is accepted in addition to an exact bot name. --all operates on every registered bot.

Push semantics

push is destructive by default: it rewrites the remote bot to match local. Files that exist on the remote but not locally are deleted. This matches the "local is source of truth" model — what's on disk is what should be on the bot.

To preserve remote-only files (e.g. files added via the Pandorabots dashboard by other team members), pass --keep-remote-only.

Pandorabots-managed files like udc are never deletable (412 from the API); pb-migrate skips them with a warning regardless of mode.

Diff and report

diff shows file-level changes only — which files differ, in what category — without inline content diffs:

report produces a richer document suitable for handoff notes / PR descriptions:

Both default to comparing against live remote. Pass --since=cache on report to compare against the local cache instead (no API call) — useful for seeing what changed locally since the last push/pull.

Persistent alters (debug-session probes)

--override is great for one-shot tweaks. For longer investigative sessions where you want a few debug probes (a category that dumps internal predicates, one that simulates state, etc.) to re-apply on every push, register them as persistent alters:

alter:list flags missing override paths with [missing!] so a session in flight is visible at a glance.

⚠️ Persistent alters live in pb-migrate.json, which is typically committed. Run alter:reset before merging your config back into a shared branch — alters are meant to leave no trace once the debug session is over.

Local cache

To avoid re-fetching every remote file on every push / diff, pb-migrate maintains a JSON cache (.pb-migrate-cache.json, gitignored) of the SHA-256 of each file at the time of the last successful push or pull. Pass --verify-remote to bypass the cache when you suspect dashboard edits or cache corruption.

Testing the code

The integration suite hits the real Pandorabots API and is not run by default. Provide credentials and select the integration suite explicitly:

CI runs the unit suite on PHP 8.1 / 8.2 / 8.3 / 8.4 — see .github/workflows/ci.yml.

License

MIT — see LICENSE.