| Name | sprinkle-ai JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | AI-powered bash command generator that converts natural language descriptions into executable shell commands |
| upload_time | 2025-08-04 16:51:41 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.12 |
| license | MIT License
Copyright (c) 2025 Yair Vogel
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
ai
automation
bash
cli
command-line
natural-language
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Sprinkle
**AI-powered bash command generator that converts natural language descriptions into executable shell commands**
## Abstract
Sprinkle is a Python-based command-line tool that leverages Google's Gemini AI to translate natural language descriptions into syntactically correct bash commands. It supports both simple command generation and template-based substitution for complex multi-step operations. The tool can either output commands for review or execute them directly, with an optional interactive editor for command refinement.
## Installation
### From PyPI (Recommended)
```bash
# Install with pip
pip install sprinkle
# Or install with pipx (recommended for CLI tools)
pipx install sprinkle
```
### Prerequisites
- Python 3.12 or higher
- Google Gemini API key
### Setup
1. Set up your Google Gemini API key:
```bash
export GOOGLE_API_KEY="your-gemini-api-key-here"
```
### Development Installation
If you want to contribute or modify the code:
1. Clone the repository:
```bash
git clone <repository-url>
cd sprinkle
```
2. Install in development mode:
```bash
pip install -e .
```
## Usage
### Basic Command Generation
Convert natural language descriptions to bash commands:
```bash
# Generate and execute a command
sprinkle "list all files in current directory"
# Output command without executing (safe mode)
sprinkle -o "find all python files larger than 1kb"
# Verbose output to see the AI reasoning process
sprinkle -v -o "count lines in all python files"
```
### Template-Based Commands
Use `{{}}` syntax for complex multi-step operations:
```bash
# Generate compound commands with AI substitution
sprinkle -o "{{find all python files}} and {{count the lines}}"
# More complex example
sprinkle -o "{{create backup directory}} then {{copy all config files to backup}}"
```
### Interactive Editing
Use the editor mode to review and modify commands before execution:
```bash
# Open interactive editor before execution
sprinkle -e "compress all log files older than 30 days"
```
### Command Line Options
- `-h, --help`: Show help message and exit
- `-v, --verbose`: Enable verbose output to see AI processing steps
- `-o, --output`: Output commands to stdout instead of executing them
- `-e, --editor`: Open interactive editor to modify commands before execution
### Examples
#### File Operations
```bash
# List files with details
sprinkle -o "show detailed information about all files including hidden ones"
# Output: ls -la
# Find and process files
sprinkle -o "find all JSON files and validate their syntax"
# Output: find . -name "*.json" -exec python -m json.tool {} \; > /dev/null
# Backup with timestamp
sprinkle -o "create a backup of the config directory with current timestamp"
# Output: cp -r config config_backup_$(date +%Y%m%d_%H%M%S)
```
#### System Administration
```bash
# Process management
sprinkle -o "kill all processes containing the word nginx"
# Output: pkill -f nginx
# Disk usage analysis
sprinkle -o "show disk usage of all directories sorted by size"
# Output: du -sh */ | sort -hr
```
#### Template-Based Complex Operations
```bash
# Multi-step file processing
sprinkle -o "{{find all log files older than 7 days}} and {{compress them with gzip}}"
# Output: find . -name "*.log" -mtime +7 and gzip
# Conditional operations
sprinkle -o "{{check if docker is running}} and {{start nginx container if it exists}}"
# Output: systemctl is-active docker and docker start nginx 2>/dev/null || echo "nginx container not found"
```
## Features
- **Natural Language Processing**: Convert plain English descriptions to bash commands
- **Template Substitution**: Use `{{}}` syntax for complex multi-part commands
- **Safety Mode**: Output commands for review before execution (`-o` flag)
- **Interactive Editing**: Modify generated commands before execution (`-e` flag)
- **Verbose Mode**: See AI reasoning and processing steps (`-v` flag)
- **Error Handling**: Automatic inclusion of appropriate error handling and safety flags
- **Command Chaining**: Intelligent use of `&&`, `;`, `|`, and `||` operators
- **POSIX Compatibility**: Generates portable commands when possible
## Safety Notes
- Always use the `-o` flag first to review generated commands before execution
- The tool can execute potentially destructive commands - exercise caution
- Set appropriate file permissions and run in appropriate directories
- Consider using the interactive editor (`-e`) for complex operations
## Requirements
The application requires the following Python packages:
- `langchain>=0.3.26`
- `langchain-google-genai>=1.0.0`
- `pydantic>=2.11.7`
- `textual>=5.2.0`
## Environment Variables
- `GOOGLE_API_KEY`: Required. Your Google Gemini API key for AI command generation.
## License
This project is licensed under the terms specified in the project configuration.
Raw data
{
"_id": null,
"home_page": null,
"name": "sprinkle-ai",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "ai, automation, bash, cli, command-line, natural-language",
"author": null,
"author_email": "Yair <yair@example.com>",
"download_url": "https://files.pythonhosted.org/packages/37/e3/2af12b66d9c139b2e5f1b96cfb3938d87bfc874a1758f022ae562d81965d/sprinkle_ai-0.1.0.tar.gz",
"platform": null,
"description": "# Sprinkle\n\n**AI-powered bash command generator that converts natural language descriptions into executable shell commands**\n\n## Abstract\n\nSprinkle is a Python-based command-line tool that leverages Google's Gemini AI to translate natural language descriptions into syntactically correct bash commands. It supports both simple command generation and template-based substitution for complex multi-step operations. The tool can either output commands for review or execute them directly, with an optional interactive editor for command refinement.\n\n## Installation\n\n### From PyPI (Recommended)\n\n```bash\n# Install with pip\npip install sprinkle\n\n# Or install with pipx (recommended for CLI tools)\npipx install sprinkle\n```\n\n### Prerequisites\n\n- Python 3.12 or higher\n- Google Gemini API key\n\n### Setup\n\n1. Set up your Google Gemini API key:\n```bash\nexport GOOGLE_API_KEY=\"your-gemini-api-key-here\"\n```\n\n### Development Installation\n\nIf you want to contribute or modify the code:\n\n1. Clone the repository:\n```bash\ngit clone <repository-url>\ncd sprinkle\n```\n\n2. Install in development mode:\n```bash\npip install -e .\n```\n\n## Usage\n\n### Basic Command Generation\n\nConvert natural language descriptions to bash commands:\n\n```bash\n# Generate and execute a command\nsprinkle \"list all files in current directory\"\n\n# Output command without executing (safe mode)\nsprinkle -o \"find all python files larger than 1kb\"\n\n# Verbose output to see the AI reasoning process\nsprinkle -v -o \"count lines in all python files\"\n```\n\n### Template-Based Commands\n\nUse `{{}}` syntax for complex multi-step operations:\n\n```bash\n# Generate compound commands with AI substitution\nsprinkle -o \"{{find all python files}} and {{count the lines}}\"\n\n# More complex example\nsprinkle -o \"{{create backup directory}} then {{copy all config files to backup}}\"\n```\n\n### Interactive Editing\n\nUse the editor mode to review and modify commands before execution:\n\n```bash\n# Open interactive editor before execution\nsprinkle -e \"compress all log files older than 30 days\"\n```\n\n### Command Line Options\n\n- `-h, --help`: Show help message and exit\n- `-v, --verbose`: Enable verbose output to see AI processing steps\n- `-o, --output`: Output commands to stdout instead of executing them\n- `-e, --editor`: Open interactive editor to modify commands before execution\n\n### Examples\n\n#### File Operations\n```bash\n# List files with details\nsprinkle -o \"show detailed information about all files including hidden ones\"\n# Output: ls -la\n\n# Find and process files\nsprinkle -o \"find all JSON files and validate their syntax\"\n# Output: find . -name \"*.json\" -exec python -m json.tool {} \\; > /dev/null\n\n# Backup with timestamp\nsprinkle -o \"create a backup of the config directory with current timestamp\"\n# Output: cp -r config config_backup_$(date +%Y%m%d_%H%M%S)\n```\n\n#### System Administration\n```bash\n# Process management\nsprinkle -o \"kill all processes containing the word nginx\"\n# Output: pkill -f nginx\n\n# Disk usage analysis\nsprinkle -o \"show disk usage of all directories sorted by size\"\n# Output: du -sh */ | sort -hr\n```\n\n#### Template-Based Complex Operations\n```bash\n# Multi-step file processing\nsprinkle -o \"{{find all log files older than 7 days}} and {{compress them with gzip}}\"\n# Output: find . -name \"*.log\" -mtime +7 and gzip\n\n# Conditional operations\nsprinkle -o \"{{check if docker is running}} and {{start nginx container if it exists}}\"\n# Output: systemctl is-active docker and docker start nginx 2>/dev/null || echo \"nginx container not found\"\n```\n\n## Features\n\n- **Natural Language Processing**: Convert plain English descriptions to bash commands\n- **Template Substitution**: Use `{{}}` syntax for complex multi-part commands\n- **Safety Mode**: Output commands for review before execution (`-o` flag)\n- **Interactive Editing**: Modify generated commands before execution (`-e` flag)\n- **Verbose Mode**: See AI reasoning and processing steps (`-v` flag)\n- **Error Handling**: Automatic inclusion of appropriate error handling and safety flags\n- **Command Chaining**: Intelligent use of `&&`, `;`, `|`, and `||` operators\n- **POSIX Compatibility**: Generates portable commands when possible\n\n## Safety Notes\n\n- Always use the `-o` flag first to review generated commands before execution\n- The tool can execute potentially destructive commands - exercise caution\n- Set appropriate file permissions and run in appropriate directories\n- Consider using the interactive editor (`-e`) for complex operations\n\n## Requirements\n\nThe application requires the following Python packages:\n- `langchain>=0.3.26`\n- `langchain-google-genai>=1.0.0`\n- `pydantic>=2.11.7`\n- `textual>=5.2.0`\n\n## Environment Variables\n\n- `GOOGLE_API_KEY`: Required. Your Google Gemini API key for AI command generation.\n\n## License\n\nThis project is licensed under the terms specified in the project configuration.",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Yair Vogel\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "AI-powered bash command generator that converts natural language descriptions into executable shell commands",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/yair/sprinkle",
"Issues": "https://github.com/yair/sprinkle/issues",
"Repository": "https://github.com/yair/sprinkle"
},
"split_keywords": [
"ai",
" automation",
" bash",
" cli",
" command-line",
" natural-language"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a06478e14147a2f9baa14a028c4c8847bec525f1d1e6d5e6fca6ed346a29c0e4",
"md5": "aa53e148fe8ff4ec0abea9acc28f29d6",
"sha256": "4c20a4d07fc6e4682d528ed5001192228fa1572196f4a7c33ab52609ccf2547e"
},
"downloads": -1,
"filename": "sprinkle_ai-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "aa53e148fe8ff4ec0abea9acc28f29d6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 4818,
"upload_time": "2025-08-04T16:51:40",
"upload_time_iso_8601": "2025-08-04T16:51:40.594902Z",
"url": "https://files.pythonhosted.org/packages/a0/64/78e14147a2f9baa14a028c4c8847bec525f1d1e6d5e6fca6ed346a29c0e4/sprinkle_ai-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "37e32af12b66d9c139b2e5f1b96cfb3938d87bfc874a1758f022ae562d81965d",
"md5": "0174ccd2ae4e432d139259162f6a936c",
"sha256": "46665857b75c662a0a954f2308daa3abd6771bbd8f1eaa3a9d08a579353fc0f7"
},
"downloads": -1,
"filename": "sprinkle_ai-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "0174ccd2ae4e432d139259162f6a936c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 43874,
"upload_time": "2025-08-04T16:51:41",
"upload_time_iso_8601": "2025-08-04T16:51:41.732470Z",
"url": "https://files.pythonhosted.org/packages/37/e3/2af12b66d9c139b2e5f1b96cfb3938d87bfc874a1758f022ae562d81965d/sprinkle_ai-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-04 16:51:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yair",
"github_project": "sprinkle",
"github_not_found": true,
"lcname": "sprinkle-ai"
}
