### Configuration File Example

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/configuration.md

Example of the config.json file, containing application settings.

```json
{
    "allowed_paths": ["/bin", "/usr/bin"],
    "auto_hook": true,
    "trusted_binaries": [],
    "blacklisted_binaries": []
}
```

--------------------------------

### Headless API Usage Example

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/INDEX.md

Illustrates a typical navigation path for headless API usage, starting from the README and linking to specific API references and schema definitions.

```text
README.md → api-reference/audit.md → types.md → cli-reference.md#json-output-schema
```

--------------------------------

### Command Suggestion Example

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/scanner.md

Shows how to get a command suggestion for a potential typo using the `suggest_command` function.

```python
# User typo: "lsdir" instead of "ls"
suggestion = scanner.suggest_command('lsdir', state_mgr)
print(f"Did you mean {suggestion}?")  # Output: Did you mean ls?
```

--------------------------------

### I/O Utilities Examples

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/README.md

Provides examples for common I/O operations including JSON handling, logging, terminal manipulation, and colorized output.

```python
from commando.utils.io import (
    load_json, save_json, write_log, clear_screen, pause,
    CYAN, GREEN, YELLOW, RED, MAGENTA, BOLD, RESET,
    HISTORY_FILE, BASE_DIR
)

# JSON operations
data = load_json(HISTORY_FILE, {})  # Safe read with default
save_json(HISTORY_FILE, data)       # Atomic write

# Logging
write_log('command', 'reason', 'additional output')  # Append to debug.log

# Terminal
clear_screen()  # Clear screen
pause()        # Prompt "Press Enter to continue..."

# Colors (auto-disabled in pipes/non-TTY)
print(f"{GREEN}Success!{RESET}")
print(f"{RED}{BOLD}Error{RESET}")

# Formatting
badge = format_badge("File Management")  # Returns colored badge string
```

--------------------------------

### Example: Search for 'ls' command

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/cli-reference.md

Demonstrates searching for the 'ls' command and viewing its description, example, and category. The CLI will pause for user input and update history.

```bash
$ commando search ls
# Displays: description, example, category
# Pauses, waits for Enter
# Updates history with usage count
```

--------------------------------

### Manage Configuration Settings

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/README.md

Initialize ConfigManager to retrieve or set configuration values. Example shows getting allowed paths and setting a custom list.

```python
from commando.utils.config import ConfigManager

config = ConfigManager()

# Get allowed paths
paths = config.get('allowed_paths')

# Set custom value
config.set('allowed_paths', ['/bin', '/usr/bin', '/opt/bin'])
```

--------------------------------

### Command Metadata Example

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/types.md

An example of a command dictionary adhering to the CommandMetadata schema.

```python
{
    "desc": "Searches for a specific pattern of text inside files.",
    "example": "grep -ri 'TODO' ./src",
    "category": "Text Processing"
}
```

--------------------------------

### Debug Log Example

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/configuration.md

Example entries from the debug.log file, showing command-related errors.

```text
[14:23:45] unknown_cmd | Command not found
[14:24:12] scan_error | Exception during binary analysis
    -> RAW: binutils library not available
```

--------------------------------

### System Integration Example

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/INDEX.md

Shows a common integration flow for system components, connecting configuration management with scanner modules.

```text
configuration.md → api-reference/config-manager.md → api-reference/scanner.md
```

--------------------------------

### Install CLI-Commando

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/README.md

Install the CLI-Commando package using pip. For development, use an editable install.

```bash
pip install cli-commando
```

```bash
pip install -e .
```

--------------------------------

### Basic Configuration Access Example

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/config-manager.md

Illustrates common usage patterns for accessing and modifying configuration settings using ConfigManager.

```python
from commando.utils.config import ConfigManager

config = ConfigManager()

# Get allowed paths for auto-scan
paths = config.get('allowed_paths')
for path in paths:
    print(path)

# Disable auto-hook
config.set('auto_hook', False)

# Check current setting
hook_enabled = config.get('auto_hook')
```

--------------------------------

### Command History Example

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/types.md

An example of the CommandHistory dictionary, showing command usage counts.

```python
{
    "ls": 5,
    "grep": 3,
    "mkdir": 1,
    "rm": 0  # Failed quiz answer
}
```

