✨ feat(cli): Add command-line interface (#15)

.env.example

@@ -1,3 +1,4 @@
 ANTHROPIC_API_KEY=your_api_key_here
 FORCE_REGENERATE=false
-LOG_LEVEL=debug
+LOG_LEVEL=debug
+CLI_ENV=local

.github/workflows/update_views.yml

@@ -6,9 +6,9 @@ on:
       - ".github/workflows/**/*.yml"
       - "prompts/**/*.md"
       - "prompts/prompt.md"
-      - "src/**/*.ts"
-      - "src/system_prompts/**/*.md"
-      - "src/templates/*.md"
+      - "src/app/**/*.ts"
+      - "src/app/system_prompts/**/*.md"
+      - "src/app/templates/*.md"
 
 jobs:
   update_views:
@@ -20,7 +20,7 @@ jobs:
 
       - name: Validate critical files
         run: |
-          if [ ! -f "src/system_prompts/prompt_analysis_agent/prompt.md" ]; then
+          if [ ! -f "src/app/system_prompts/prompt_analysis_agent/prompt.md" ]; then
             echo "Error: AI prompt analyzer file is missing"
             exit 1
           fi
@@ -58,7 +58,7 @@ jobs:
       - name: Check for system prompt changes
         id: check_changes
         run: |
-          if git diff --name-only HEAD^ HEAD | grep -q "src/system_prompts/prompt_analysis_agent/"; then
+          if git diff --name-only HEAD^ HEAD | grep -q "src/app/system_prompts/prompt_analysis_agent/"; then
             echo "FORCE_REGENERATE=true" >> $GITHUB_ENV
           else
             echo "FORCE_REGENERATE=false" >> $GITHUB_ENV
@@ -68,6 +68,7 @@ jobs:
         env:
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
           FORCE_REGENERATE: ${{ env.FORCE_REGENERATE }}
+          CLI_ENV: github_actions
         run: npm run generate-metadata
 
       - name: Update views

.gitignore

@@ -6,6 +6,9 @@ dist/
 node_modules/
 archive/
 
+# Ignore local database
+*.sqlite
+
 # Ignore local temporary files
 z_diff_output.txt
 z_dir2prompt_output.txt

.promptignore

@@ -15,8 +15,6 @@ package-lock.json
 dist/
 node_modules/
 archive/
-fragments/
-prompts/
 
 # Ignore local temporary files
 z_diff_output.txt

README.md

@@ -2,159 +2,225 @@
 
 > 🚧 **Project Under Development** - Evolving project, expect changes. Feedback welcome!
 
-Welcome to the **Prompt Library**, a collection of categorized AI prompts for easy navigation and reuse. Fork and customize this repository to build your own personalized prompt library tailored to your needs.
+Welcome to the **Prompt Library**, a collection of categorized AI prompts for easy navigation and reuse. This project combines GitHub Actions automation with a CLI for managing and using prompts, supporting both CI environments and desktop usage.
 
 ## 📚 Table of Contents
 
-<!-- START doctoc -->
-<!-- END doctoc -->
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
-## 🎯 Purpose
+- [🎯 Purpose & Features](#-purpose--features)
+- [⚡ Quick Start](#-quick-start)
+- [🛠️ How It Works](#-how-it-works)
+- [🖥️ CLI Usage](#-cli-usage)
+  - [Interactive Menu](#interactive-menu)
+  - [List Prompts and Categories](#list-prompts-and-categories)
+  - [Sync Personal Library](#sync-personal-library)
+  - [Execute Prompts](#execute-prompts)
+- [📂 Prompt Library Example](#-prompt-library-example)
+- [🚀 Getting Started](#-getting-started)
+- [🧩 Using Fragments](#-using-fragments)
+- [⚙️ Metadata Customization](#-metadata-customization)
+- [🤝 Contributing](#-contributing)
+- [📄 License](#-license)
 
-This project provides a structured framework for organizing and managing AI prompts, helping you to:
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-1. Store and categorize your prompts efficiently
-2. Automatically generate metadata for your prompts
-3. Easily navigate and reuse your prompt collection
-4. Collaborate and share prompts with others
-5. Create modular and reusable prompt components using fragments
+## 🎯 Purpose & Features
+
+The Prompt Library treats AI prompts as mini-applications that instruct AI models to become specialized agents. This approach promotes modularity, reusability, and shareability across projects and teams. In the rapidly evolving AI landscape, maintaining a library of prompts and agent definitions is increasingly valuable for both individuals and organizations.
+
+Key features include:
+
+- Prompt storage and categorization
+- Automatic metadata generation
+- Easy navigation and reuse of prompts
+- Collaboration and sharing capabilities
+- Modular prompt components (fragments)
+- CLI for prompt management and execution
+- GitHub Actions for automation
+
+> **Note**: Currently, this tool works exclusively with Claude from Anthropic. Support for additional AI models may be added in future updates.
+
+This project serves as a starting point for creating your own AI toolkit, demonstrating one way to manage and utilize AI prompts and agent definitions in personal and professional contexts.
+
+## ⚡ Quick Start
+
+1. Fork and clone the repository
+2. Set up Anthropic API key (GitHub Actions and CLI)
+3. Install dependencies: `npm install`
+4. Build and install CLI: `npm run build && npm install -g .`
+5. Initialize CLI: `prompt-library-cli`
+
+Detailed setup instructions in [Getting Started](#-getting-started).
 
 ## 🛠️ How It Works
 
-1. **Add Prompts**: Create a `prompt.md` file in the `prompts` directory.
-2. **Commit Changes**: Push your changes to the repository.
-3. **Automation**: GitHub Actions generate metadata and update README files.
-4. **Update Repository**: Changes are automatically committed back.
+1. Create a `prompt.md` file in `prompts` directory
+2. Commit and push changes
+3. GitHub Actions generate metadata and update READMEs
+4. Use CLI to manage and execute prompts
 
-## 📂 Prompt Library Example
+> **Important**: Create and commit `prompt.md` files individually to allow GitHub Actions to generate corresponding `metadata.yml` files. Both files are required for CLI prompt usage.
+
+## 🖥️ CLI Usage
+
+### Interactive Menu
+
+```sh
+prompt-library-cli
+```
+
+For all CLI options, run:
+
+```sh
+prompt-library-cli --help
+```
+
+### List Prompts and Categories
+
+```sh
+prompt-library-cli prompts --list
+prompt-library-cli prompts --categories
+```
+
+### Sync Personal Library
+
+```sh
+prompt-library-cli sync
+```
+
+> **Note**: Sync currently operates in read-only mode, fetching updates from the remote Git repository without pushing local changes.
+
+### Execute Prompts
+
+The `execute` command is a powerful tool for running prompts, especially useful in CI environments:
+
+```sh
+prompt-library-cli execute [options]
+```
+
+Key options:
+
+- `-p, --prompt <id>`: Execute a stored prompt by ID
+- `-i, --inspect`: Inspect the prompt variables without executing
+- `-fi, --file-input <variable>=<file>`: Specify a file to use as input for a variable
+- `-c, --ci`: Run in CI mode (non-interactive)
+
+In CI mode, the `execute` command acts as a dynamic CLI, allowing you to pass prompt variables as command-line arguments:
 
-> **Note:** The prompts listed here are examples to demonstrate structure and organization. Customize and maintain your own prompts as needed.
+```sh
+prompt-library-cli execute -p <prompt_id> --<variable1> <value1> --<variable2> <value2> -c
+```
 
+For detailed usage, run:
+
+```sh
+prompt-library-cli execute --help
+```
+
+## 📂 Prompt Library Example
+
+> **Note:** The prompts listed here are examples. Customize and maintain your own prompts as needed.
 > **Tip:** Check out the Prompt Engineering category for prompts to help you create high-quality prompts and build your own library.
-<details open>
+<details>
 <summary><strong>Coding</strong></summary>
 
-- [Git Branch Name Generator](prompts/git_branch_name_generator/README.md) - Generates optimized git branch names based on project context and best practices
-- [Git Commit Message Creator](prompts/git_commit_message_agent/README.md) - Generates optimized git commit messages following Conventional Commits specification
 - [GitHub Issue Creator Agent](prompts/github_issue_creator_agent/README.md) - Creates comprehensive and actionable GitHub issues based on provided project information
+- [Git Commit Message Creator](prompts/git_commit_message_agent/README.md) - Generates optimized git commit messages following Conventional Commits specification
 - [Software Architect Code Reviewer](prompts/software_architect_code_reviewer/README.md) - Generates comprehensive pull requests with architectural analysis and optimization suggestions
+- [Git Branch Name Generator](prompts/git_branch_name_generator/README.md) - Generates optimized git branch names based on project context and best practices
 - [Software Development Expert Agent](prompts/software_development_agent/README.md) - Provides expert assistance across the software development lifecycle
 
 </details>
-<details open>
+<details>
 <summary><strong>Content Creation</strong></summary>
 
 - [Documentation Specialist Agent](prompts/documentation_specialist_agent/README.md) - Generates revolutionary software documentation using AI-powered techniques and industry expertise
 
 </details>
-<details open>
+<details>
 <summary><strong>Healthcare</strong></summary>
 
 - [Health Optimization Agent](prompts/health_optimization_agent/README.md) - Generates personalized, adaptive health optimization plans based on comprehensive user data analysis
 - [Psychological Support Therapy Agent](prompts/psychological_support_agent/README.md) - Provides personalized, AI-driven psychological support and therapy through digital platforms
 
 </details>
-<details open>
+<details>
 <summary><strong>Problem Solving</strong></summary>
 
 - [Problem Solving Assistant](prompts/problem_solving_agent/README.md) - Generates expert networks and strategies to solve complex problems and achieve goals
 
 </details>
-<details open>
+<details>
 <summary><strong>Prompt Engineering</strong></summary>
 
-- [Prompt Engineering God](prompts/prompt_engineering_agent/README.md) - Creates or refines optimized prompts to maximize AI potential within ethical boundaries
 - [AI Assistant Concept Architect](prompts/ai_assistant_concept_architect/README.md) - Generates innovative and feasible AI assistant concepts based on user-provided topics
-- [Software Engineering Architect Agent](prompts/software_engineering_architect/README.md) - Generates comprehensive software specification documents with futuristic insights
+- [Prompt Engineering God](prompts/prompt_engineering_agent/README.md) - Creates or refines optimized prompts to maximize AI potential within ethical boundaries
+- [Software Specification Architect](prompts/software_spec_architect_agent/README.md) - Analyzes user requirements and creates comprehensive software specification documents
 
 </details>
-<details open>
+<details>
 <summary><strong>Translation</strong></summary>
 
-- [Omniscient Cosmic Translator](prompts/cosmic_translator_agent/README.md) - Translates between all forms of expression and existence across infinite realities
+- [Universal Translator Agent](prompts/universal_translator_agent/README.md) - Translates between any languages, modes of expression, or conceptual frameworks
 
 </details>
 
 ## 🚀 Getting Started
 
 1. **Fork the Repository**: Click "Fork" to create a copy in your GitHub account.
+
 2. **Clone Your Fork**:
-   ```
+
+   ```sh
    git clone https://github.com/YOUR_USERNAME/REPO_NAME.git
    ```
+
 3. **Set Up Anthropic API Key**:
-   - Create an Anthropic account and generate an API key at the [Anthropic Console](https://console.anthropic.com/).
-   - In repository settings: **Secrets and variables** > **Actions**.
-   - Create a secret named `ANTHROPIC_API_KEY` with your API key.
+   - Generate an API key at the [Anthropic Console](https://console.anthropic.com/).
+   - For GitHub Actions: Add as `ANTHROPIC_API_KEY` secret in repository settings.
+   - For CLI: Enter when prompted or set as environment variable.
+
 4. **Install Dependencies**:
-   - Ensure [Node.js](https://nodejs.org/en) (v22+ recommended) is installed.
-   - Run `npm install`.
-5. **Add Prompts**:
-   - Create a `prompt.md` file in the `prompts` directory.
-   - Write your prompt content.
-   - Commit and push:
-     ```
-     git add .
-     git commit -m "Add new prompt: [Brief Description]"
-     git push
-     ```
-6. **Automated Processes**: GitHub Actions will generate metadata and update README files.
-7. **Run Locally (Optional)**:
-   - Copy `.env.example` to `.env`:
-     ```
-     cp .env.example .env
-     ```
-   - Update `.env` with your API key.
-   - Generate metadata:
-     ```
-     npm run generate-metadata
-     ```
-   - Update README files:
-     ```
-     npm run update-views
-     ```
-8. **Customize as Needed**:
-   - Modify templates in `src/templates` to change prompt display.
-   - Update scripts in `src/core` to alter metadata generation or view updates.
-
-## 🔧 Customizing Metadata Extraction
-
-To customize metadata extraction:
-
-1. Open and edit `src/system_prompts/prompt_analysis_agent/prompt.md`.
-2. Run `npm run generate-metadata` to test.
-3. Commit and push changes to trigger GitHub Actions.
-
-> **Note**: Changes affect future metadata generations. Test thoroughly.
+   - Ensure [Node.js](https://nodejs.org/en) is installed.
 
-## 🧩 Using Fragments
+   ```sh
+   npm install
+   ```
+
+5. **Build and Install CLI**:
 
-Fragments are reusable prompt components.
+   ```sh
+   npm run build
+   npm install -g .
+   ```
+
+6. **Initialize CLI**:
+
+   ```sh
+   prompt-library-cli
+   ```
+
+   Follow prompts to set up configuration.
 
-To use fragments:
+## 🧩 Using Fragments
 
-1. **Create a Fragment**:
-   - In `fragments`, create a new `.md` file under the appropriate category (categories are listed [here](/src/system_prompts/prompt_analysis_agent/prompt.md)).
-   - Create your fragment content.
-   - To match a variable in a prompt, name the fragment file to correspond with that variable.
+Fragments are reusable prompt components:
 
-     **Example:** `awesome_guidelines.md` → `AWESOME_GUIDELINES`
+1. Create `.md` files in `fragments` directory under the appropriate [categories](/src/app/system_prompts/prompt_analysis_agent/prompt.md)).
+2. Reference in prompts: `` (e.g., `` for `awesome_guidelines.md`).
+3. Manage and use via CLI.
 
-2. **Update Metadata and Views**:
-   - Regenerate metadata:
-     ```
-     FORCE_REGENERATE=true npm run generate-metadata
-     ```
-   - Update views:
-     ```
-     npm run update-views
-     ```
+## ⚙️ Metadata Customization
 
-Once metadata and views are regenerated, each prompt's README will list compatible fragments.
+1. Edit `src/system_prompts/prompt_analysis_agent/prompt.md`.
+2. Test with `npm run generate-metadata`.
+3. Commit and push to trigger GitHub Actions.
 
-> **Note**: Forcing metadata regeneration can be costly; consider running selectively.
+> **Note**: Changes affect future metadata generations. Test thoroughly before committing.
 
-## 📝 Contributing
+## 🤝 Contributing
 
 Contributions to improve templates, scripts, or structure are welcome! Submit issues or pull requests.