Update cli_commands_reference.md

Author: 1minds3t

docs/cli_commands_reference.md

@@ -1,195 +1,268 @@
-# omnipkg CLI Commands Reference
+# Omnipkg CLI Documentation
+*The intelligent Python package manager that eliminates dependency hell*
 
-This document provides a comprehensive overview of all `omnipkg` command-line interface (CLI) commands and their usage.
+## Quick Start
 
-## Global Options
+```bash
+# Install packages with smart conflict resolution
+8pkg install requests numpy>=1.20
+
+# Install multiple versions of the same package
+8pkg install uv==0.7.13 uv==0.7.14
 
-*   `-v`, `--version`: Displays the current version of `omnipkg`.
+# See what's installed
+8pkg list
 
-## Commands
+# Explore a package interactively
+8pkg info tensorflow
+
+# Try the demos
+8pkg demo
+```
 
 ---
 
-### `omnipkg install <package_spec> [package_spec...]`
+## Core Commands
+
+### 📦 Package Management
 
-**Description**: The primary command for installing packages. `omnipkg` intelligently manages versions, automatically resolving conflicts by creating isolated "bubbles" for conflicting versions while keeping your main environment stable.
+#### `8pkg install <package_spec> [package_spec...]`
+Install packages with intelligent conflict resolution. Omnipkg automatically handles version conflicts by creating isolated "bubbles" while keeping your main environment stable.
 
-**Arguments**:
-*   `<package_spec>`: One or more package specifications (e.g., `"requests"`, `"numpy==1.26.4"`, `"django>=3.0,<4.0"`).
-*   `-r`, `--requirement <FILE>`: Install packages listed in a `requirements.txt`-like file.
+**Options:**
+- `-r, --requirement <FILE>` - Install from requirements file
 
-**Examples**:
+**Examples:**
 ```bash
-# Install a specific version of a package
-omnipkg install flask==2.3.0
+# Basic install
+8pkg install flask==2.3.0
 
-# Install multiple packages
-omnipkg install requests==2.32.4 tqdm
+# Multiple packages
+8pkg install requests tqdm pandas
 
-# Install multiple versions of the same package (omnipkg will bubble one)
-omnipkg install uv==0.7.13 uv==0.7.14
+# From requirements file
+8pkg install -r requirements.txt
 
-# Install from a requirements file
-omnipkg install -r my_project_requirements.txt
+# Multiple versions (omnipkg handles conflicts automatically)
+8pkg install numpy==1.24.0 numpy==1.26.4
 ```
 
----
+#### `8pkg install-with-deps <package> --dependency <dep>...`
+Install a package with specific dependency versions - perfect for AI/ML workflows where you need exact version combinations.
 
-### `omnipkg install-with-deps <package_spec> [--dependency <dep_spec>...]`
+```bash
+# Install TensorFlow with specific NumPy version
+8pkg install-with-deps tensorflow==2.13.0 --dependency numpy==1.24.3
 
-**Description**: Installs a package while allowing you to specify exact versions for its direct or transitive dependencies. This is particularly useful for complex ecosystems like AI/ML where a specific combination of a main package and its underlying libraries (e.g., TensorFlow with a precise NumPy version) is required. `omnipkg` will ensure these versions are present, bubbling them if they conflict with your main environment.
+# Multiple dependencies
+8pkg install-with-deps torch==2.0.0 --dependency numpy==1.24.3 --dependency pillow==9.5.0
+```
 
-**Arguments**:
-*   `<package_spec>`: The main package to install (e.g., `"tensorflow==2.13.0"`).
-*   `--dependency <dep_spec>`: One or more explicit dependency versions (e.g., `"numpy==1.24.3"`, `"typing-extensions==4.5.0"`). Can be used multiple times.
+#### `8pkg uninstall <package> [--yes]`
+Intelligently remove packages with interactive version selection.
 
-**Example**:
 ```bash
-omnipkg install-with-deps tensorflow==2.13.0 --dependency numpy==1.24.3 --dependency typing-extensions==4.5.0
+8pkg uninstall old-library
+8pkg uninstall torch --yes  # Skip confirmation
 ```
 
 ---
 
-### `omnipkg list [filter]`
+### 📋 Information & Status
 
-**Description**: Displays all packages `omnipkg` is aware of, distinguishing between versions active in your main Python environment and those stored in isolated "bubbles."
+#### `8pkg list [filter]`
+View all managed packages, showing active vs bubbled versions.
+
+```bash
+8pkg list           # All packages
+8pkg list tensor    # Filter by name
+```
 
-**Arguments**:
-*   `[filter]`: An optional string to filter package names (e.g., `"flask"` will show `flask` and `flask-login`).
+#### `8pkg info <package> [--version <version>]`
+Interactive package explorer with detailed metadata and version management.
 