--------------------------------

### Get Completion Matches for Prefix

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/cli-reference.md

Returns a space-separated list of known commands that start with the given prefix. This is used internally by the bash completion script.

```bash
commando --complete <prefix>
```

--------------------------------

### Initialize and Run Main Dashboard Loop

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/dashboard.md

Example of initializing the StateManager and setting up a search wrapper to enter the interactive dashboard. This is the primary entry point for the UI.

```python
from commando.main import StateManager
from commando.core import audit, scanner
from commando.ui import dashboard

state_mgr = StateManager()

def search_wrapper(cmd):
    audit.search_command(cmd, state_mgr, scanner)

# Enter interactive dashboard
dashboard.main_loop(state_mgr, search_wrapper, scanner.auto_scan_system)
```

--------------------------------

### Custom Commands File Format

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/configuration.md

Example of the custom.json file, storing metadata for user-defined commands.

```json
{
    "mytool": {
        "desc": "My custom utility",
        "example": "mytool --help",
        "category": "Custom"
    }
}
```

--------------------------------

### Instantiate ConfigManager

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/config-manager.md

Shows how to get the singleton instance of ConfigManager. This is the primary way to interact with the configuration.

```python
config = ConfigManager()
```

--------------------------------

### Example: Programmatic Integration with JSON output

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/cli-reference.md

Shows how to programmatically integrate with the CLI by capturing JSON output and parsing it to check for specific behaviors, such as network calls.

```bash
#!/bin/bash
response=$(commando search wget --json)
tags=$(echo "$response" | grep -o 'Network Mutator')
if [ -n "$tags" ]; then
    echo "wget makes network calls"
fi
```

--------------------------------

### CI/CD Integration Example

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/cli-reference.md

Example of using CLI Commando in a CI/CD pipeline, specifically for GitHub Actions, to check command status.

```yaml
# GitHub Actions
- name: Check command
  run: commando search curl --json | jq '.status'
```

--------------------------------

### Static Analysis Pattern Examples

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/scanner.md

Illustrates heuristic patterns used by the scanner to extract usage information from binary strings, including priority levels and example matches.

```markdown
| Pattern | Priority | Example Match |
|---------|----------|----------------|
| `example:` / `examples:` followed by command invocation | 1 | "examples: grep -r 'pattern' ." |
| `usage:` followed by command invocation | 1 | "usage: ls -la" |
| `<cmd> - <description>` format | 2 | "grep - line-oriented text search" |
| Longest line mentioning command (>15 chars, no special chars) | 3 | "grep is a text search utility" |
```

--------------------------------

### Example Usage of Environment Variables

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/configuration.md

Demonstrates how to use environment variables like NO_COLOR, PATH, and HOME to control CLI-Commando's behavior.

```bash
# Disable colors
NO_COLOR=1 commando search grep

# Custom PATH (only affects which directories scanner probes)
PATH=/usr/bin:/bin commando search ls

# User data directory
HOME=/custom/home commando  # Uses /custom/home/.commando
```

--------------------------------

### Dashboard Module Examples

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/README.md

Shows how to use the dashboard module to display menus and run the main interactive loop for the Commando CLI.

```python
from commando.ui import dashboard
from commando.core import audit, scanner

# Display menu
dashboard.print_dashboard(state_mgr.session_history, state_mgr.pending_imports)

# Run main loop (blocks until exit)
def search_fn(cmd):
    audit.search_command(cmd, state_mgr, scanner)

dashboard.main_loop(state_mgr, search_fn, scanner.auto_scan_system)
```

--------------------------------

### Intent Search Example

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/scanner.md

Demonstrates how to find commands related to a specific intent using the `search_intent` function. Requires `StateManager` initialization.

```python
from commando.core import scanner
from commando.main import StateManager

state_mgr = StateManager()

# Find commands related to file deletion
results = scanner.search_intent('delete files', state_mgr)
print(results)  # Output: ['rm', 'shred', 'unlink']
```

--------------------------------

### Example: Search for 'grep' command with JSON output

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/cli-reference.md

Demonstrates searching for the 'grep' command and requesting the output in JSON format for automation purposes.

