rubber-ducky 1.5.3__py3-none-any.whl → 1.6.1__py3-none-any.whl

ducky/ducky.py

@@ -348,9 +348,12 @@ class RubberDuck:
         if host:
             os.environ["OLLAMA_HOST"] = host
             self.client = AsyncClient(host)
+            if "ollama.com" in host:
+                console.print("[dim]Note: Cloud models require authentication[/dim]", style="yellow")
         elif "-cloud" in model_name:
             os.environ["OLLAMA_HOST"] = "https://ollama.com"
             self.client = AsyncClient("https://ollama.com")
+            console.print("[dim]Note: Cloud models require authentication[/dim]", style="yellow")
         else:
             os.environ["OLLAMA_HOST"] = "http://localhost:11434"
             self.client = AsyncClient()
@@ -549,7 +552,10 @@ class InlineInterface:
         # Check if first word is a crumb name
         first_word = stripped.split()[0].lower()
         if self.crumb_manager.has_crumb(first_word):
-            await self._use_crumb(first_word)
+            # Extract additional arguments after the crumb name
+            parts = stripped.split()
+            args = parts[1:]
+            await self._use_crumb(first_word, args)
             return
 
         if stripped.lower() in {":run", "/run"}:
@@ -634,13 +640,16 @@ class InlineInterface:
         console.print()
 
         commands = [
-            ("[bold]/help[/bold]", "Show this help message"),
+            ("[bold]Crumbs:[/bold]", ""),
+            ("[bold]/crumb help[/bold]", "Show detailed crumb commands help"),
             ("[bold]/crumbs[/bold]", "List all saved crumb shortcuts"),
             ("[bold]/crumb <name>[/bold]", "Save last result as a crumb"),
             ("[bold]/crumb add <name> <cmd>[/bold]", "Manually add a crumb"),
             ("[bold]/crumb del <name>[/bold]", "Delete a crumb"),
             ("[bold]<name>[/bold]", "Invoke a saved crumb"),
-            ("[bold]/expand[/bold]", "Show full output of last shell command"),
+            ("", ""),
+            ("[bold]General:[/bold]", ""),
+            ("[bold]/help[/bold]", "Show this help message"),
             ("[bold]/model[/bold]", "Select a model interactively (local or cloud)"),
             (
                 "[bold]/local[/bold]",
@@ -651,10 +660,8 @@ class InlineInterface:
                 "[bold]/clear[/bold] or [bold]/reset[/bold]",
                 "Clear conversation history",
             ),
-            (
-                "[bold]/run[/bold]",
-                "Re-run the last suggested command",
-            ),
+            ("[bold]/expand[/bold]", "Show full output of last shell command"),
+            ("[bold]/run[/bold]", "Re-run the last suggested command"),
             (
                 "[bold]Empty Enter[/bold]",
                 "Re-run suggested command or explain last output",
@@ -666,7 +673,13 @@ class InlineInterface:
         ]
 
         for command, description in commands:
-            console.print(f"{command:<45} {description}")
+            if command:
+                console.print(f"{command:<45} {description}")
+            else:
+                console.print()
+
+        console.print()
+        console.print("[dim]Use /crumb help for detailed crumb command documentation[/dim]")
 
         console.print()
 
@@ -706,9 +719,15 @@ class InlineInterface:
     async def _handle_crumb_command(self, command: str) -> None:
         """Handle /crumb commands."""
         parts = command.split()
+
         if len(parts) == 1:
-            # Just "/crumbs" - show list
-            await self._show_crumbs()
+            # Just "/crumb" - show help
+            await self._show_crumb_help()
+            return
+
+        # Check for help flag or argument
+        if parts[1] in {"help", "--help", "-h"}:
+            await self._show_crumb_help()
             return
 
         if len(parts) == 2:
@@ -721,6 +740,7 @@ class InlineInterface:
             # "/crumb add <name> <...command>"
             if len(parts) < 4:
                 console.print("Usage: /crumb add <name> <command>", style="yellow")
+                console.print("Example: /crumb add deploy docker build -t app:latest", style="dim")
                 return
             name = parts[2]
             cmd = " ".join(parts[3:])
@@ -734,10 +754,50 @@ class InlineInterface:
             return
 
         console.print(
-            "Usage: /crumb <name> | /crumb add <name> <cmd> | /crumb del <name>",
+            "Unknown crumb command. Use /crumb help for usage information.",
             style="yellow",
         )
 
+    async def _show_crumb_help(self) -> None:
+        """Display detailed help for crumb commands."""
+        console.print("\n[bold blue]Crumbs Help[/bold blue]")
+        console.print("=" * 40)
+        console.print()
+
+        console.print("[bold cyan]Commands:[/bold cyan]")
+        console.print()
+
+        commands = [
+            ("[bold]/crumbs[/bold]", "List all saved crumb shortcuts"),
+            ("[bold]/crumb help[/bold]", "Show this help message"),
+            ("[bold]/crumb <name>[/bold]", "Save the last AI-suggested command as a crumb"),
+            ("[bold]/crumb add <name> <cmd>[/bold]", "Manually add a crumb with a specific command"),
+            ("[bold]/crumb del <name>[/bold]", "Delete a saved crumb"),
+            ("[bold]<name>[/bold]", "Invoke a saved crumb by name"),
+        ]
+
+        for command, description in commands:
+            console.print(f"{command:<45} {description}")
+
+        console.print()
+        console.print("[bold cyan]Examples:[/bold cyan]")
+        console.print()
+        console.print("  [dim]# List all crumbs[/dim]")
+        console.print("  >> /crumbs")
+        console.print()
+        console.print("  [dim]# Save last command as 'deploy'[/dim]")
+        console.print("  >> /crumb deploy")
+        console.print()
+        console.print("  [dim]# Manually add a crumb[/dim]")
+        console.print("  >> /crumb add test-run pytest tests/ -v")
+        console.print()
+        console.print("  [dim]# Delete a crumb[/dim]")
+        console.print("  >> /crumb del deploy")
+        console.print()
+        console.print("  [dim]# Run a saved crumb[/dim]")
+        console.print("  >> test-run")
+        console.print()
+
     async def _save_crumb(self, name: str) -> None:
         """Save the last result as a crumb."""
         if not self.assistant.last_result:
@@ -819,8 +879,13 @@ class InlineInterface:
         else:
             console.print(f"Crumb '{name}' not found.", style="yellow")
 
-    async def _use_crumb(self, name: str) -> None:
-        """Recall and execute a saved crumb."""
+    async def _use_crumb(self, name: str, args: list[str] | None = None) -> None:
+        """Recall and execute a saved crumb.
+
+        Args:
+            name: Name of the crumb to execute
+            args: Optional list of arguments to replace ${VAR} placeholders in the command
+        """
         crumb = self.crumb_manager.get_crumb(name)
         if not crumb:
             console.print(f"Crumb '{name}' not found.", style="yellow")
@@ -829,9 +894,13 @@ class InlineInterface:
         explanation = crumb.get("explanation", "") or "No explanation"
         command = crumb.get("command", "") or "No command"
 
+        # Substitute placeholders with provided arguments
+        if args and command != "No command":
+            command = substitute_placeholders(command, args)
+
         console.print(f"\n[bold cyan]Crumb: {name}[/bold cyan]")
         console.print(f"Explanation: {explanation}", style="green")
-        console.print(f"Command: ", style="cyan", end="")
+        console.print("Command: ", style="cyan", end="")
         console.print(command, highlight=False)
 
         if command and command != "No command":
@@ -975,7 +1044,33 @@ async def run_single_prompt(
 ) -> AssistantResult:
     if logger:
         logger.log_user(prompt)
-    result = await rubber_ducky.send_prompt(prompt=prompt, code=code)
+    try:
+        result = await rubber_ducky.send_prompt(prompt=prompt, code=code)
+    except Exception as e:
+        error_msg = str(e)
+        if "unauthorized" in error_msg.lower() or "401" in error_msg:
+            console.print("\n[red]Authentication Error (401)[/red]")
+            console.print("You're trying to use a cloud model but don't have valid credentials.", style="yellow")
+
+            # Check if API key is set
+            api_key = os.environ.get("OLLAMA_API_KEY")
+            if api_key:
+                console.print("\nAn OLLAMA_API_KEY is set, but it appears invalid.", style="yellow")
+            else:
+                console.print("\n[bold]OLLAMA_API_KEY environment variable is not set.[/bold]", style="yellow")
+
+            console.print("\nOptions:", style="bold")
+            console.print("  1. Use --local flag to access local models:", style="dim")
+            console.print("     ducky --local", style="cyan")
+            console.print("  2. Select a local model with /local command", style="dim")
+            console.print("  3. Set up Ollama cloud API credentials:", style="dim")
+            console.print("     export OLLAMA_API_KEY='your-api-key-here'", style="cyan")
+            console.print("\nGet your API key from: https://ollama.com/account/api-keys", style="dim")
+            console.print()
+            raise
+        else:
+            raise
+
     content = result.content or "(No content returned.)"
     console.print(content, style="green", highlight=False)
     if logger:
@@ -1037,7 +1132,7 @@ async def ducky() -> None:
     )
     parser.add_argument(
         "single_prompt",
-        nargs="?",
+        nargs="*",
         help="Run a single prompt and copy the suggested command to clipboard",
         default=None,
     )