-**Examples**:
 ```bash
-# List all managed packages
-omnipkg list
+8pkg info requests
+8pkg info numpy --version 1.24.3
+```
+
+#### `8pkg status`
+Environment health dashboard showing active packages, bubble usage, and system status.
 
-# List packages matching a filter
-omnipkg list tensor
+```bash
+8pkg status
 ```
 
 ---
 
-### `omnipkg status`
+### 🔄 Environment Management
 
-**Description**: Provides a high-level overview of your `omnipkg`-managed Python environment's health. It shows the active `site-packages` path, the number of active packages, the total size and count of isolated bubbles, and fun status messages about critical tools like `pip` and `uv`.
+#### `8pkg swap <type> <version>`
+Switch between different versions of packages or Python interpreters at runtime.
 
-**Usage**:
 ```bash
-omnipkg status
+8pkg swap python 3.11    # Switch Python version
+8pkg swap numpy 1.24.0   # Switch package version
 ```
 
----
-
-### `omnipkg info <package_name> [--version <version_spec>]`
+#### `8pkg revert [--yes]`
+Restore environment to last known good state - your "undo" button.
 
-**Description**: Provides a detailed interactive dashboard for a specific package. You can explore its metadata, dependencies, active status, and any bubbled versions.
+```bash
+8pkg revert
+8pkg revert --yes  # Skip confirmation
+```
 
-**Arguments**:
-*   `<package_name>`: The name of the package to inspect (e.g., `"requests"`, `"numpy"`).
-*   `--version <version_spec>`: Optional. Specify a particular version to inspect directly (e.g., `"1.24.3"`). If omitted, `omnipkg` might offer interactive choices.
+#### `8pkg run <script_path> [args...]`
+Run Python scripts with auto-healing - if version conflicts occur, omnipkg automatically resolves them and re-runs.
 
-**Examples**:
 ```bash
-omnipkg info flask-login
-omnipkg info uv --version 0.7.14
+8pkg run my_script.py
+8pkg run analysis.py --input data.csv
 ```
 
 ---
 
-### `omnipkg demo`
+### 🐍 Python Management
+
+#### `8pkg python <subcommand>`
+Manage Python interpreters in your environment.
 
-**Description**: An interactive showcase of `omnipkg`'s core version-switching capabilities. This is highly recommended for new users to see `omnipkg` in action on various package types.
+**Subcommands:**
+- `adopt <version>` - Add a Python version to omnipkg management
+- `remove <version>` - Remove a managed Python version
+- `switch <version>` - Switch to a different Python version
+- `rescan` - Refresh the Python interpreter registry
 
-**Usage**:
 ```bash
-omnipkg demo
+8pkg python adopt 3.11
+8pkg python switch 3.12
+8pkg python remove 3.9
 ```
-Follow the on-screen prompts to select a demo (Python module switching, binary switching, C-extension switching, complex dependency switching).
 
 ---
 
-### `omnipkg stress-test`
+### 🧹 Maintenance
 
-**Description**: A heavy-duty demonstration of `omnipkg`'s resilience with large, complex scientific computing packages (NumPy, SciPy). It performs a series of challenging installations and runtime version swaps to prove `omnipkg`'s ability to handle previously "impossible" dependency scenarios.
+#### `8pkg prune <package> [--keep-latest N] [--yes]`
+Clean up old bubbled versions to save disk space.
 
-**Usage**:
 ```bash
-omnipkg stress-test
+8pkg prune tensorflow --keep-latest 3  # Keep 3 most recent versions
+8pkg prune numpy --yes                 # Remove all old versions
 ```
-**(Note**: This demo currently requires Python 3.11. Future versions of `omnipkg` will enable cross-Python-version interpreter hot-swapping.)
 
----
+#### `8pkg rebuild-kb [--force]`
+Refresh omnipkg's knowledge base of package metadata.
+
+```bash
+8pkg rebuild-kb         # Standard refresh
+8pkg rebuild-kb --force # Complete rebuild
+```
 
-### `omnipkg revert [--yes]`
+#### `8pkg reset [--yes]`
+Clear omnipkg's Redis knowledge base (keeps actual packages).
 
-**Description**: Your "undo" button for environment changes. `omnipkg` maintains "last known good" snapshots of your environment. This command restores your main environment to the state of the last snapshot, effectively reversing any unintended changes (e.g., downgrades caused by `pip` or `uv`).
+```bash
+8pkg reset --yes
+```
 
-**Arguments**:
-*   `--yes`, `-y`: Skip the confirmation prompt.
+#### `8pkg reset-config [--yes]`
+Delete configuration file to trigger fresh setup.
 