```bash
# Get JSON response for automation
commando search grep --json
# Output: {"command": "grep", "status": "success", "kinetic_tags": [...], "audit_method": "strace"}
```

--------------------------------

### Behavioral Tags Example

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/types.md

An example list of BehavioralTags, indicating network, file, and process operations.

```python
["[Network Mutator]", "[File Reader/Writer]", "[Process Spawner]"]
```

--------------------------------

### Blacklist File Format

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/configuration.md

Example of the blacklist.json file, listing rejected command names.

```json
[
    "broken_cmd",
    "no_description_found",
    "corrupted_binary"
]
```

--------------------------------

### Example: Interactive Dashboard Workflow

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/cli-reference.md

Illustrates a typical workflow within the interactive dashboard, including auto-scanning for commands, reviewing imports, and updating statistics.

```bash
$ commando
# Main menu displayed
# User selects [4] to auto-scan
# Scanner discovers new commands
# User reviews pending imports via [7]
# Stats updated in history
```

--------------------------------

### Example Config File Structure

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/config-manager.md

Shows the expected JSON structure for the configuration file, including common settings like allowed paths, auto-hook status, and binary blacklists/whitelists.

```json
{
    "allowed_paths": [
        "/bin",
        "/usr/bin",
        "/data/data/com.termux/files/usr/bin",
        "/system/bin"
    ],
    "auto_hook": true,
    "trusted_binaries": [],
    "blacklisted_binaries": []
}
```

--------------------------------

### Inverted Search Index Example

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/types.md

An example of an InvertedIndex, mapping keywords to lists of commands.

```python
{
    "search": ["grep", "find"],
    "delete": ["rm", "rmdir"],
    "file": ["ls", "cat", "grep", "find"],
    "directory": ["ls", "mkdir", "rmdir"]
}
```

--------------------------------

### Inverted Index File Format

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/configuration.md

Example of the index.json file, mapping words to lists of commands.

```json
{
    "search": ["grep", "find"],
    "file": ["ls", "cat", "grep"],
    "delete": ["rm", "rmdir"]
}
```

--------------------------------

### Scan Result Example

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/types.md

An example of a successful ScanResult, detailing a command's description, example, category, and source.

```python
{
    "desc": "search for lines matching a pattern",
    "example": "grep 'pattern' filename.txt",
    "category": "Auto-Imported Libs",
    "source": "OS Manual"
}
```

--------------------------------

### Headless JSON Output Example (CLI)

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/audit.md

Demonstrates how to obtain JSON output from the command-line interface for audit results. This is useful for scripting and automated analysis.

```bash
audit.search_command('grep', state_mgr, scanner, headless=True)
```

--------------------------------

### History File Format

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/configuration.md

Example of the history.json file, storing command usage counts.

```json
{
    "ls": 5,
    "grep": 3,
    "mkdir": 1
}
```

--------------------------------

### Pending Imports File Format

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/configuration.md

Example of the pending.json file, storing metadata for commands awaiting user review.

```json
{
    "newtool": {
        "desc": "A newly discovered tool",
        "example": "newtool run",
        "category": "Auto-Imported Libs"
    }
}
```

--------------------------------

### Audit Command Search Examples

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/README.md

Demonstrates how to search for commands using the audit module, with options for basic search, kinetic auditing, and programmatic JSON output.

```python
from commando.core import audit, scanner

# Basic search
audit.search_command('ls', state_mgr, scanner, headless=False, audit=False)

# With kinetic audit (strace + analysis)
audit.search_command('curl', state_mgr, scanner, headless=False, audit=True)

# JSON mode (programmatic)
audit.search_command('grep', state_mgr, scanner, headless=True, audit=False)
# Outputs: {"command": "grep", "status": "success", "kinetic_tags": [...]}
```

--------------------------------

### Error Handling Integration Example

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/INDEX.md

Demonstrates the relationship between API module documentation, the central error reference, and recovery strategies.

```text
api-reference/[module].md → errors.md → recovery strategies
```

--------------------------------

### Command Not Found Error Handling

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/cli-reference.md

Example of the error message when a command is not found and the suggested solution.

```bash
$ commando search nonexistent
Error: Couldn't find exact command 'nonexistent'.
Did you mean one of these?
 - ...
```

