User guide

BucketDeck is a web portal for the S3 buckets your organization has connected. Open the portal URL your administrator gave you and sign in with your company account. You see the connections (AWS accounts) and buckets an administrator granted you; what you may do in each is shown as permissions (read, write, delete, manage, share) and greyed-out actions explain what's missing.

The top bar has Explorer, Search, Transfer, Jobs, Templates and Lens. Press ? for keyboard shortcuts. The portal also works on phones and tablets.

Some features depend on your organization's plan (Starter, Team, Business or Enterprise). A feature the plan doesn't include shows a plan badge, for example Team or Business, and says what it needs. This guide notes the plan next to each such feature.

#Your AWS access

If your administrator enabled it, the Explorer sidebar has Your AWS access. Use it to work with your own AWS permissions, the same ones you have in the AWS console:

• Connect with SSO (IAM Identity Center): choose Open the AWS access portal, check that the code shown matches, and choose Allow. Your accounts and permission sets appear under Connections as Your permission set.
• Sign in with keys (IAM user): enter your access key ID and secret access key, plus your MFA device and code if your policies require MFA. BucketDeck exchanges them for temporary credentials and doesn't store the keys. Your IAM user appears as Your IAM user.

What you can do there is decided by AWS, not by BucketDeck. Choose the sign-out icon next to a method to disconnect; sessions also end on their own when they expire.

#Explorer

• Navigate with the folder tree, the breadcrumb path (Ctrl + L to type a path such as my-bucket/logs/2024/), Backspace to go up and Alt + ← → for back and forward. Star a folder to add it to Favorites.
• Large folders load page by page and are cached, so returning to a folder with hundreds of thousands of objects is instant. The status bar says when the listing was cached; F5 refreshes it from S3. Type / to filter the current folder.
• Select with click, Shift/Ctrl + click, Space or Ctrl + A. The details panel (Ctrl + I) shows size, storage class, encryption, metadata, tags, versions, Object Lock and restore state, plus the S3 URI, ARN and a link to the AWS console.
• Actions (when your permissions allow):
  • Upload files or whole folders by drag and drop; large files upload in parallel parts, keep going for hours (part links are renewed as needed) and can be cancelled. If the bucket isn't set up for browser uploads, ask someone with manage on it to choose Enable browser uploads in the bucket details.
  • New folder, Rename (F2, objects up to 5 GiB; use a move job for folders or larger objects), Delete (Delete; with versioning you can also delete specific versions).
  • Download a file, or a selection as a ZIP (an archive job for larger selections; ZIP downloads are part of Business and above).
  • Copy link: a presigned URL valid for minutes (up to an hour). With the share permission (Team and above) you can create a share link that lasts longer (up to the maximum your admin set, 7 days by default): anyone with the link can download the file until it expires, you revoke it, or you lose access to the file yourself. Every use is recorded. Shares lists your links and their use counts, and lets you revoke them.
  • Storage class, Restore from Glacier classes, Tags and Metadata (with manage). Changing the storage class of, or restoring, several objects or a folder at once is part of Business and above.
  • Copy / cut and paste (Ctrl + C, Ctrl + X, Ctrl + V) opens the transfer wizard with the selection as the source and the current folder as the destination.

#Previews

Press Enter or double-click a file. BucketDeck shows:

Other files, and files over the size limit, show their details and a download button.

#Search

Search finds objects by name or key under any bucket or prefix you can read.

• Match: contains (default), prefix, exact, glob (*, ?, **) or regex; on the file name or the whole key; optionally case sensitive.
• Filters: extensions, categories (images, documents, data, archives, ...), size range, modified date range, storage classes.
• Source: Live lists S3 under the prefix and shows results as they arrive (keep it running for very large prefixes). Index (Business and above) searches the bucket's latest Lens index in seconds, even across millions of objects. Auto uses the index when one younger than 24 hours covers the prefix.