@@ -1096,31 +1191,41 @@ async def ducky() -> None:
 
     # Handle crumb invocation mode
     crumb_manager = CrumbManager()
-    if args.single_prompt and crumb_manager.has_crumb(args.single_prompt):
-        crumb = crumb_manager.get_crumb(args.single_prompt)
-        if crumb:
-            explanation = crumb.get("explanation", "") or "No explanation"
-            command = crumb.get("command", "") or "No command"
-
-            console.print(f"\n[bold cyan]Crumb: {args.single_prompt}[/bold cyan]")
-            console.print(f"Explanation: {explanation}", style="green")
-            console.print(f"Command: ", style="cyan", end="")
-            console.print(command, highlight=False)
-
-            if command and command != "No command":
-                # Execute the command
-                await run_shell_and_print(
-                    rubber_ducky,
-                    command,
-                    logger=logger,
-                    history=rubber_ducky.messages,
-                )
-        return
+    if args.single_prompt:
+        first_arg = args.single_prompt[0]
+        if crumb_manager.has_crumb(first_arg):
+            # Extract crumb arguments (everything after the crumb name)
+            crumb_args = args.single_prompt[1:]
+
+            crumb = crumb_manager.get_crumb(first_arg)
+            if crumb:
+                explanation = crumb.get("explanation", "") or "No explanation"
+                command = crumb.get("command", "") or "No command"
+
+                # Substitute placeholders with provided arguments
+                if crumb_args and command != "No command":
+                    command = substitute_placeholders(command, crumb_args)
+
+                console.print(f"\n[bold cyan]Crumb: {first_arg}[/bold cyan]")
+                console.print(f"Explanation: {explanation}", style="green")
+                console.print("Command: ", style="cyan", end="")
+                console.print(command, highlight=False)
+
+                if command and command != "No command":
+                    # Execute the command
+                    await run_shell_and_print(
+                        rubber_ducky,
+                        command,
+                        logger=logger,
+                        history=rubber_ducky.messages,
+                    )
+            return
 
     # Handle single prompt mode
     if args.single_prompt:
