https://github.com/gagoar/alohomora
✨ A cli that makes using AWS Parameter Store... as simple as the flick of a wand 🧙
https://github.com/gagoar/alohomora
aws-ssm aws-ssm-agent cli ssm
Last synced: 12 days ago
JSON representation
✨ A cli that makes using AWS Parameter Store... as simple as the flick of a wand 🧙
- Host: GitHub
- URL: https://github.com/gagoar/alohomora
- Owner: gagoar
- License: mit
- Created: 2020-05-11T21:46:47.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2025-03-31T19:03:29.000Z (23 days ago)
- Last Synced: 2025-04-11T16:17:21.932Z (12 days ago)
- Topics: aws-ssm, aws-ssm-agent, cli, ssm
- Language: TypeScript
- Homepage:
- Size: 1.73 MB
- Stars: 16
- Watchers: 2
- Forks: 2
- Open Issues: 25
-
Metadata Files:
- Readme: readme.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
Alohomora
✨ A cli that makes using AWS Parameter Store... as simple as the flick of a wand 🧙
Explore the docs »
Report Bug
·
Request Feature
## Table of Contents
- [About the Project](#about-the-project)
- [Built With](#built-with)
- [Getting Started](#getting-started)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Usage](#usage)
- [Contributing](#contributing)
- [License](#license)
## About The Project
Many libraries deal with parameter store secrets. However, I didn't find one that suits my needs, so I created this one. I wanted to develop a library that will solve all my needs while using secrets, including exporting the key/secrets to different formats
Here's why:
- Many solutions require prefixes to store keys, making it difficult to migrate when needed.
- Support for exporting keys to widely accepted file formats such as JSON was limited.
### Built With
- [aws-sdk](https://github.com/aws/aws-sdk-js)
- [ora](https://github.com/sindresorhus/ora)
- [cli-table3](https://github.com/cli-table/cli-table3)
- [dateformat](https://github.com/felixge/node-dateformat)
- [commander](https://github.com/tj/commander.js/)
- [cosmiconfig](https://github.com/davidtheclark/cosmiconfig)
## Getting Started
Below is an example of instructions you can integrate into your own project's _Getting Started_ section. You can follow these simple steps to get a local copy up and running:
### Prerequisites
- Node 8 or higher
- AWS credentials to your account. ([more info here](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/loading-node-credentials-environment.html))
### Installation
If you wish to use `alohamora` as a standalone utility:
```sh
npm -g install alohomora
```
This will make the `alo` command available in your terminal.
```sh
alo --help
```
If instead you would like to add it to a package:
```sh
npm install --only=dev alohomora
```
## Usage
Every command accepts several options through command line or custom configuration [see configuration for more](#configuration)
### List secrets.
```sh
alo list --prefix my-company/my-app
```
### Get a secret.
```sh
alo get SECRET_KEY_NAME --prefix my-company/my-app
```
### Set/Update/Create a secret.
```sh
alo set SECRET_KEY_NAME VALUE --prefix my-company/my-app --environment development
```
### Delete a secret.
```sh
alo delete SECRET_KEY_NAME --prefix my-company/my-app --environment production
```
### Export secrets
```sh
alo export json --prefix my-company/my-app --environment production
```
## Configuration
You can configure `alohomora` from several places:
### CLI options
- **Prefix** (`--prefix`): The prefix used to store the keys (it should not start or end with a `/`, ex: if the path to the secret is `/my-app/[env]/secretName`, the prefix will be `my-app` )
- **AWS region** (`--aws-region`): The AWS region code where the secrets will be stored (https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions)', `default: us-east-1`
- **Environment** (`--environment`): It will be used to filter the secrets (production, staging, test, all), `default: all`
- **AWS Access Key ID** (`--aws-access-key-id`): Credentials following https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/loading-node-credentials-environment.html
- **AWS Secret Access Key** (`--aws-secret-access-key`): Credentials following https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/loading-node-credentials-environment.html
- **AWS Session Token** (`--aws-session-token`): Credentials following https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/loading-node-credentials-environment.html
- **AWS Profile** (`--aws-profile`): Following https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/loading-node-credentials-shared.html
- **CI flag** (`--ci`): Removes colors to avoid odd input. `default: false`
If you are using `alo` as a [global command](#installation), you can provide all the above options via command line:
```sh
alo list --prefix my-company/my-app --aws-region us-west-2 --aws-profile myCustomAWSProfile --environment production
```
for more details you can invoke:
```sh
alo --help
```
### Custom Configuration
You can also define custom configuration in your package:
```json
{
"name": "my-package",
"alohomora": {
"prefix": "my-company/my-app",
"environment": "production",
"region": "us-west-2"
},
"scripts": {
"secrets": "alo export"
},
"devDependencies": {
"alohomora": "^1.0.0"
}
}
```
When the command is invoked it will look for the `alohomora` configuration block.
```bash
(my-package)$ npm run secrets
```
Custom configuration can be defined in many places, for more information check [cosmiconfig](https://github.com/davidtheclark/cosmiconfig)
**notes about custom configuration**
- If `prefix` is provided via cli, the custom configuration will be ignored.
- If configuration is provided via the cli, custom configuration will be merged with the provided cli configuration (except `prefix`)
example with overrides:
```json
"alohomora": {
"prefix": "my-company/my-app",
"region": "us-west-2",
"environment": "development",
}
```
```bash
alo list --environment production
```
result: We will use everything from the custom configuration and use `environment` provided by the cli instead of the one on the custom configuration
example ignoring custom configuration:
```json
"alohomora": {
"prefix": "my-company/my-app",
"region": "us-west-2",
"environment": "development",
}
```
```bash
alo list prefix "my-other-company/my-other-app"
```
result: We will ignore custom configuration given that `prefix` was provided via cli.
## Roadmap
See the [open issues](https://github.com/gagoar/alohomora/issues) for a list of proposed features (and known issues).
## Contributing
Contributions are what makes the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated **greatly appreciated**.
1. Fork the Project
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the Branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## License
Distributed under the MIT License. See `LICENSE` for more information.
[contributors-shield]: https://img.shields.io/github/contributors/gagoar/alohomora.svg?style=flat-square
[contributors-url]: https://github.com/gagoar/alohomora/graphs/contributors
[forks-shield]: https://img.shields.io/github/forks/gagoar/alohomora.svg?style=flat-square
[forks-url]: https://github.com/gagoar/alohomora/network/members
[stars-shield]: https://img.shields.io/github/stars/gagoar/alohomora.svg?style=flat-square
[stars-url]: https://github.com/gagoar/alohomora/stargazers
[issues-shield]: https://img.shields.io/github/issues/gagoar/alohomora.svg?style=flat-square
[issues-url]: https://github.com/gagoar/alohomora/issues
[license-shield]: https://img.shields.io/github/license/gagoar/alohomora.svg?style=flat-square
[license-url]: https://github.com/gagoar/alohomora/blob/master/LICENSE