# Custom Providers

A Toolbelt provider tells Pi how to use an installed local CLI safely.

Toolbelt should not require users to wait for a built-in adapter. If a useful CLI exists on the machine, users should be able to define a provider and let Toolbelt enforce policy around it.

## What a provider definition needs

A provider definition should answer:

- What is the provider called?
- Which executable should Toolbelt call?
- How does Toolbelt verify it is installed?
- Which operations are read-only?
- Which operations are mutating and require approval?
- Which operations are destructive and blocked?
- How should output be parsed?
- Which values must be redacted?
- What timeout/concurrency limits apply?

## Example shape

```json
{
  "id": "example-service",
  "label": "Example Service",
  "executable": "example",
  "install": {
    "macos": "brew install example",
    "linux": "curl -fsSL https://example.com/install.sh | sh",
    "windows": "winget install Example.ExampleCLI"
  },
  "auth": {
    "mode": "external-cli",
    "loginCommand": "example login",
    "statusCommand": "example whoami --json",
    "credentialsStayLocal": true
  },
  "operations": {
    "status": {
      "risk": "read",
      "command": ["status", "--json"]
    },
    "list-projects": {
      "risk": "read",
      "command": ["projects", "list", "--json"]
    },
    "deploy": {
      "risk": "mutating",
      "requiresApproval": true,
      "command": ["deploy", "--json"]
    },
    "delete-project": {
      "risk": "blocked",
      "reason": "Destructive project deletion is intentionally not exposed to agents."
    }
  },
  "redaction": {
    "secretKeys": ["token", "apiKey", "password", "authorization", "cookie"],
    "secretValuePatterns": ["sk-[A-Za-z0-9_-]+"]
  }
}
```

## Ask Pi to add a provider

Users should be able to say:

```text
Add Toolbelt support for the official Render CLI. Install it if missing, verify auth, then create a safe provider definition with read-only status/list/log operations and approval-gated deploy/restart operations.
```

Pi should then:

1. Read Toolbelt docs.
2. Detect whether the CLI exists.
3. Install it using official instructions if the user approves.
4. Run a version check.
5. Guide CLI login if needed.
6. Inspect `--help` output.
7. Draft a provider definition.
8. Run safe status/list operations.
9. Confirm no credentials appear in output.

## Good defaults

- Default to read-only operations.
- Return JSON when the CLI supports it.
- Prefer CLI operations that return IDs, counts, statuses, URLs, and bounded machine-readable output over huge raw payloads.
- Treat logs as potentially sensitive; truncate and redact.
- Never expose secret values, even for secret-management CLIs. Secret names and metadata are enough.
- Require explicit user approval and a reason for mutating operations.
- Block destructive delete/reset/purge operations until a human decides to expose them.

## Generated CLIs

If a service has no official CLI, generate or build one first. Recommended path:

1. Use CLI-Anything for applications and services that need an agent-native CLI: https://github.com/HKUDS/CLI-Anything
2. Use CLI-Anything Web for web apps where traffic capture is appropriate: https://github.com/ItamarZand88/CLI-Anything-WEB
3. Use an OpenAPI-to-CLI generator when the provider has a clean OpenAPI spec.
4. Add `--json` output and tests to the generated CLI.
5. Wrap the generated CLI with Toolbelt policy.

Toolbelt is the safety and policy layer. The CLI is the capability layer.