--------------------------------

### Bash CLI Usage Examples

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/README.md

Shows common command-line interactions with the commando tool, including launching the dashboard, searching commands, and enabling bash completion.

```bash
# Interactive dashboard
commando

# Search command
commando search grep
commando search curl --audit     # With kinetic audit
commando search ls --json        # JSON output

# Bash completion
commando --generate-completion >> ~/.bashrc
source ~/.bashrc
commando gr<TAB>              # Completes to 'grep', 'gzip', etc.
```

--------------------------------

### Dashboard Extension Example

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/INDEX.md

Outlines a path for extending the dashboard module by referencing its API and related I/O utilities.

```text
MODULES.md → api-reference/dashboard.md → api-reference/io-utilities.md
```

--------------------------------

### Scanner Module Examples

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/README.md

Illustrates the use of the scanner module for discovering commands, performing intent-based searches, suggesting commands based on similarity, and sanitizing text.

```python
from commando.core import scanner

# Auto-scan system PATH
scanner.auto_scan_system(state_mgr)
# Discovers unknown commands, saves to pending_imports

# Intent search (keyword matching)
results = scanner.search_intent('delete files', state_mgr)
# Returns: ['rm', 'rmdir', 'shred', ...]

# String similarity suggestion
suggestion = scanner.suggest_command('lsdir', state_mgr)
# Returns: 'ls' (if similarity > 0.6)

# Text sanitization
clean = scanner.sanitize_text("Text\x1b[31mwith\x00control")
# Returns: "Textwithcontrol"
```

--------------------------------

### Example: Audit network behavior of 'curl'

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/cli-reference.md

Demonstrates auditing the network behavior of the 'curl' command using `strace`. The output shows detected behavioral tags.

```bash
$ commando search curl --audit
# Runs: strace -f -e trace=network,file,process curl --help
# Displays: detected behavioral tags
# Example output: [Network Mutator], [File Reader/Writer]
```

--------------------------------

### Manual Index Rebuild Example

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/scanner.md

Forces a rebuild of the command index using `build_inverted_index`. The updated index is saved to a configuration file.

```python
# Force index rebuild for updated command database
index = scanner.build_inverted_index(state_mgr)
# Results saved to ~/.commando/index.json
```

--------------------------------

### Allowed Paths Configuration

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/scanner.md

Example JSON configuration for `allowed_paths`, specifying directories to be scanned for executables. This setting is stored in `~/.commando/config.json`.

```json
{
    "allowed_paths": [
        "/bin",
        "/usr/bin",
        "/data/data/com.termux/files/usr/bin",
        "/system/bin"
    ]
}
```

--------------------------------

### Instantiate ConfigManager Singleton

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/configuration.md

Shows how to get an instance of the thread-safe ConfigManager singleton in Python. Subsequent calls return the same instance.

```python
from commando.utils.config import ConfigManager

config = ConfigManager()  # First call: initializes
config2 = ConfigManager()  # Returns same instance
assert config is config2
```

--------------------------------

### Auto-Scan System Example

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/scanner.md

Initiates an interactive system-wide scan for unknown commands using `auto_scan_system`. This process displays progress and saves pending imports.

```python
# Scan PATH for unknown commands (interactive)
scanner.auto_scan_system(state_mgr)
# TUI displays discovery progress
# Pending imports saved to pending.json
```

--------------------------------

### Get Configuration Value

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/config-manager.md

Retrieves a configuration value using its key. Provides a default value if the key is not found.

```python
allowed_paths = config.get('allowed_paths')
# Result: ['/bin', '/usr/bin', '/data/data/com.termux/files/usr/bin', '/system/bin']

custom_value = config.get('nonexistent_key', 'fallback')
# Result: 'fallback'
```

--------------------------------

### Concurrent Access to ConfigManager

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/config-manager.md

Illustrates safe concurrent access to ConfigManager from multiple threads. The example shows how to retrieve and set configuration values within worker threads, relying on the manager's internal locking mechanism.

```python
import threading

config = ConfigManager()

def worker():
    value = config.get('allowed_paths')
    config.set('auto_hook', False)

threads = [threading.Thread(target=worker) for _ in range(10)]
for t in threads:
    t.start()
for t in threads:
    t.join()

# Safe concurrent access via locking
```

