Pi Port

Export and import your pi agent configuration between machines — settings, auth, trusted dirs, skills, git packages, and optionally memory/sessions — as a single portable .pi-backup archive.

The npm package cache (~/.pi/agent/npm/, often 400MB+) is never copied: packages are recorded as a list in settings.json and reinstalled automatically on the target's first pi run. A typical backup is under 10MB.

Install

pi install npm:@andrewjacop/pi-port          # from npm
# or
pi install git:github.com/andrewjacop/pi-port@v0.1.0

Both commands (/export-pi, /import-pi) load automatically.

Usage

Export

/export-pi [path]

Runs an interactive wizard: resolves an output path (defaults to ~/pi-backups/pi-backup-<timestamp>.pi-backup, remembers your last location), auto-detects which sections exist, and asks whether to include each one. settings is always included; auth (API keys) warns when toggled on.

Import

/import-pi [path]

Reads the archive's manifest, validates format and checksums, then walks you through selecting which sections to restore. Absolute paths under the source machine's home are automatically rewritten to the target home (e.g. /Users/alice/... → /home/bob/...). Paths outside the source home (e.g. /opt/...) are left untouched.

Before overwriting settings.json, the current file is backed up to settings.json.preimport.bak.

Backup format

A .pi-backup file is a gzip-compressed tar containing:

manifest.json        # metadata, source machine, section list, sha256 checksums
settings.tar         # one inner tar per exported section
trust.tar
skills.tar
...

manifest.json:

{
  "format": "pi-backup",
  "version": 1,
  "createdAt": "2026-07-06T09:55:00Z",
  "source": { "os": "darwin", "username": "alice", "home": "/Users/alice", "hostname": "macbook" },
  "sections": ["settings", "trust", "skills"],
  "checksums": { "settings.tar": "sha256:..." },
  "exportedBy": "pi-port@0.1.0"
}

The format is versioned. Importing a backup made by a newer Pi Port than you have installed fails with a clear upgrade message.

Sections

Section	Source	Default in export
settings	settings.json	✅ always
auth	auth.json	⚠️ opt-in (contains API keys)
trust	trust.json	✅
skills	skills/	✅
git-packages	git/	✅
bin	bin/	✅
memory	pi-hermes-memory/	❌ opt-in (large)
projects-memory	projects-memory/	❌ opt-in
sessions	sessions/	❌ opt-in (large)

Security

• auth.json contains your API keys in plaintext (same as pi stores them). Export warns twice; import defaults to including it but asks explicitly.
• Backups are written with mode 0600.
• Checksums are verified on import; mismatches are reported.
• No network access, no telemetry.

Platform support

• v0.1: macOS and Linux (uses the system tar binary).
• Windows: not yet supported — v0.2 will add a native tar fallback.

Development

git clone https://github.com/andrewjacop/pi-port
cd pi-port
npm install
npm test          # unit tests for path remapping
npx tsc --noEmit  # typecheck

Quick test without installing:

pi -e ./extensions/pi-port.ts

License

MIT