Folder sync is deliberately opt-in. Add named mappings in VS Code Settings, then run BucketBuddy: Sync Configured Folder…. Every run opens a preview and requires an explicit Apply Sync confirmation. Remote deletion is disabled by default.

"bucketbuddy.folderSyncMappings": [
  {
    "name": "Website assets → staging",
    "localPath": "${workspaceFolder}/public",
    "profile": "staging",
    "bucket": "my-staging-assets",
    "prefix": "web/",
    "include": ["*"],
    "exclude": ["*.map", ".DS_Store"],
    "deleteRemote": false
  }
]

The target bucket must be unlocked. Sync only transfers files selected by the filters; it does not watch folders or run automatically.

1. Install

Install from the VS Code Marketplace — search for AWS BucketBuddy in the Extensions panel, or visit getbucketbuddy.com.

2. Configure an AWS profile

BucketBuddy uses your existing AWS CLI profiles. If you haven't set one up:

aws configure
# or for SSO:
aws configure sso

3. Open the sidebar

Click the BucketBuddy icon in the Activity Bar. On first launch, the extension automatically connects every AWS profile found in your ~/.aws/credentials and ~/.aws/config files — no manual setup needed. Each profile appears as its own colour-coded root node with its configured buckets already pinned.

On subsequent launches, BucketBuddy restores the exact set of profiles that were active when VS Code last closed (respecting any profiles you manually disconnected).

4. Browse or go to a bucket

• Owned buckets are listed and the tree auto-expanded as soon as a profile connects, if your credentials have s3:ListAllMyBuckets — no manual click needed
• Pre-configured buckets from buckets= in your AWS config are pinned immediately
• Direct access — click the "Go to bucket…" icon on a profile row (or right-click → Go to Bucket…) and enter a bucket name or s3:// URL
• Every bucket starts locked (read-only) — see Read-Only Lock below

5. Connect an additional profile

Click the + icon in the panel header and select a profile. It appears as a new root node — each session has a distinct colour badge for easy identification.

Add a buckets= field to your AWS config and BucketBuddy will automatically pin those buckets when you connect the profile — no manual "Go to bucket…" needed each time:

[MyProfile]
aws_access_key_id     = ...
aws_secret_access_key = ...
region                = us-east-1
account_id            = 123456789012
buckets               = prod-data, staging-bucket, my-logs
env                   = DEV

The account_id field is also shown in the profile header for easy identification. env groups this profile under a "DEV" banner alongside every other profile that also sets env=DEV — see Environment Grouping below.

Add an env= field to any profile in your AWS config to group similar profiles under a banner — DEV, Staging, Prod, or any name you choose:

[dev-a]
env = DEV

[dev-b]
env = DEV

[prod-main]
env = Prod

Profiles sharing the same env value are grouped under one banner at the root of the tree. Recognized names (dev, staging, prod) are sorted first; other custom values sort alphabetically; profiles with no env set are grouped last under "Other". If you never set env on any profile, the tree renders flat exactly as before — this is fully opt-in.

Prefer not to edit your AWS config? Right-click any profile → "Set Environment/Group…" to assign it a group directly from the tree. This is stored locally by BucketBuddy only — it never reads or writes your ~/.aws/config file — and always wins over that file's env= value if both are set. Pick "Clear override" to fall back to whatever the config file says (or ungrouped, if nothing is set there either).

Every profile and bucket starts locked (read-only) to prevent accidental changes — especially useful for production accounts. Right-click a profile or bucket and choose Unlock (Allow Edits) to make it writable, or hover the row and click its lock icon (red closed padlock while locked, green icon while unlocked — a pencil for buckets, an open padlock for profiles); choose Lock (Read-Only) to re-lock it.

Buckets show that same red-padlock/green-pencil icon as their permanent main icon too, so status is visible without even hovering. Profile rows are color-coded instead (red = locked, green = unlocked, amber = mixed) since a profile's status is really an aggregate over all of its known buckets, not just its own setting — amber means some of its buckets are unlocked and some aren't, so you're never guessing whether "locked" on the profile means every bucket underneath it is locked too.

• Locking a profile locks every bucket under it, unless a bucket has been individually unlocked.
• Unlocking a single bucket overrides its profile's lock for that bucket only.
• Attempting a write (upload, delete, rename, create folder/file, restore version, copy-in) on a locked target shows a warning with an "Unlock Now" button — it only unlocks; you'll need to retry the action afterward, so a single click can never both unlock and delete/overwrite.
• Lock state is remembered across VS Code restarts and across every workspace.
• The default for anything you haven't explicitly locked/unlocked yet is controlled by bucketbuddy.lockByDefault (default true). Set it to false if you'd rather new profiles and buckets start unlocked — existing explicit choices per profile/bucket are never affected either way.