+        prompt = " ".join(args.single_prompt)
         result = await run_single_prompt(
-            rubber_ducky, args.single_prompt, code=code, logger=logger
+            rubber_ducky, prompt, code=code, logger=logger
         )
         if result.command:
             if args.yolo:
@@ -1137,6 +1242,35 @@ async def ducky() -> None:
     await interactive_session(rubber_ducky, logger=logger, code=code)
 
 
+def substitute_placeholders(command: str, args: list[str]) -> str:
+    """Replace ${VAR} and $var placeholders in command with provided arguments.
+
+    Args:
+        command: The command string with placeholders
+        args: List of arguments to substitute (first arg replaces first placeholder, etc.)
+
+    Returns:
+        Command with placeholders replaced, falling back to env vars for unreplaced placeholders
+    """
+    result = command
+    arg_index = 0
+    placeholder_pattern = re.compile(r'\$\{([^}]+)\}|\$(\w+)')
+
+    def replace_placeholder(match: re.Match) -> str:
+        nonlocal arg_index
+        # Get the variable name from either ${VAR} or $var format
+        var_name = match.group(1) or match.group(2)
+        if arg_index < len(args):
+            value = args[arg_index]
+            arg_index += 1
+            return value
+        # Fallback to environment variable
+        return os.environ.get(var_name, match.group(0))
+
+    result = placeholder_pattern.sub(replace_placeholder, result)
+    return result
+
+
 def main() -> None:
     asyncio.run(ducky())
 

