Pi Toolbelt

Agent-safe control plane for local CLIs in Pi.

Pi Toolbelt lets agents use your already-authenticated local CLIs safely. Auth stays where it belongs — in the official CLI, OS keychain, local config, or environment — while Toolbelt gives Pi policy-gated JSON envelopes with redacted CLI output.

Why this exists

Agents often need to check deploys, repos, billing metadata, email status, logs, cloud resources, incidents, databases, and product APIs. Doing that through ad hoc shell commands makes safety policy inconsistent and risks exposing credentials in prompts or terminal output.

Pi Toolbelt gives agents one local interface with:

• Official CLI wrapping for services with mature CLIs: GitHub, Vercel, Railway, Render, Netlify, Fly.io, AWS, GCP, Azure, Stripe, Sentry, Tailscale, Cloudflare, Supabase, Firebase, and many more.
• Custom provider definitions for any installed CLI.
• CLI generation path through CLI-Anything when a provider has no useful CLI yet.
• Secret-safe operation: credentials stay in local CLIs/auth stores; Toolbelt rejects secret-shaped inputs and redacts secret-shaped output.
• Approval-gated mutations: mutating operations are classified and require explicit user approval.
• Auditable JSON envelopes so Pi receives provider results through one policy layer instead of ad hoc shell calls.
• Pi-native install via pi install npm:@pixeldevv/pi-toolbelt.

Install

pi install npm:@pixeldevv/pi-toolbelt

Development checkout:

git clone https://github.com/apsisvictor-sys/pi-toolbelt.git
cd pi-toolbelt
npm test
pi -e ./extensions/toolbelt/index.ts

See Install and First Run for local CLI setup, custom providers, and CLI-Anything generation paths.

First 30 seconds

Ask Pi:

Check which Toolbelt providers are available.

Or run the CLI directly:

pi-toolbelt status --json --agent human
pi-toolbelt inventory --json --agent human
pi-toolbelt inventory --category cloud --json --agent human
pi-toolbelt status --provider github --json --agent human
pi-toolbelt catalog-check --json --agent human
pi-toolbelt audit-secrets --json --agent human

How it works

Toolbelt is a policy gateway between Pi and local CLIs:

Pi agent → Toolbelt extension → pi-toolbelt CLI → official/local provider CLI → provider API

The provider CLI owns login and credentials. Toolbelt owns agent safety: operation classification, redaction, approval gates, JSON envelopes, and audit hooks.

See Architecture.

Supported CLI ecosystem

Toolbelt is designed for the whole official-CLI and official-API ecosystem, not one fixed provider list. The package includes a provider registry covering major cloud, deploy, source control, CI/CD, observability, payments, auth, databases, messaging, AI APIs, infrastructure, CMS, media, and product tools. See the Official CLI Catalog.

If a CLI is missing, ask Pi to install it:

Install the official Railway CLI, verify it works, guide me through login if needed, and configure Toolbelt to use it safely.

If the service has no official CLI, generate or build one first, then wrap it with Toolbelt. See Custom Providers and CLI-Anything.

Security model

Pi packages run with local user permissions. Review source before installing any package, including this one.

Pi Toolbelt's public contract:

1. Secret-shaped arguments are rejected.
2. Authentication material stays in local CLIs/auth stores, not in prompts.
3. Secret-shaped CLI output is redacted before Toolbelt returns results to Pi.
4. Provider output is returned inside a structured JSON envelope for agent use.
5. Mutating provider operations must be approval-gated.
6. Destructive operations should be blocked or double-gated.

See SECURITY.md.

Product roadmap

• Provider registry for official/local CLIs
• Built-in catalog for common official CLIs and API-generation targets
• Custom provider definitions
• Conversational CLI installation through Pi
• CLI-Anything integration guide for generated CLIs
• Redacted ledger with temp-home tests
• Provider conformance tests
• Demo video for pi.dev package gallery

Contributing

Provider definitions, install notes, and safety-focused improvements are welcome. See CONTRIBUTING.md.

License

MIT