Bulk actions: the toolbar has Lock All Profiles and Unlock All Profiles. Unlock All requires confirmation and skips any protected profile (see below) — you'll be told which ones were skipped and can still unlock them individually.

Protected profiles: add glob patterns to bucketbuddy.protectedEnvPatterns (default ["prod*", "production*"], matched against a profile's env= value) or bucketbuddy.protectedProfilePatterns (matched against the profile name) to mark certain profiles/buckets as protected. Protection only changes what Unlock All does — a protected item is excluded from that bulk action (hover its tooltip to see why), but the individual lock/unlock toggle always still works on it, one at a time.

Activity log: every successful write is recorded — action, profile, bucket, and detail — in a dedicated BucketBuddy Activity output channel. Open it from the toolbar's Show Activity Log button.

No s3:ListAllMyBuckets permission? No problem. Use Go to bucket… to navigate directly to any bucket by name or s3:// URL — even cross-account buckets your credentials have been explicitly granted access to. BucketBuddy validates the bucket is accessible before confirming.

Click any S3 object — a dedicated Version History panel updates automatically showing all versions and delete markers. From the panel you can:

• Open any prior version in the VS Code editor
• Download a specific version
• Restore a prior version (promotes it to LATEST via a copy)

Requires the bucket to have versioning enabled.

Right-click any object → Copy to Another Profile…

1. Select the target profile (e.g. staging, prod)
2. Enter the target bucket name
3. Confirm (or edit) the target key

The object streams from the source account through VS Code to the target account — no server-side copy required, so it works seamlessly across AWS accounts, environments, and regions.

On a profile session node:

• Go to Bucket…
• Disconnect Profile
• Create Bucket
• Set Environment/Group…
• Lock (Read-Only) / Unlock (Allow Edits)

On an environment/group banner:

• Connect All in Group
• Disconnect All in Group

On a bucket:

• Upload File
• Create Folder
• Create File…
• Refresh Node
• Search Objects
• Copy S3 URI
• Open in AWS Console
• Download Folder
• Delete Folder
• Copy Folder…
• View Bucket Details
• Storage Insights
• List All Files…
• Run Permission Diagnostics
• Save Bucket Path…
• Lock (Read-Only) / Unlock (Allow Edits)

On a folder:

• Upload File
• Create Folder
• Create File…
• Refresh Node
• Search Objects
• Copy S3 URI
• Open in AWS Console
• Download Folder
• Delete Folder
• Copy Folder…
• Rename Folder…
• Storage Insights
• List All Files…
• Save Bucket Path…

On an object:

• Open in Editor
• Edit Object…
• Download
• Copy S3 URI
• Copy Pre-signed URL
• Copy as AWS CLI Command
• Copy as curl Command
• Open in AWS Console
• Rename / Move
• Copy to Another Profile…
• View/Edit Tags…
• View Object Properties
• View Object Lock
• Version History
• Delete

On a version (Version History panel):

• Open Version
• Download Version
• Compare with…
• Restore Version

Connect as many AWS profiles as you need — each appears as a collapsible root node with a distinct color badge (🔵 🟢 🟡 🟣 🟠 🔴) and shows the region and account ID from your config.

Useful when:

• You have buckets spread across dev, staging, and production accounts
• You need to compare or migrate objects between AWS accounts
• Your IAM role grants direct bucket access but not ListAllMyBuckets

Add a session: click + in the panel header, or ➕ Connect another profile… at the bottom Connect all: click the plug icon in the panel header to reconnect every profile at once Remove a session: right-click the profile node → Disconnect Profile Disconnect all: click the disconnect button in the panel header

First launch: all profiles in ~/.aws/credentials + ~/.aws/config are connected automatically. Subsequent launches: restores the profiles that were active when VS Code last closed. Sessions and pinned buckets are persisted — they reconnect automatically when you reopen VS Code.

• No credentials stored. BucketBuddy never persists access keys anywhere. Only profile names (plain strings) are saved across sessions.
• No network calls from WebViews. All AWS API calls run in the VS Code extension host.
• Credential chain per session: fromIni() → fromSSO() → fromProcess() — restricted to the selected AWS profile so ambient environment credentials cannot silently override it.

• VS Code 1.85.0 or later
• AWS CLI configured with at least one profile (aws configure)
• Node.js is not required — the extension bundles all dependencies