-**Examples**:
 ```bash
-omnipkg revert
-omnipkg revert --yes
+8pkg reset-config --yes
 ```
 
 ---
 
-### `omnipkg uninstall <package_name> [package_name...] [--yes]`
-
-**Description**: Intelligently removes packages. By default, it will prompt you to select which versions (active, bubbled, or all non-protected) of a package to remove. It handles associated files and cleans up its knowledge base.
+### ⚙️ Configuration
 
-**Arguments**:
-*   `<package_name>`: One or more package names to uninstall.
-*   `--yes`, `-y`: Skip confirmation prompts for removal.
+#### `8pkg config <action> [key] [value]`
+Manage omnipkg settings.
 
-**Examples**:
 ```bash
-omnipkg uninstall old-library
-omnipkg uninstall torch --yes
+8pkg config view                    # Show current config
+8pkg config set language es         # Set display language
+8pkg config get redis.host          # Get specific setting
 ```
-**(Note**: `omnipkg`'s core dependencies and `omnipkg` itself are protected from accidental uninstallation from the active environment.)
 
 ---
 
-### `omnipkg rebuild-kb [--force]`
+## Interactive Demos
 
-**Description**: Refreshes `omnipkg`'s internal knowledge base. `omnipkg` stores rich metadata about your packages and their file hashes in Redis. Use this command if you suspect the knowledge base is out of sync or corrupted, or after manually altering installed packages (not recommended).
+### `8pkg demo`
+Interactive showcase of version-switching capabilities. Great for new users!
 
-**Arguments**:
-*   `--force`, `-f`: Ignore existing cache and force a complete rebuild of all package metadata and file hashes.
+**Demo Types:**
+- Python module switching
+- Binary switching  
+- C-extension switching
+- Complex dependency switching
 
-**Usage**:
-```bash
-omnipkg rebuild-kb
-omnipkg rebuild-kb --force
-```
+### `8pkg stress-test`
+Heavy-duty demonstration with large scientific packages (NumPy, SciPy). Shows omnipkg handling "impossible" dependency scenarios.
+
+*Note: Currently requires Python 3.11*
 
 ---
 
-### `omnipkg reset [--yes]`
+## Global Options
 
-**Description**: Deletes `omnipkg`'s entire Redis knowledge base. This will clear all package metadata, hash indexes, and bubble tracking data. It does NOT delete actual package files from your system. Use this for a complete clean slate if `omnipkg` is misbehaving severely, then follow up with `omnipkg rebuild-kb`.
+- `-v, --version` - Show omnipkg version
+- `-h, --help` - Show help message
+- `--lang CODE` - Override display language (e.g., `es`, `de`, `ja`)
 
-**Arguments**:
-*   `--yes`, `-y`: Skip the confirmation prompt.
+---
 
-**Usage**:
-```bash
-omnipkg reset
-omnipkg reset --yes
-```
+## Key Concepts
+
+**🫧 Bubbles**: Isolated package versions that don't conflict with your main environment
+
+**🔄 Runtime Switching**: Change package/Python versions without restarting your environment
+
+**🧠 Knowledge Base**: Redis-powered metadata system that tracks all packages and their relationships
+
+**🛡️ Auto-Healing**: Automatic resolution of version conflicts when running scripts
 
 ---
 
-### `omnipkg reset-config [--yes]`
+## Common Workflows
+
+### Setting up a new project
+```bash
+# Install your main dependencies
+8pkg install django>=4.0 psycopg2-binary
+
+# Add development tools
+8pkg install pytest black flake8
+
+# Check everything is working
+8pkg status
+```
+
+### Handling version conflicts
+```bash
+# Install conflicting versions (omnipkg handles it)
+8pkg install numpy==1.24.0 scipy  # scipy needs numpy>=1.26.0
 
-**Description**: Deletes `omnipkg`'s local configuration file (`~/.config/omnipkg/config.json`). The next time `omnipkg` is executed, it will run through the first-time setup process again, allowing you to reconfigure paths or Redis connections.
+# Switch between versions as needed
+8pkg swap numpy 1.26.0  # For scipy work
+8pkg swap numpy 1.24.0  # For legacy code
 
-**Arguments**:
-*   `--yes`, `-y`: Skip the confirmation prompt.
+# Or let auto-healing handle it
+8pkg run legacy_script.py  # Automatically uses numpy 1.24.0
+```
 
-**Usage**:
+### Cleaning up your environment
 ```bash
-omnipkg reset-config
-omnipkg reset-config --yes
+# See what's taking up space
+8pkg list
+
+# Remove old versions
+8pkg prune tensorflow --keep-latest 2
+8pkg prune numpy --keep-latest 1
+
+# Check the results
+8pkg status
 ```