--------------------------------

### Terminal Output with Colors

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/io-utilities.md

Shows how to print colored text and formatted badges to the terminal. Includes examples of basic color application and using the format_badge utility.

```python
from commando.utils.io import CYAN, BOLD, RESET, GREEN, format_badge

print(f"{CYAN}{BOLD}My Title{RESET}")
print(format_badge("File Management"))
print(f"{GREEN}[+]{RESET} Successfully imported command")
```

--------------------------------

### Module Documentation Structure

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/INDEX.md

Each API reference file follows a consistent pattern, detailing module path, function definitions with signatures and parameters, data structures, and integration examples.

```markdown
[Module Name]
├── Module path and import statement
├── Function/Class definitions
│   ├── Signature with types
│   ├── Parameters table
│   ├── Return type and description
│   ├── Error conditions
│   ├── Code examples
│   └── Source file location
├── Data structures
└── Integration examples
```

--------------------------------

### get(key, default=None)

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/config-manager.md

Retrieves a configuration value associated with the given key. If the key is not found, it returns the specified default value.

```APIDOC
## get(key, default=None)

### Description
Retrieves a configuration value by its key. Returns a default value if the key does not exist.

### Method
`get(key: str, default=None)`

### Parameters
#### Path Parameters
- **key** (str) - Required - The configuration key to retrieve.
- **default** (Any) - Optional - The value to return if the key is not found. Defaults to None.

### Returns
`Any` - The configuration value associated with the key, or the default value if the key is not found.

### Usage Example
```python
allowed_paths = config.get('allowed_paths')
custom_value = config.get('nonexistent_key', 'fallback')
```
```

--------------------------------

### Run Quiz

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/dashboard.md

Initiates an adaptive quiz based on command history. Requires at least three commands in the history to start.

```python
run_quiz(state_manager)
# Generates 3 questions from command history
```

--------------------------------

### Configuration Manager Singleton

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/README.md

Demonstrates the usage of the ConfigManager as a thread-safe singleton for managing application settings, including getting and setting configuration values.

```python
from commando.utils.config import ConfigManager

config = ConfigManager()  # Singleton

# Get configuration
allowed_paths = config.get('allowed_paths')
auto_hook = config.get('auto_hook', True)

# Set and persist
config.set('allowed_paths', ['/bin', '/usr/bin'])
```

--------------------------------

### Initialize and Use StateManager

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/state-manager.md

Demonstrates initializing the StateManager, updating command history, saving changes, accepting pending imports, and retrieving all known commands. Ensure the necessary data files exist or will be created in the ~/.commando/ directory.

```python
from commando.main import StateManager

# Initialize
state_manager = StateManager()

# Increment search count for a command
state_manager.session_history['grep'] = state_manager.session_history.get('grep', 0) + 1
state_manager.save_history()

# Accept a pending import as custom
pending = state_manager.get_pending()
if 'new_cmd' in pending:
    state_manager.custom_guide['new_cmd'] = pending['new_cmd']
    state_manager.save_custom()

# View all available commands
all_cmds = state_manager.get_all_known_commands()
for cmd_name in all_cmds:
    print(cmd_name)
```

--------------------------------

### Python Testing Mocks

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/README.md

Provides examples of mocking Python objects for testing purposes, including StateManager, subprocess calls, and file I/O operations.

```python
# Mock StateManager
state_mgr = StateManager()
state_mgr.session_history = {'ls': 1}

# Mock subprocess (for audit/scanner tests)
# Use unittest.mock.patch('subprocess.run')

# Mock file I/O
# Use unittest.mock.patch('pathlib.Path.open')

# Test isolation
# Each test can use independent temp directories
```

--------------------------------

### Basic Command Search

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/audit.md

Displays information about a known command without performing a kinetic audit. Use when you need to show command descriptions and examples to the user.

```python
from commando.core import audit, scanner
from commando.main import StateManager

state_mgr = StateManager()

# Display information about a known command
audit.search_command('grep', state_mgr, scanner, headless=False, audit=False)
# Output: Command info with description and example
```

--------------------------------

### Accept Pending Import

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/dashboard.md

