# Pi Toolbelt

![Pi Toolbelt social preview](docs/social-card.png)

Agent-safe control plane for local CLIs in [Pi](https://pi.dev).

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

```bash
pi install npm:@pixeldevv/pi-toolbelt
```

Development checkout:

```bash
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](docs/install.md) for local CLI setup, custom providers, and CLI-Anything generation paths.

## First 30 seconds

Ask Pi:

```text
Check which Toolbelt providers are available.
```

Or run the CLI directly:

```bash
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:

```text
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](docs/architecture.md).

## 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](docs/official-clis.md).

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

```text
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](docs/custom-providers.md) and [CLI-Anything](https://github.com/HKUDS/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](SECURITY.md).

## Product roadmap

- [x] Provider registry for official/local CLIs
- [x] Built-in catalog for common official CLIs and API-generation targets
- [x] Custom provider definitions
- [ ] Conversational CLI installation through Pi
- [x] 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](CONTRIBUTING.md).

## License

MIT