cmd_stash 0.1.398
A tool to save and retrieve frequently used commands.
Requires Python: <4.0,>=3.9

# Command Stash Tool

A CLI tool for managing and organizing commands with support for saving, listing, exporting, importing, and backing up commands to AWS S3. This tool is designed to help developers quickly store useful commands and retrieve them later, saving time that would otherwise be spent searching through command history.

## Table of Contents

- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
    - [Setting Up](#setting-up)
    - [Commands](#commands)
- [Configuration](#configuration)
- [Contributing](#contributing)
- [License](#license)
- [Additional Information](#additional-information)

## Python Versions

This project supports Python versions specified in the `pyproject.toml` file:

```toml
[tool.poetry.dependencies]
python = ">=3.9,<4.0"
```

## Features

- Save commands with categories and descriptions.
- List saved commands with filtering options.
- Import commands from JSON or YAML files.
- Backup commands to Local Storage or AWS S3 bucket.
- Restore commands from an AWS S3 bucket.
- Override and Show Configuration

## Installation

### Using the Makefile

1. **Clone the repository**:

     ```bash
     git clone <repository-url>
     cd <repository-name>
     ```

2. **Run the setup command**:

The Makefile provides a convenient way to set up the project. Run the following command to install dependencies and set up the environment:

     ```bash
     make setup
     ```

     This command will:

     - Install dependencies using poetry.
     - Set up the virtual environment.
     - Install project-specific dependencies.

     If you prefer to set up the environment manually, please refer to the manual setup instructions in the original README.

## Usage

### Setting Up

Configure AWS: Create a config.yaml file in the root directory with the following structure:

```yaml
aws:
    region: your-aws-region
    bucket_name: your-s3-bucket-name
    bucket_privacy: private # or public-read
```


A CLI tool for managing and organizing commands with support for saving, listing, exporting, importing, and backing up commands to AWS S3. This tool is designed to help developers quickly store useful commands and retrieve them later, saving time that would otherwise be spent searching through command history.

## Table of Contents

- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
    - [Setting Up](#setting-up)
    - [Commands](#commands)
- [Configuration](#configuration)
- [Contributing](#contributing)
- [License](#license)
- [Additional Information](#additional-information)

## Python Versions

This project supports Python versions specified in the `pyproject.toml` file:

```toml
[tool.poetry.dependencies]
python = ">=3.9,<4.0"
```

## Features

- Save commands with categories and descriptions.
- List saved commands with filtering options.
- Import commands from JSON or YAML files.
- Backup commands to Local Storage or AWS S3 bucket.
- Restore commands from an AWS S3 bucket.
- Override and Show Configuration

## Installation

### Using the Makefile

1. **Clone the repository**:

     ```bash
     git clone <repository-url>
     cd <repository-name>
     ```

2. **Run the setup command**:

The Makefile provides a convenient way to set up the project. Run the following command to install dependencies and set up the environment:

     ```bash
     make setup
     ```

     This command will:

     - Install dependencies using poetry.
     - Set up the virtual environment.
     - Install project-specific dependencies.

     If you prefer to set up the environment manually, please refer to the manual setup instructions in the original README.

## Usage

### Setting Up

Configure AWS: Create a config.yaml file in the root directory with the following structure:

```yaml
aws:
    region: your-aws-region
    bucket_name: your-s3-bucket-name
    bucket_privacy: private # or public-read
```

## Commands

- Register commands:
    - `set_config`: Set the configuration.
    - `show_config`: Show the configuration.
    - `export_config`: Export the configuration.
    - `show_bundles`: Show the bundles.
    - `save_command`: Save a command.
    - `list_commands`: List all commands.
    - `list_all_commands`: List all commands.
    - `list_categories`: List categories.
    - `import_commands`: Import commands.
    - `create_backup`: Create a backup.
    - `destroy_backup`: Destroy a backup.
    - `remove`: Remove a command.
    - `backup`: Backup commands.
    - `fetch`: Fetch commands.
    - `restore`: Restore commands.

Please note that the above commands are placeholders and need to be implemented with their respective functionalities.


## Commands

Here are some examples of commands and their expected outputs:

- `--help`:
   - Description: help for usage
   - Output: a list of commands to use
   ```bash
cmd_stash --help
Usage: cmd_stash [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  backup
  create-backup
  destroy-backup   Command function to destroy the backup.
  export-config
  fetch
  import
  list
  list-all
  list-categories  Command function to list all categories.
  remove           Command function to remove commands based on provided...
  restore
  save
  set-config
  show-bundles
  show-config
  ```



- `set_config`:
    - Description: Set the configuration.
    - Output: The configuration is successfully set. Additional bundles to different repos can be added.
      Just ensure to follow the same schema convention and if its a public repo, it will be fetched.
      pre-configured bundles for this tool are available from https://github.com/darrenrabbs/cmd_stash_bundles

- `show_config`:
    - Description: Show the configuration.
    - Output: The current configuration is displayed. A list of pre-configured bundles which can be fetched.
    ```bash
    cmd_stash show-config
        Configuration details:
    {
    "backup_provider": "aws",
    "commands_file": "/tmp/commands.yaml",
    "object_name": "commands.json",
    "aws": {
        "bucket_acl": "private",
        "bucket_name": "cmd-stash-bucket",
        "region": "us-east-1"
    },
    "bundles": [
        {
        "name": "aws",
        "url": "https://github.com/darrenrabbs/cmd_stash_bundles/raw/main/aws/commands.json"
        },
        {
        "name": "gcp",
        "url": "https://github.com/darrenrabbs/cmd_stash_bundles/raw/main/gcp/commands.json"
        },
        {
        "name": "docker",
        "url": "https://github.com/darrenrabbs/cmd_stash_bundles/raw/main/docker/commands.json"
        },
        {
        "name": "helm",
        "url": "https://github.com/darrenrabbs/cmd_stash_bundles/raw/main/helm/commands.json"
        },
        {
        "name": "kubernetes",
        "url": "https://github.com/darrenrabbs/cmd_stash_bundles/raw/main/kubernetes/commands.json"
        },
        {
        "name": "bazel",
        "url": "https://github.com/darrenrabbs/cmd_stash_bundles/raw/main/bazel/commands.json"
        },
        {
        "name": "argocd",
        "url": "https://github.com/darrenrabbs/cmd_stash_bundles/raw/main/argocd/commands.json"
        },
        {
        "name": "terraform",
        "url": "https://github.com/darrenrabbs/cmd_stash_bundles/raw/main/terraform/commands.json"
        },
        {
        "name": "ansible",
        "url": "https://github.com/darrenrabbs/cmd_stash_bundles/raw/main/ansible/commands.json"
        },
        {
        "name": "pulumi",
        "url": "https://github.com/darrenrabbs/cmd_stash_bundles/raw/main/pulumi/commands.json"
        },
        {
        "name": "gradle",
        "url": "https://github.com/darrenrabbs/cmd_stash_bundles/raw/main/gradle/commands.json"
        },
        {
        "name": "poetry",
        "url": "https://github.com/darrenrabbs/cmd_stash_bundles/raw/main/poetry/commands.json"
        },
        {
        "name": "maven",
        "url": "https://github.com/darrenrabbs/cmd_stash_bundles/raw/main/maven/commands.json"
        },
        {
        "name": "awk",
        "url": "https://github.com/darrenrabbs/cmd_stash_bundles/raw/main/awk/commands.json"
        },
        {
        "name": "sed",
        "url": "https://github.com/darrenrabbs/cmd_stash_bundles/raw/main/sed/commands.json"
        },
        {
        "name": "shell",
        "url": "https://github.com/darrenrabbs/cmd_stash_bundles/raw/main/shell/commands.json"
        },
        {
        "name": "bash",
        "url": "https://github.com/darrenrabbs/cmd_stash_bundles/raw/main/bash/commands.json"
        },
        {
        "name": "windows",
        "url": "https://github.com/darrenrabbs/cmd_stash_bundles/raw/main/windows/commands.json"
        },
        {
        "name": "python",
        "url": "https://github.com/darrenrabbs/cmd_stash_test/raw/main/python/commands.json"
        }
    ]
    }
```
- `export_config`:
    - Description: Export the configuration.
    - Output: The configuration is exported to a file.
    ```bash
    cmd_stash export-config /tmp/config.yaml
    Configuration exported to: /private/tmp/config.yaml
    ```

- `show_bundles`:
    - Description: Show the bundles.
    - Output: The available bundles are listed.
    ```bash
    cmd_stash show-bundles
    ```

- `save_command`:
    - Description: Save a command.
    - Output: The command is successfully saved.
    ```bash
        cmd_stash save git log "commit log for all branches" "git log --all --graph --oneline --decorate"
        Saved command: Saved command: git log --all --graph --oneline --decorate
    ```

- `list_commands`:
    - Description: List all commands.
    - Output: All saved commands are displayed.
    ```bash
        cmd_stash list git
        {
            "log": {
                "commit log for all branches": "git log --all --graph --oneline --decorate"
            }
        }
    ```

- `list_all_commands`:
    - Description: List all commands.
    - Output: All saved commands are displayed.
    ```bash
      cmd_stash list-all
    ```

- `list_categories`:
    - Description: List categories.
    - Output: All available categories are listed.
    ```bash
      cmd_stash list-categories
    ```

- `import_commands`:
    - Description: Import commands.
    - Output: The commands are successfully imported.
    ```bash
       cmd_stash import <filepath>
    ```
- `create_backup`:
    - Description: Create a backup.
    - Output: A backup of the commands is created. This is required if you are using AWS bucket. Ensure your are authenticated.
    ```bash
       cmd_stash create-backup
    ```
- `destroy_backup`:
    - Description: Destroy a backup.
    - Output: The backup is successfully destroyed. 

- `remove`:
    - Description: Remove a command.
    - Output: The command is successfully removed.
    ```bash
       cmd_stash remove git
        Are you sure you want to remove the commands? This action cannot be undone. [y/N]: n
    ```

- `backup`:
    - Description: Backup commands.
    - Output: The commands are backed up depending on what you have configured, local or aws.
    ```bash
       cmd_stash backup
       File /tmp/commands.yaml backed up to /tmp/cmd_stash/backups/backups/commands_20240807_235241.txt.
    ```
- `fetch`:
    - Description: Fetch commands.
    - Output: The commands are fetched from the configured bundles
    ```bash
        cmd_stash fetch poetry
        Commands saved to fetched/poetry_commands.json
        Commands successfully imported from fetched/poetry_commands.json
     ```

- `restore`:
    - Description: Restore commands.
    - Output: The commands are successfully restored from backup
    ```bash
       cmd_stash restore
    ```

Please note that the above commands are placeholders and need to be implemented with their respective functionalities.