pi-cloudmanager

rclone integration for the pi coding agent — browse, read, copy, sync, move and delete files across any rclone remote (OneDrive, S3, SFTP, Google Drive, Dropbox, WebDAV, …).

Status: npm-installable pi package (TypeScript, loaded natively by pi — no build step). The rclone CLI does the heavy lifting; this extension wraps it with typed, safety-gated tools.

Why rclone instead of a bespoke API client?

rclone already provides 80+ storage backends, credential handling, and a battle-tested transfer engine. This extension deliberately does not re-implement any of that. It:

• exposes rclone's remotes as first-class, discoverable tools,
• adds safety gating (open / confirm / readonly) around destructive operations,
• adds footer status + a /rclone-doctor health check, consistent with your other pi extensions.

Installation

First install and configure rclone itself:

brew install rclone
rclone config          # add a remote, e.g. OneDrive
rclone listremotes     # confirm it shows up

Then install the extension:

pi install npm:pi-cloudmanager
# or from git:
pi install git:github.com/Lauritz30/pi-cloudmanager
# one-off session:
pi -e npm:pi-cloudmanager

Quick Start

1. Add a remote: rclone config → n (new remote) → name it e.g. onedrive → pick type onedrive → follow the OAuth flow.
2. Create ~/.pi/agent/pi-cloudmanager.json (optional — only holds policy, not credentials):

{
  "defaultRemote": "onedrive",
  "safetyLevel": "confirm"
}

3. Run /rclone-doctor to verify the binary, remotes, and connectivity.

Example configuration

{
  "defaultRemote": "onedrive",
  "safetyLevel": "confirm",
  "remotes": [
    { "name": "onedrive", "safetyLevel": "confirm" },
    { "name": "backup", "safetyLevel": "readonly" }
  ]
}

Remotes themselves always live in rclone's config file (~/.config/rclone/rclone.conf, or $RCLONE_CONFIG). The remotes array in pi-cloudmanager.json is only a per-remote policy overlay — it never stores credentials.

Tools

Read

| Tool | Description | | --- | --- | | rclone_doctor | Check binary, config, remotes, and connectivity | | rclone_list_remotes | List configured remotes (the available sources) | | rclone_list_dirs | List directories (folders only) | | rclone_list | List files/dirs with size & modtime; recursion, depth, include/exclude | | rclone_cat | Read a file's content (optional byte range) | | rclone_size | Object count and total bytes under a path | | rclone_about | Storage quota/usage (when the backend supports it) | | rclone_config_show | Show rclone config with secrets obfuscated |

Write (safety-gated)

| Tool | Description | | --- | --- | | rclone_mkdir | Create a directory | | rclone_copy | Copy source → destination (non-destructive) | | rclone_move | Move source → destination (deletes source after transfer) | | rclone_sync | Make destination an exact mirror of source (destructive) | | rclone_delete_file | Delete a single file | | rclone_delete | Delete all files under a path (optional --rmdirs) | | rclone_purge | Delete a directory and all its contents |

Every write tool supports dryRun: true to preview the exact command without executing it.

Commands

| Command | Description | | --- | --- | | /rclone-status | Show current status (binary, active remote, safety level) | | /rclone-doctor | Check installation, config, remotes, and connectivity |

Prompt templates

| Template | Description | | --- | --- | | /rclone-find | Locate files across remotes | | /rclone-backup | Back up the current project to a remote | | /rclone-transfer | Move/copy/sync between remotes and local |

Safety model

Three levels, mirroring your other extensions:

| Level | Behaviour | | --- | --- | | readonly | All write tools are blocked. | | confirm | Write tools prompt for approval via the UI; without a UI they are blocked unless a headlessApprovals rule matches. | | open | Write tools run without prompting. |

Set the level globally with safetyLevel, or per remote via the remotes array. A remote can additionally restrict writes to allowedRoots path prefixes — mutations outside those prefixes are always blocked.

Headless write approvals

In confirm mode, writes from a non-interactive run are blocked unless a matching rule exists:

{
  "defaultRemote": "onedrive",
  "safetyLevel": "confirm",
  "remotes": [
    {
      "name": "onedrive",
      "headlessApprovals": [
        { "action": "rclone_copy", "paths": ["backups"] },
        { "action": "rclone_sync", "paths": ["site"] }
      ]
    }
  ]
}

A rule matches when action equals the tool name, remote (if set) equals the target remote, and paths (if set) contains the target path. Paths match on prefix: "backups" matches backups/project-2024.

Configuration reference

~/.pi/agent/pi-cloudmanager.json

| Key | Type | Default | Description | | --- | --- | --- | --- | | defaultRemote | string | — | Remote used when a tool call omits remote. | | safetyLevel | string | "confirm" | Global default: "open", "confirm", or "readonly". | | mock | boolean | false | Skip live connectivity checks in rclone_doctor. | | remotes | array | [] | Per-remote policy overlays: { name, safetyLevel?, allowedRoots?, headlessApprovals? }. |

Environment variables:

| Variable | Purpose | | --- | --- | | RCLONE_BINARY | Override the rclone binary path. | | RCLONE_CONFIG | Override the rclone config file location (handled by rclone itself). |

Development

npm install
npm test
npm run check

Run against a local checkout from anywhere with:

pi install /absolute/path/to/pi-cloudmanager
# or, for a one-off session:
pi -e /absolute/path/to/pi-cloudmanager

Requirements

• Node.js 22.19+
• pi coding agent
• rclone CLI on $PATH

License

MIT — see LICENSE.