# Install and First Run

Pi Toolbelt is a Pi package plus a local CLI.

## Install from npm

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

After install, ask Pi:

```text
Check Toolbelt status and show me the provider categories.
```

Expected first checks:

```bash
pi-toolbelt status --json --agent human
pi-toolbelt inventory --json --agent human
pi-toolbelt catalog-check --json --agent human
```

## Install from GitHub/source

```bash
pi install git:github.com/apsisvictor-sys/pi-toolbelt
```

For local development, do not run nested Pi from inside a Pi agent shell. From a normal terminal, use:

```bash
cd /path/to/pi-toolbelt
npm test
npm run smoke
npm run audit:secrets
pi -e ./extensions/toolbelt/index.ts
```

## Ask Pi to install a provider CLI

Toolbelt wraps local CLIs. If a provider CLI is missing, ask Pi to install it using the vendor-recommended path.

Examples:

```text
Install the official GitHub CLI, verify gh --version, guide me through gh auth login if needed, then run Toolbelt status for github.
```

```text
Install the official Vercel CLI, verify it works, and configure Toolbelt to expose safe Vercel read operations.
```

```text
Install the Stripe CLI, verify authentication status, and show me which Stripe operations Toolbelt classifies as read-only vs approval-gated.
```

Good install flow:

1. Detect OS and package manager.
2. Install the official CLI from vendor docs.
3. Run `<cli> --version`.
4. Guide login with the provider CLI, not through chat secrets.
5. Run a read-only provider status check.
6. Use Toolbelt inventory/status to confirm the provider is available.

## First commands

List every provider in the catalog:

```bash
pi-toolbelt inventory --json --agent human
```

List one category:

```bash
pi-toolbelt inventory --category hosting --json --agent human
```

Inspect one provider:

```bash
pi-toolbelt status --provider github --json --agent human
```

Call a read operation:

```bash
pi-toolbelt call --provider github --operation status --json --agent human
```

Mutating operations are approval-gated:

```bash
pi-toolbelt call --provider vercel --operation deploy --json --agent human
```

To actually run a mutating operation, a user must explicitly approve and include a reason:

```bash
pi-toolbelt call --provider vercel --operation deploy --confirm-mutating --reason "Deploy approved by user" --json --agent human
```

## Add a custom provider

Copy the example:

```bash
mkdir -p ~/.config/pi-toolbelt/providers
cp examples/providers/custom-cli.json ~/.config/pi-toolbelt/providers/my-service.json
```

Edit it to match your CLI. Then validate:

```bash
pi-toolbelt catalog-check --json --agent human
pi-toolbelt status --provider my-service --json --agent human
```

You can also point Toolbelt at a temporary provider directory:

```bash
PI_TOOLBELT_PROVIDER_DIR=/path/to/providers pi-toolbelt inventory --json --agent human
```

## No CLI exists?

Generate or build one first, then wrap it with Toolbelt.

Recommended options:

- CLI-Anything: https://github.com/HKUDS/CLI-Anything
- CLI-Anything Web: https://github.com/ItamarZand88/CLI-Anything-WEB
- OpenAPI-to-CLI generators when the provider has a clean OpenAPI spec

Ask Pi:

```text
This service has an API but no official CLI. Use CLI-Anything or an OpenAPI CLI generator to create a local CLI with JSON output, then add a Toolbelt provider definition for safe read operations and approval-gated mutations.
```

## Troubleshooting

### Provider CLI is missing

Run:

```bash
pi-toolbelt status --provider <id> --json --agent human
```

Toolbelt returns install guidance from the provider catalog.

### Auth is missing

Run the provider CLI's login command directly. Toolbelt does not collect provider credentials in chat.

### Catalog validation fails

Run:

```bash
pi-toolbelt catalog-check --json --agent human
```

Fix invalid provider definitions. Duplicate provider IDs are blocked so custom providers cannot silently override built-ins.