Helper function to move a pending import to the custom guide. It atomically adds to custom_guide, enforces a limit, deletes from pending_imports, and saves both files.

```python
_accept_pending_import('newtool', data_dict, state_manager.custom_guide, state_manager.pending_imports)
```

--------------------------------

### install_bash_hook

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/dashboard.md

Installs the bash `command_not_found_handle` integration. This function interactively prompts the user for confirmation, resolves the script path, and appends a hook snippet to `~/.bashrc` to enable automatic command-not-found integration.

```APIDOC
## install_bash_hook()

### Description
Installs bash `command_not_found_handle` integration. Prompts user for confirmation, resolves script path, reads existing `~/.bashrc` (creates if missing), removes old hook if present, appends new hook snippet, writes atomically via temp file, and displays success message with restart instructions.

**Hook Snippet:**
```bash
# cli-commando auto-search hook
command_not_found_handle() {
    python3 "<script_path>" search -- "$1"
    return 127
}
```

### Parameters
None

### Returns
None
```

--------------------------------

### review_pending_imports

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/dashboard.md

Walks the user through pending import decisions interactively. For each pending command, users can choose to accept, reject, or edit it. The system displays the command's name, category, description, and example, saving changes after each decision.

```APIDOC
## review_pending_imports(state_manager)

### Description
Walk user through pending import decisions. Step-by-step review of each pending import with options:
- **(y) Accept** — move to `custom_guide`, remove from pending
- **(n) Reject** — add to blacklist, remove from pending
- **(e) Edit** — prompt for new description, then accept
- **(q) Quit** — stop reviewing and return to menu

Displays command name, category badge, description, example. Saves changes after each decision.

**Notes:** If no pending imports exist, shows message and returns immediately.

### Parameters
#### Path Parameters
- **state_manager** (StateManager) - Required - StateManager instance with pending_imports

### Returns
None
```

--------------------------------

### Standard Installation

Source: https://github.com/mnemonice/cli-commando/blob/main/README.md

Command to install the CLI Commando tool using pip.

```bash
pip install .
```

--------------------------------

### Development Installation

Source: https://github.com/mnemonice/cli-commando/blob/main/README.md

Command to install the CLI Commando tool in editable mode for active development.

```bash
pip install -e .
```

--------------------------------

### Install Bash Hook

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/cli-reference.md

Install the bash hook for interactive command not found handling. This modifies your ~/.bashrc file.

```bash
# In interactive dashboard, select [8]
# Prompts to install hook to ~/.bashrc
# Then user types unknown command in bash:

$ unknowncmd
bash: unknowncmd: command not found
# Bash automatically invokes:
python3 /path/to/commando search -- unknowncmd
# Commando searches database and displays results
```

--------------------------------

### Install Bash Hook

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/dashboard.md

Installs the bash hook for command-not-found integration. It interactively prompts for confirmation and modifies the ~/.bashrc file.

```python
install_bash_hook()
# Interactive: adds hook to ~/.bashrc
```

--------------------------------

### Initialize StateManager

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/configuration.md

Demonstrates the automatic initialization of the StateManager class in Python, which loads configuration files like history.json and blacklist.json.

```python
from commando.main import StateManager

state_manager = StateManager()  # No parameters
```

--------------------------------

### Bash Hook Usage Example

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/cli-reference.md

Example of how the bash hook works when an unknown command is typed. Bash invokes the hook, which then calls commando search.

```bash
$ unknowncmd
# Bash invokes: python3 /usr/local/bin/commando search -- unknowncmd
# Commando displays info if found
# Returns to bash prompt
# Bash exits with 127
```

--------------------------------

### Basic Commando CLI Usage

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/configuration.md

Demonstrates basic command-line interactions with the Commando CLI for searching and generating completions.

```bash
commando
commando search grep
commando search curl --audit
commando search ls --json
commando --generate-completion
eval "$(commando --generate-completion)"
```

--------------------------------

### Search for a Command

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/README.md

Initialize StateManager and use the audit module to search for a command without auditing.

```python
from commando.main import StateManager
from commando.core import audit, scanner

state_mgr = StateManager()
audit.search_command('grep', state_mgr, scanner, headless=False, audit=False)
```

