# s3-empty-bucket

> Library and CLI to quickly empty AWS S3 buckets.

Latest version **1.0.0-alpha.8** (published 2024-03-15) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install s3-empty-bucket
pnpm add s3-empty-bucket
yarn add s3-empty-bucket
bun add s3-empty-bucket
```

Provides the command `s3-empty-bucket`.

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.0-alpha.8 |
| Published | 2024-03-15 |
| First published | 2024-02-29 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=18.0.0 |
| Dependencies | 0 |
| Unpacked size | 33.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Zane Rockenbaugh |
| Maintainers | zanerock |
| Keywords | bucket, clean, empty, flush, s3, truncate |

## Links

- npm: https://www.npmjs.com/package/s3-empty-bucket
- Repository: https://github.com/liquid-labs/s3-empty-bucket
- Homepage: https://github.com/liquid-labs/s3-empty-bucket#readme
- Issues: https://github.com/liquid-labs/s3-empty-bucket/issues
- npm.io page: https://npm.io/package/s3-empty-bucket

## Alternatives

- [@mce/gif](https://npm.io/package/@mce/gif.md) — 2.6K weekly downloads
- [cleanse](https://npm.io/package/cleanse.md) — 173 weekly downloads
- [str](https://npm.io/package/str.md) — 127 weekly downloads
- [naming](https://npm.io/package/naming.md) — 95 weekly downloads
- [tap-telco-api](https://npm.io/package/tap-telco-api.md) — 19 weekly downloads

## Recent versions

- 1.0.0-alpha.8 (latest) — 2024-03-15
- 1.0.0-alpha.7 — 2024-03-12
- 1.0.0-alpha.6 — 2024-03-01
- 1.0.0-alpha.5 — 2024-03-01
- 1.0.0-alpha.4 — 2024-03-01
- 1.0.0-alpha.3 — 2024-03-01
- 1.0.0-alpha.2 — 2024-03-01
- 1.0.0-alpha.1 — 2024-02-29

## README

# s3-empty-bucket

___DO NOT USE FOR THE MOMENT.___ [There's a bug](https://github.com/liquid-labs/s3-empty-bucket/issues/21) in the code that may result in excessive API calls. We will address later today.

Special notice ends.

--------

Library and CLI to quickly empty AWS S3 buckets.

While we expect this library to work in most cases, it has not been extensively tested. However, we actively support this library so please [submit any issues](https://github.com/liquid-labs/s3-empty-bucket/issues) and we'll be happy to look into it.

- [Installation](#installation)
- [Usage](#usage)
- [API reference](#api-reference)
- [CLI command reference](#cli-command-reference)
- [Contributing](#contributing)
- [Support and feature requests](#support-and-feature-requests)

## Installation

To install the library:
```bash
npm i --omit peer s3-empty-bucket # peer deps only needed for CLI
```

To install the CLI (globally):
```bash
npm i -g s3-empty-bucket
```

## Usage

### Library

```javascript
import { S3Client } from '@aws-sdk/client-s3'
import { fromIni } from '@aws-sdk/credential-providers'

import { emptyBucket } from 's3-empty-bucket' // ES6
// const { emptyBucket } = require('s3-empty-bucket') // cjs

// following works with API keys, include the profile when using SSO sessions
const credentials = fromIni(/* { profile : ssoProfile }*/)
const s3Client = new S3Client({ credentials })

emptyBucket({ bucketName, s3Client, verbose: false })
```

### CLI

```bash
# following works with API keys, include the profile when using SSO sessions
s3-empty-bucket my-bucket-name # --profile your-sso-profile
```
##  API Reference
_API generated with [dmd-readme-api](https://www.npmjs.com/package/dmd-readme-api)._

<a id="emptyBucket"></a>
### `emptyBucket(options)`

Empties AWS S3 bucket.


| Param | Type | Description |
| --- | --- | --- |
| options | `object` | The destructured options object. |
| options.bucketName | `string` | The name of the bucket to empty. |
| options.doDelete | `boolean` | If true, then deletes the bucket after emptying it. |
| options.s3Client | `object` | Authenticated `S3Client`. |
| options.verbose | `boolean` | When true, will report actions to `process.stdout`. |


[**Source code**](./src/lib/s3-empty-bucket.mjs#L11)

## CLI command reference

### Usage

`s3-empty-bucket <options> [bucketName]`

### Options

|Option|Description|
|------|------|
|`[bucketName]`|(_main argument_,_required_) The name of the bucket to empty.|
|`--delete`|Deletes the bucket after emptying it.|
|`--document`|Generates command line documentation in Markdown format. All other options are ignored.|
|`--help`, `-?`|Prints command help.|
|`--profile`, `-p`|The SSO profile to use.|
|`--quiet`, `-q`|Suppresses output.|
|`--throw-error`|Instead of printing simple message, allows exceptions to bubble up to the user.|



## Contributing

Plase feel free to submit any [bug reports or feature suggestions](https://github.com/liquid-labs/s3-empty-bucket/issues). You're also welcome to submit patches of course. We don't have a full contributors policy yet, but you can post questions on [our discord channel](https://discord.gg/QWAav6fZ5C). It's not monitored 24/7, but you should hear back from us by next business day generally.

## Support and feature requests

The best way to get free support is to [submit a ticket](https://github.com/liquid-labs/s3-empty-bucket/issues). You can also become a patron for as little as $1/month and get priority support and request new feature on [all Liquid Labs open source software](https://github.com/liquid-labs). You can get these benefits and [support our work at patreon.com/zanecodes](https://www.patreon.com/zanecodes).

---
_Source: https://npm.io/package/s3-empty-bucket · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._