rubber_ducky-1.6.1.dist-info/METADATA

@@ -0,0 +1,317 @@
+Metadata-Version: 2.4
+Name: rubber-ducky
+Version: 1.6.1
+Summary: Quick CLI do-it-all tool. Use natural language to spit out bash commands
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: colorama>=0.4.6
+Requires-Dist: fastapi>=0.115.11
+Requires-Dist: ollama>=0.6.0
+Requires-Dist: openai>=1.60.2
+Requires-Dist: prompt-toolkit>=3.0.48
+Requires-Dist: rich>=13.9.4
+Requires-Dist: termcolor>=2.5.0
+Dynamic: license-file
+
+# Rubber Ducky
+
+Turn natural language into bash commands without leaving your terminal.
+
+Rubber Ducky is an inline terminal companion that transforms your prompts into runnable shell commands. Paste multi-line context, get smart suggestions, and execute commands instantly.
+
+---
+
+## Quick Start
+
+```bash
+# Install globally (recommended)
+uv tool install rubber-ducky
+
+# Run interactively
+ducky
+
+# Quick one-shot
+ducky "list all files larger than 10MB in current directory"
+
+# From CLI with options
+ducky --model qwen3
+ducky --directory src
+ducky --local
+
+# Or use uvx (requires -- separator)
+uvx rubber-ducky -- --model qwen3
+```
+
+Both `ducky` and `rubber-ducky` executables work identically.
+
+### Requirements
+
+- [Ollama](https://ollama.com) (running locally or using cloud models)
+- Python 3.10+
+
+---
+
+## Features
+
+- **Natural to Shell** - Describe what you want, get the bash command
+- **Model Flexibility** - Switch between local Ollama models and cloud models
+- **Crumbs** - Save and reuse commands with argument substitution
+- **Piped Input** - Pipe output from other commands directly to ducky
+- **Interactive REPL** - Rich terminal experience with history and shortcuts
+- **Code Context** - Preload project code for AI awareness
+- **Clipboard Support** - Copy commands across macOS, Windows, and Linux
+
+---
+
+## Key Concepts
+
+### REPL (Interactive Mode)
+
+Launch `ducky` to start an inline session:
+
+```
+ducky
+```
+
+**Key controls:**
+- `Enter` - Submit prompt
+- `Ctrl+J` - Insert newline (for multi-line prompts)
+- `Empty Enter` - Rerun last command or explain shell output
+- `Ctrl+R` - Re-run last suggested command
+- `Ctrl+S` - Copy last command to clipboard
+- `!<cmd>` - Run shell command immediately
+- `Arrow keys` - Browse history
+- `Ctrl+D` - Exit
+
+### Models
+
+Rubber Ducky supports both local and cloud models:
+
+- `/model` - Interactive model selection
+- `/local` - List local models (localhost:11434)
+- `/cloud` - List cloud models (ollama.com)
+- Last used model is saved automatically
+
+**Startup flags:**
+- `--local` / `-l` - Use local Ollama with qwen3 default
+- `--model <name>` / `-m` - Specify model directly
+
+### Crumbs
+
+Crumbs are saved command shortcuts. Store frequently-used commands or complex workflows:
+
+```
+>> How do I list all running Python processes?
+...
+Suggested: ps aux | grep python | grep -v grep
+>> /crumb pyprocs
+Saved crumb 'pyprocs'!
+```
+
+**Invoke crumb:**
+```
+>> pyprocs
+Crumb: pyprocs
+Command: ps aux | grep python | grep -v grep
+...
+```
+
+**With argument substitution:**
+```bash
+# Crumb command: git worktree add "../$var-$other" -b $var3
+ducky at feature backend develop
+# Executes: git worktree add "../feature-backend" -b develop
+```
+
+---
+
+## Usage Guide
+
+### Interactive Mode
+
+Default mode. Perfect for development sessions.
+
+```bash
+ducky
+```
+
+Load code context for better suggestions:
+
+```bash
+ducky --directory src
+```
+
+### Single-Shot Mode
+
+Get one command suggestion and exit.
+
+```bash
+ducky "find all TODO comments in src/"
+```
+
+Copy to clipboard automatically:
+
+```bash
+ducky "build and run tests"
+```
+
+### Piped Input
+
+Process text from other commands:
+
+```bash
+cat error.log | ducky "what's wrong here?"
+git diff | ducky "summarize these changes"
+```
+
+### Run Without Confirmation
+
+Auto-execute suggested commands:
+
+```bash
+ducky --yolo "restart the nginx service"
+```
+
+---
+
+## Crumbs Quick Reference
+
+| Command | Description |
+|---------|-------------|
+| `/crumbs` | List all saved crumbs |
+| `/crumb <name>` | Save last command as crumb |
+| `/crumb add <name> <cmd>` | Manually add crumb |
+| `/crumb del <name>` | Delete crumb |
+| `<name>` | Execute crumb |
+| `/crumb help` | Detailed crumb help |
+
+**Argument Substitution:**
+
+Crumbs support `${VAR}` and `$var` placeholder styles:
+
+```bash
+# Create crumb with placeholders
+git worktree add "../$var-$other" -b $var3
+
+# Invoke with arguments
+ducky at feature backend develop
+```
+
+Both styles are interchangeable.
+
+---
+
+## Command Reference
+
+### Inline Commands
+
+| Command | Action |
+|---------|--------|
+| `/help` | Show all commands |
+| `/clear` / `/reset` | Clear conversation history |
+| `/model` | Select model (interactive) |
+| `/local` | List local models |
+| `/cloud` | List cloud models |
+| `/run` / `:run` | Re-run last command |
+| `/expand` | Show full output of last shell command |
+
+### CLI Flags
+
+| Flag | Description |
+|------|-------------|
+| `--directory <path>` / `-d` | Preload code from directory |
+| `--model <name>` / `-m` | Specify Ollama model |
+| `--local` / `-l` | Use local Ollama (qwen3 default) |
+| `--yolo` / `-y` | Auto-run without confirmation |
+| `<prompt>` | Single prompt mode (copied to clipboard) |
+
+---
+
+## Tips & Tricks
+
+### Efficient Workflows
+
+```bash
+# Preload project context
+ducky --directory src
+
+# Reuse complex commands with crumbs
+docker ps | ducky "kill all containers"
+>> /crumb killall
+
+# Chain commands
+!ls -la
+ducksy "find large files"
+
+# Use history
+[↑] Recall previous prompts
+[↓] Navigate command history
+```
+
+### Keyboard Shortcuts Reference
+
+| Key | Action |
+|-----|--------|
+| `Enter` | Submit prompt |
+| `Ctrl+J` | Insert newline |
+| `Empty Enter` | Rerun last command or explain |
+| `Ctrl+R` | Re-run last suggested command |
+| `Ctrl+S` | Copy to clipboard |
+| `Ctrl+D` | Exit |
+| `!cmd` | Run shell command directly |
+
+### Crumb Patterns
+
+```bash
+# Save after complex command
+>> docker-compose up -d && wait && docker-compose logs
+>> /crumb start-logs
+
+# Manually add with arguments
+>> /crumb add deploy-prod docker build -t app:latest && docker push app:latest
+
+# Use for common workflows
+>> ls -la
+find . -type f -name "*.py" | xargs wc -l
+>> /crumb count-py
+```
+
+---
+
+## Storage
+
+Rubber Ducky stores data in `~/.ducky/`:
+
+| File | Purpose |
+|------|---------|
+| `prompt_history` | readline-compatible history |
+| `conversation.log` | JSON log of all interactions |
+| `config` | User preferences (last model) |
+| `crumbs.json` | Saved crumb shortcuts |
+
+Delete the entire directory for a fresh start.
+
+---
+
+## Development
+
+```bash
+# Clone and setup
+git clone <repo>
+cd ducky
+uv sync
+
+# Run
+uv run ducky --help
+uv run ducky
+
+# Lint
+uv run ruff check .
+```
+
+---
+
+## License
+
+MIT © 2023 Parth Sareen

{rubber_ducky-1.5.3.dist-info → rubber_ducky-1.6.1.dist-info}/RECORD

@@ -1,13 +1,13 @@
 ducky/__init__.py,sha256=2vLhJxOuJ3lnIeg5rmF6xUvybUT5Qhjej6AS0BeBASY,60
 ducky/config.py,sha256=Lh7xTUYh4i8Gxgrl0oTYadZB_72Wy2BKIqLCcDQduOA,2116
 ducky/crumb.py,sha256=7BlyjD81-cZptYxQM97y6gOGdVDBF2qzxW0xbPqbspE,2693
-ducky/ducky.py,sha256=bAU-hck3T9ZomrWtmh8E9bu3WZ2p3ektNdm_sDhL8kE,41582
+ducky/ducky.py,sha256=LMAp1ZV7dR-NR6uoSiUpfcanHXU1eRA55Q0jB_ViMwo,47374
 examples/POLLING_USER_GUIDE.md,sha256=rMEAczZhpgyJ9BgwHkN-SKwSdyas8nlw_CjpV7SFOLA,10685
 examples/mock-logs/info.txt,sha256=apJqEO__UM1R2_2x9MlQOA7XmxvLvbhRvOy-FAwrINo,258
 examples/mock-logs/mock-logs.sh,sha256=zM2JSaCR1eCQLlMvXDWjFnpxZTqrMpnFRa_SgNLPmBk,1132
-rubber_ducky-1.5.3.dist-info/licenses/LICENSE,sha256=gQ1rCmw18NqTk5GxG96F6vgyN70e1c4kcKUtWDwdNaE,1069
-rubber_ducky-1.5.3.dist-info/METADATA,sha256=3MwsGVph0L8spjytrZQx_E6St4gW1LxJlBcOIFLMZhk,6733
-rubber_ducky-1.5.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-rubber_ducky-1.5.3.dist-info/entry_points.txt,sha256=WPnVUUNvWdMDcBlCo8JCzkLghGllMX5QVZyQghyq85Q,75
-rubber_ducky-1.5.3.dist-info/top_level.txt,sha256=hid_mDkugR6XIeravFKuzcRPpuN_ylN3ejC_06Fmnb4,15
-rubber_ducky-1.5.3.dist-info/RECORD,,
+rubber_ducky-1.6.1.dist-info/licenses/LICENSE,sha256=gQ1rCmw18NqTk5GxG96F6vgyN70e1c4kcKUtWDwdNaE,1069
+rubber_ducky-1.6.1.dist-info/METADATA,sha256=lZZ9iHVNunf7cJuyN7lLQK9vA1WUBVX3SGGWG4c7Mok,6638
+rubber_ducky-1.6.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+rubber_ducky-1.6.1.dist-info/entry_points.txt,sha256=WPnVUUNvWdMDcBlCo8JCzkLghGllMX5QVZyQghyq85Q,75
+rubber_ducky-1.6.1.dist-info/top_level.txt,sha256=hid_mDkugR6XIeravFKuzcRPpuN_ylN3ejC_06Fmnb4,15
+rubber_ducky-1.6.1.dist-info/RECORD,,

rubber_ducky-1.5.3.dist-info/METADATA

@@ -1,198 +0,0 @@
-Metadata-Version: 2.4
-Name: rubber-ducky
-Version: 1.5.3
-Summary: Quick CLI do-it-all tool. Use natural language to spit out bash commands
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: colorama>=0.4.6
-Requires-Dist: fastapi>=0.115.11
-Requires-Dist: ollama>=0.6.0
-Requires-Dist: openai>=1.60.2
-Requires-Dist: prompt-toolkit>=3.0.48
-Requires-Dist: rich>=13.9.4
-Requires-Dist: termcolor>=2.5.0
-Dynamic: license-file
-
-# Rubber Ducky
-
-Rubber Ducky is an inline terminal companion that turns natural language prompts into runnable shell commands. Paste multi-line context, get a suggested command, and run it without leaving your terminal.
-
-## Quick Start
-
-| Action | Command |
-| --- | --- |
-| Install globally | `uv tool install rubber-ducky` |
-| Run once | `uvx rubber-ducky -- --help` |
-| Local install | `uv pip install rubber-ducky` |
-
-Requirements:
-- [Ollama](https://ollama.com) running locally or use cloud models
-- Model available via Ollama (default: `glm-4.7:cloud`)
-
-## Usage
-
-```
-ducky                      # interactive inline session
-ducky --directory src      # preload code from a directory
-ducky --model qwen3        # use a different Ollama model
-ducky --local              # use local models with qwen3 default
-```
-
-Both `ducky` and `rubber-ducky` executables map to the same CLI, so `uvx rubber-ducky -- <args>` works as well.
-
-### Inline Session (default)
-
-Launching `ducky` with no arguments opens the inline interface:
-- **Enter** submits; **Ctrl+J** inserts a newline (helpful when crafting multi-line prompts). Hitting **Enter on an empty prompt** reruns the latest suggested command; if none exists yet, it explains the most recent shell output.
-- **Ctrl+R** re-runs the last suggested command.
-- **Ctrl+S** copies the last suggested command to clipboard.
-- Prefix any line with **`!`** (e.g., `!ls -la`) to run a shell command immediately.
-- Arrow keys browse prompt history, backed by `~/.ducky/prompt_history`.
-- Every prompt, assistant response, and executed command is logged to `~/.ducky/conversation.log`.
-- Press **Ctrl+D** on an empty line to exit.
-- Non-interactive runs such as `cat prompt.txt | ducky` print one response (and suggested command) before exiting; if a TTY is available you'll be asked whether to run the suggested command immediately.
-- If `prompt_toolkit` is unavailable in your environment, Rubber Ducky falls back to a basic input loop (no history or shortcuts); install `prompt-toolkit>=3.0.48` to unlock the richer UI.
-
-`ducky --directory <path>` streams the contents of the provided directory to the assistant the next time you submit a prompt (the directory is read once at startup).
-
-### Model Management
-
-Rubber Ducky now supports easy switching between local and cloud models:
-- **`/model`** - Interactive model selection between local and cloud models
-- **`/local`** - List and select from local models (localhost:11434)
-- **`/cloud`** - List and select from cloud models (ollama.com)
-- Last used model is automatically saved and loaded on startup
-- Type **`esc`** during model selection to cancel
-
-### Additional Commands
-
-- **`/help`** - Show all available commands and shortcuts
-- **`/crumbs`** - List all saved crumb shortcuts
-- **`/crumb <name>`** - Save the last AI-suggested command as a named crumb
-- **`/crumb add <name> <command>`** - Manually add a crumb with a specific command
-- **`/crumb del <name>`** - Delete a saved crumb
-- **`<crumb-name>`** - Invoke a saved crumb (displays info and executes the command)
-- **`/clear`** or **`/reset`** - Clear conversation history
-- **`/run`** or **`:run`** - Re-run the last suggested command
-
-## Crumbs
-
-Crumbs are saved command shortcuts that let you quickly reuse AI-generated bash commands without regenerating them each time. Perfect for frequently-used workflows or complex commands.
-
-### Saving Crumbs
-
-When the AI suggests a command that you want to reuse:
-
-1. Get a command suggestion from ducky
-2. Save it immediately: `/crumb <name>`
-3. Example:
-   ```
-   >> How do I list all Ollama processes?
-   ...
-   Suggested command: ps aux | grep -i ollama | grep -v grep
-   >> /crumb ols
-   Saved crumb 'ols'!
-   Generating explanation...
-   Explanation added: Finds and lists all running Ollama processes.
-   ```
-
-The crumb is saved with:
-- The original command
-- An AI-generated one-line explanation
-- A timestamp
-
-### Invoking Crumbs
-
-Simply type the crumb name in the REPL or use it as a CLI argument:
-
-**In REPL:**
-```
->> ols
-
-Crumb: ols
-Explanation: Finds and lists all running Ollama processes.
-Command: ps aux | grep -i ollama | grep -v grep
-
-$ ps aux | grep -i ollama | grep -v grep
-user123  12345  0.3  1.2  456789  98765 ?  Sl  10:00   0:05 ollama serve
-```
-
-**From CLI:**
-```bash
-ducky ols              # Runs the saved crumb and displays output
-```
-
-When you invoke a crumb:
-1. It displays the crumb name, explanation, and command
-2. Automatically executes the command
-3. Shows the output
-
-### Managing Crumbs
-
-**List all crumbs:**
-```bash
->> /crumbs
-```
-
-Output:
-```
-Saved Crumbs
-=============
-ols      | Finds and lists all running Ollama processes. | ps aux | grep -i ollama | grep -v grep
-test     | Run tests and build project                  | pytest && python build.py
-deploy   | Deploy to production                         | docker push app:latest
-```
-
-**Manually add a crumb:**
-```bash
->> /crumb add deploy-prod docker build -t app:latest && docker push app:latest
-```
-
-**Delete a crumb:**
-```bash
->> /crumb ols
-Deleted crumb 'ols'.
-```
-
-### Storage
-
-Crumbs are stored in `~/.ducky/crumbs.json` as JSON. Each crumb includes:
-- `prompt`: Original user prompt
-- `response`: AI's full response
-- `command`: The suggested bash command
-- `explanation`: AI-generated one-line summary
-- `created_at`: ISO timestamp
-
-**Example:**
-```json
-{
-  "ols": {
-    "prompt": "How do I list all Ollama processes?",
-    "response": "To list all running Ollama processes...",
-    "command": "ps aux | grep -i ollama | grep -v grep",
-    "explanation": "Finds and lists all running Ollama processes.",
-    "created_at": "2024-01-05T10:30:00.000000+00:00"
-  }
-}
-```
-
-Delete `~/.ducky/crumbs.json` to clear all saved crumbs.
-
-## Development (uv)
-
-```
-uv sync
-uv run ducky --help
-```
-
-`uv sync` creates a virtual environment and installs dependencies defined in `pyproject.toml` / `uv.lock`.
-
-## Telemetry & Storage
-
-Rubber Ducky stores:
-- `~/.ducky/prompt_history`: readline-compatible history file.
-- `~/.ducky/conversation.log`: JSON lines with timestamps for prompts, assistant messages, and shell executions.
-- `~/.ducky/config`: User preferences including last selected model.
-
-No other telemetry is collected; delete the directory if you want a fresh slate.