--------------------------------

### Display Help

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/cli-reference.md

Access the built-in help command definition by searching for 'help'. For general usage, simply run 'commando'.

```bash
commando search help
# Displays: built-in help command definition
```

```bash
commando
# Displays: interactive menu with all options
```

--------------------------------

### Inverted Index Structure

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/scanner.md

An example of an inverted index mapping search terms to related commands.

```json
{
    "search": ["grep", "find"],
    "remove": ["rm", "rmdir", "unlink"],
    "directory": ["ls", "find", "pwd"],
    "...": []
}
```

--------------------------------

### Initialize StateManager

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/state-manager.md

Instantiates the StateManager and loads all persisted data from disk. This is the first step to interact with state management.

```python
state_manager = StateManager()
```

--------------------------------

### Command Metadata Structure

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/types.md

Defines the schema for command dictionaries, including description, example, and category.

```python
CommandMetadata = {
    "desc": str,        # Description of command (40-200 chars typical)
    "example": str,     # Usage example (e.g., "ls -la")
    "category": str,    # Category label (e.g., "File Management")
}
```

--------------------------------

### Start Interactive Dashboard

Source: https://github.com/mnemonice/cli-commando/blob/main/README.md

Command to launch the interactive terminal dashboard for CLI Commando.

```bash
commando
```

--------------------------------

### Backward Compatibility with Default Config

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/config-manager.md

Illustrates how adding new keys to the default configuration automatically applies to existing user configurations upon loading. This ensures backward compatibility when new settings are introduced.

```python
# If code adds new DEFAULT_CONFIG key
DEFAULT_CONFIG['new_setting'] = 'value'

# Existing configs get the new key on next load
config = ConfigManager()
# config.config_data now includes 'new_setting'
```

--------------------------------

### Get Command History

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/state-manager.md

Retrieves the command history with usage counts. Used for ranking commands by mastery level.

```python
history = state_manager.get_history()
# Example: {'mkdir': 2, 'ls': 5, 'grep': 1}
```

--------------------------------

### Strace Timeout Error

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/cli-reference.md

Example of an error message indicating a strace timeout during command audit, and the automatic fallback solution.

```bash
# During audit
Error: Program timed out and was killed.
```

--------------------------------

### Get Inverted Index

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/scanner.md

Retrieves or rebuilds the inverted index. This function ensures you have the latest index available for command searching.

```python
index = get_inverted_index(state_manager)
```

--------------------------------

### Get Pending Imports

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/state-manager.md

Retrieves commands discovered by auto-scan that are awaiting user review. Each pending command includes metadata.

```python
pending = state_manager.get_pending()
# Example: {
#     'customtool': {'desc': '...', 'example': '...', 'category': '...'}
# }
```

--------------------------------

### Singleton Pattern Usage

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/config-manager.md

Demonstrates obtaining and verifying the singleton instance of ConfigManager. Subsequent calls return the same object.

```python
mgr = ConfigManager()  # First call: initializes
mgr2 = ConfigManager()  # Subsequent calls: return same instance
assert mgr is mgr2
```

--------------------------------

### Get All Known Commands

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/state-manager.md

Retrieves a merged dictionary of all commands, combining built-in and custom commands. Useful for search and display.

```python
all_commands = state_manager.get_all_known_commands()
# Example result:
# {
#     'mkdir': {'desc': 'Creates a new directory...', 'example': 'mkdir -p ...', 'category': 'File Management'},
#     'custom_cmd': {...}
# }
```

--------------------------------

### Main Dashboard Loop

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/dashboard.md

Starts the main event loop for dashboard interaction, handling user input and system events.

```python
dashboard.main_loop(state_manager, search_wrapper, scanner.auto_scan_system)
```

--------------------------------

### Load Configuration from File

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/config-manager.md

Manually triggers the loading of configuration settings from the config file or defaults. Typically called internally during initialization.

```python
config._load()
```

--------------------------------

### Complete Configuration Schema

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/configuration.md

Shows the full structure of the CLI-Commando JSON configuration file, including allowed paths, auto-hook settings, and binary lists.

