cmd_assist 0.1.11
A tool to save and retrieve frequently used commands.
License: MIT
Requires Python: <4.0,>=3.9
Keywords: commands, CLI, tools

# Command Assist Tool

Command Assist is a versatile CLI tool designed to streamline the management and organization of commands. It offers robust features for saving, listing, exporting, importing, backing up, and restoring commands, with support for AWS S3. The tool is aimed at helping developers efficiently store and retrieve useful commands, reducing time spent searching through command history or searching for a specifc command.

In addition to these core functionalities, Command Assist includes an AI assistance feature. This AI integration provides intelligent guidance and support for command-related queries, making it easier to discover and use commands effectively

## Table of Contents

- [Motivation](#motivation)
- [Python Versions](#python-versions)
- [Features](#features)
- [Installation](#installation)
    - [Option 1: Using a Virtual Environment and Symbolic Links](#option-1-using-a-virtual-environment-and-symbolic-links)
    - [Option 2: Installing Directly to System Python](#option-2-installing-directly-to-system-python)
- [Setting Up](#setting-up)
- [Commands](#commands)

## Motivation
Motivation

Managing commands and snippets in the terminal can be cumbersome, especially when juggling different contexts, switching between applications, or manually saving commands to notes. Many developers find themselves constantly copying commands from their terminal to other tools or having to search through command history to retrieve useful snippets.

The Command Assist Tool was created to streamline this process and enhance portability. Inspired by solutions like Warp, which offer advanced terminal features, I wanted to build a tool that allows me to manage and access my personal stash of commands directly from the terminal.

A key feature of Command Assist is its ability to seamlessly back up commands to cloud storage solutions such as AWS S3. This ensures that your command stash is not only organized and accessible but also portable. By storing your commands in the cloud, you can easily back them up and restore them if you switch devices, providing peace of mind and flexibility for developers who work across multiple environments.

In addition, Command Assist integrates with OpenAI to provide intelligent assistance for command-related queries. This AI integration offers context-aware guidance and suggestions, helping you discover and utilize commands more effectively without leaving the terminal.

While AWS S3 is an affordable and reliable starting point for cloud storage, there is potential for future updates to support additional storage solutions. The current choice of AWS S3 reflects its cost-effectiveness and wide adoption, but the tool is designed with flexibility in mind, allowing for the integration of other cloud providers as needed.

With features for saving commands, creating backups, leveraging AI assistance, and ensuring portability, Command Assist aims to simplify command management and enhance productivity, all while ensuring that your valuable command data is securely stored and easily retrievable from anywhere.

This version now includes the integration with OpenAI, highlighting how the AI assistance can enhance the tool’s capabilities.

## 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: Store commands with categories and descriptions.
	•	List Commands: Retrieve saved commands with filtering options.
	•	Import Commands: Import commands from JSON or YAML files.
	•	Backup Commands: Back up commands to local storage or an AWS S3 bucket.
	•	Restore Commands: Restore commands from an AWS S3 bucket.
	•	Configuration Management: Override and display configuration settings.
	•	AI Assistance: Get AI-generated assistance for command-related queries.

## Installation
Ensure you are using Python 3.9 and above.

### Option 1: Using a Virtual Environment and Symbolic Links

1. **Ensure Python Version**
   - Verify you have Python 3.9 or later:
     ```bash
     python --version
     ```

2. **Create and Activate Virtual Environment**
   - **Create**:
     ```bash
     python -m venv myenv
     ```

   - **Activate**:
     - **Windows**:
       ```bash
       myenv\Scripts\activate
       ```
     - **macOS/Linux**:
       ```bash
       source myenv/bin/activate
       ```

3. **Install `cmd_assist`**
   ```bash
   pip install cmd_assist
   ```

4. **Create Symbolic Links**
   - **Locate** your virtual environment’s `bin` directory:
     ```bash
     /path/to/myenv/bin/
     ```

   - **Create Symbolic Link**:
     - **macOS/Linux**:
       ```bash
       sudo ln -s /path/to/myenv/bin/ca /usr/local/bin/ca
       ```
     - **Windows**:
       ```powershell
       mklink C:\Path\To\Global\Folder\ca C:\Path\To\myenv\Scripts\ca.exe
       ```

5. **Verify Installation**
   ```bash
   ca --help
   ```

## Option 2: Installing Directly to System Python

1. **Ensure Python Version**
   - Verify you have Python 3.9 or later:
     ```bash
     python --version
     ```

2. **Install `cmd_assist`**
   ```bash
   python -m pip install cmd_assist
    ```
3.  **Verify Installation**
   ```bash
   ca --help
    ```

### Setting Up

To configure cmd_assist, follow these steps:

1. You can view the default structure by running `ca show-config`. 

2. Copy and paste this YAML to a convenient location or edit the config file inside your home directory `~/.cmd_assist/config.yaml`.

3. By default, the backup strategy is set to "local". However, you can choose to use an AWS bucket as the backup provider. To do this, make sure you are authenticated and have appropriate IAM permissions to create a bucket.

4. Edit the `backup_provider` field in the `config.yaml` file to "aws". Choose a suitable region and bucket name.

5. Run the command `ca create-backup` to create a backup using the AWS bucket as the provider.


6. The `command_files` directory is the default location where your commands are stored. Local backups will be saved in a sub-directory called `backups`.


```yaml
backup_provider: local  # or aws

# Configuration specific to different backup providers.
backup_providers:
  aws:
    region: us-east-1
    bucket_name: cmd-assist-bucket
    bucket_acl: private

  local:
    directory: /tmp/cmd_assist/
    directory_name: backups

# Path to the file where commands are stored.
commands_file: /tmp/commands.yaml

# Name of the object (file) to be used for backup.
object_name: commands.json
```



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:
```bash
ca --help
Usage: ca [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
assist           Command function to get ai asssitance 
```

- `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 it's a public repo, it will be fetched. Pre-configured bundles for this tool are available from [cmd_assist_bundles](https://github.com/darrenrabbs/cmd_assist_bundles).
  
- `show_config`:
    - Description: Show the configuration.
    - Output: The current configuration is displayed. A list of pre-configured bundles which can be fetched.

- `export_config`:
    - Description: Export the configuration.
    - Output: The configuration is exported to a file.

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

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

- `list_commands`:
    - Description: List all commands.
    - Output: All saved commands are displayed.
```bash
    ca 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.

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

- `import_commands`:
    - Description: Import commands.
    - Output: The commands are successfully imported.

- `create_backup`:
    - Description: Create a backup.
    - Output: A backup of the commands is created. This is required if you are using AWS bucket. Ensure you are authenticated.

- `destroy_backup`:
    - Description: Destroy a backup.
    - Output: The backup is successfully destroyed. 

- `remove`:
    - Description: Remove a command.
    - Output: The command is successfully removed.
    ```bash
        ca remove --category git --subcategory diff --description 'command to compare a file between 2 branches'
        Are you sure you want to remove the commands? This action cannot be undone. [y/N]: y
    ```
- `backup`:
    - Description: Backup commands.
    - Output: The commands are backed up depending on what you have configured, local or AWS.
```bash
    ca backup
    File /tmp/commands.yaml backed up to /tmp/cmd_assist/backups/backups/commands_20240807_235241.txt.
```

- `fetch`:
    - Description: Fetch commands.
    - Output: The commands are fetched from the configured bundles.
```bash
    ca fetch ansible
    Commands saved to fetched/ansible_commands.json
    Commands successfully imported from fetched/ansible_commands.json
```

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

## AI Assistance

The Command Assist Tool features AI assistance to enhance your experience. Use the assist command to interact with the AI, which provides intelligent support and suggestions based on your command-related queries. This feature helps you discover and utilize commands more effectively. There is a requirement to have an OPEN_AI_TOKEN and account setup to use this feature.

### Example1
```bash
cmd_assist_tool % ca assist linux volumes "command to mount a volume on linux"
Processing query for category: linux, subcategory: volumes, description: command to mount a volume on linux...
Suggested command: START_COMMAND
mount /dev/sdb1 /mnt/my_volume
END_COMMAND
Would you like to save this command? (yes/no) [no]: yes
Command saved.
```
### Example2
```bash
ca assist git history "command to show last person to change a specific file"
Processing query for category: git, subcategory: history, description: command to show last person to change a specific file...
Suggested command: START_COMMAND
git log -n 1 -- <file>
END_COMMAND
Would you like to save this command? (y/n) [n]: y
Command saved.
ca list git 
{
  "history": {
    "command to see last commit": "git log -1",
    "command to show last person to change a specific file": "git log -n 1 -- <file>"
  },
..
```



## Contact
If you encounter any issues or have any suggestions, please feel free to send them to dev@darrenrabbitt.com. Thank you for your support!