Select results to download, copy, move or delete them, or to start a transfer.

#Transfer

The transfer wizard runs jobs: copy, move, delete, change storage class, restore, and archive (ZIP). Jobs run in the background in your AWS account and can process millions of objects; you can close the browser. Storage class, restore and archive jobs are part of Business and above, and a job on Starter covers up to 10,000 objects.

1. Source: a connection, bucket and prefix, or the objects you selected. Choose whether to include subfolders.
2. Filters (optional): include and exclude patterns (*.csv), a regular expression, extensions, categories, size, modified dates and storage classes.
3. Destination (copy and move): a connection, bucket and prefix, in the same or another account.
4. Rename rules (optional, Team and above): see below. The preview shows the old and new key of sample objects as you edit, and flags conflicts and errors.
5. Options:
   • Overwrite: always, never (skip existing), if newer, or if different (size or ETag);
   • Conflicts (two sources map to one destination): fail, skip, or add a suffix (-1, -2, ...);
   • storage class, encryption, ACL bucket-owner-full-control for cross-account copies, whether to keep metadata and tags, and parallelism;
   • for delete jobs, whether to delete all versions.
6. Review: start a dry run to see exactly what would happen (counts and the planned keys), or start the job. Save as template (Team and above) keeps the whole definition for later.

#Rename rules

Team and above. Rules rewrite each object's key. By default they apply to the part of the key below the source prefix (relative mode), and the destination prefix is added in front; full mode applies them to the whole source key. Rules run in order; a rule with a when pattern (regular expression) runs only on matching keys.

Example: hive partitions to a date path. Objects such as

USDARSfix/corrected/year=2024/month=1/day=5/hour=7/part-0001.csv

should be copied as

2024/01/05/07/part-0001.csv

Choose source prefix USDARSfix/corrected/ (relative mode removes it), destination prefix empty, and one Hive to path rule with keys year,month,day,hour and zero-padding on: year=2024/month=1/day=5/hour=7/ becomes 2024/01/05/07/ (year padded to 4 digits, the others to 2). The preview shows the full mapping before you start:

USDARSfix/corrected/year=2024/month=1/day=5/hour=7/part-0001.csv  ->  2024/01/05/07/part-0001.csv

The same can be done with one Regex rule, year=(\d{4})/month=(\d{1,2})/day=(\d{1,2})/hour=(\d{1,2})/ → $1/$2/$3/$4/, but only Hive to path pads 1 to 01.

A key that would end up empty, start with /, contain // or exceed 1,024 bytes is reported as an error for that object; the others continue.

#Jobs

Jobs lists your jobs (admins can also see everyone's). Each job shows its status (QUEUED, PLANNING, RUNNING, FINALIZING, then SUCCEEDED, PARTIAL or FAILED; or CANCELLED), progress (objects and bytes planned, done, skipped and failed) and its options.

• Cancel stops a running job within seconds; work already done stays done.
• Failures lists the failed keys and why; Download report gives the full CSV.
• Retry failures starts a new job for the failed keys only.
• Preview (dry runs and planned jobs) shows the planned source and destination keys.
• A badge in the top bar shows jobs in progress; you get a notice when one finishes.

Job files (plans, reports, archives) are kept for 30 days (archives 7 days).

#Templates

Team and above. Templates keeps job definitions: a nightly copy to another account, a cleanup of a scratch prefix, a standard rename. Run a template with one click (it starts a new job with the saved settings), edit it, or share it with everyone. Templates you didn't create can be run but only their owner or an admin can change them.

#Lens

Business and above. Lens shows what is in a bucket or prefix: object count and size by storage class, category, extension, top-level prefix, size band, age and month, and the largest and oldest objects, plus the bucket's daily CloudWatch storage metrics. Choose Scan to build or refresh the snapshot; it runs as an index job, and the result also powers Index search. Use it to find what to archive, what to move to a cheaper storage class, and where the space goes.