```json
{
    "allowed_paths": [
        "/data/data/com.termux/files/usr/bin",
        "/system/bin",
        "/bin",
        "/usr/bin"
    ],
    "auto_hook": true,
    "trusted_binaries": [],
    "blacklisted_binaries": []
}
```

--------------------------------

### StateManager Constructor

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/state-manager.md

Initializes a StateManager instance and loads all persisted data from disk. This includes command history, custom commands, blacklisted commands, and pending imports from JSON files in the user's home directory.

```APIDOC
## StateManager()

### Description
Initializes a StateManager instance and loads all persisted data from disk.

### Parameters
None

### Returns
`StateManager` instance

### Notes
Automatically converts legacy list-format history to dict format for backward compatibility. Loads data from `history.json`, `custom.json`, `blacklist.json`, and `pending.json` located in `~/.commando/`.
```

--------------------------------

### Scan Results Structure

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/scanner.md

Defines the structure for storing metadata about a scanned command, including its description, example usage, category, and source.

```json
{
    "desc": "A text-search utility",
    "example": "grep -r 'pattern' .",
    "category": "Auto-Imported Libs",
    "source": "OS Manual|Built-in|Static Analysis"
}
```

--------------------------------

### Pipe Command Output

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/cli-reference.md

Examples of piping CLI Commando output to other commands like 'less', redirecting to a file, or processing with 'jq'.

```bash
# Pipe to less for paging
commando search grep | less
```

```bash
# Redirect to file
commando search ls --json > result.json
```

```bash
# Pipe to jq for JSON processing
commando search curl --json | jq '.kinetic_tags'
```

--------------------------------

### Scripting with CLI Commando

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/cli-reference.md

Demonstrates how to use CLI Commando within shell scripts, iterating through commands and processing JSON output.

```bash
#!/bin/bash
for cmd in ls grep rm; do
    commando search "$cmd" --json | jq '.command'
done
```

--------------------------------

### Scanner Integration with Allowed Paths

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/config-manager.md

Demonstrates how the scanner utilizes the 'allowed_paths' configuration to restrict its search for executable files. This ensures that the scanner only discovers binaries within the directories specified in the configuration.

```python
allowed_paths = ConfigManager().get("allowed_paths")
# Scanner restricts PATH discovery to these directories
```

--------------------------------

### Review Pending Imports

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/dashboard.md

Interactively guides the user through accepting, rejecting, or editing pending command imports. If no imports are pending, a message is displayed.

```python
review_pending_imports(state_manager)
# Interactive: accept/reject/edit each pending command
```

--------------------------------

### CLI-Commando Main Module Exports

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/MODULES.md

Shows the direct usage of key components from the `commando.main` module, including `StateManager` and the `cli` entry point.

```python
from commando.main import StateManager, cli

# Direct usage (rarely needed):
from commando.main import BEGINNER_GUIDE
```

--------------------------------

### Configuration Merging Strategy

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/configuration.md

Illustrates how Commando CLI merges new default configurations with existing user configurations.

```python
# Scenario: Code adds new DEFAULT_CONFIG['new_key']
DEFAULT_CONFIG = {
    "old_key": "old_value",
    "new_key": "new_value"  # <-- Added in new version
}

# Existing config.json has only {"old_key": "old_value"}
# On load: merged to {"old_key": "old_value", "new_key": "new_value"}
# Automatically saved on next config.set()
```

--------------------------------

### ConfigManager Constructor

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/api-reference/config-manager.md

Instantiates the ConfigManager. On first call, it initializes configuration data by loading from a file or using defaults. Subsequent calls return the existing singleton instance.

```APIDOC
## ConfigManager()

### Description
Returns the singleton instance of ConfigManager. Initializes configuration on the first call by loading from a file or setting defaults.

### Method
`__new__()`

### Parameters
None

### Returns
`ConfigManager` - The singleton instance of the ConfigManager.

### Usage Example
```python
from commando.utils.config import ConfigManager

config = ConfigManager()
```
```

--------------------------------

### CLI Entry Point Configuration in pyproject.toml

Source: https://github.com/mnemonice/cli-commando/blob/main/_autodocs/configuration.md

Defines the 'commando' command entry point in the pyproject.toml file, specifying the Python module and function to execute.

```toml
[project.scripts]
commando = "commando.main:cli"
```