{"id":17873937,"url":"https://github.com/biont/shellm","last_synced_at":"2025-07-24T01:03:55.505Z","repository":{"id":259784857,"uuid":"879060192","full_name":"Biont/shellm","owner":"Biont","description":"A one-file Ollama CLI client written in bash","archived":false,"fork":false,"pushed_at":"2024-11-10T20:45:48.000Z","size":96,"stargazers_count":25,"open_issues_count":2,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-02T23:34:05.005Z","etag":null,"topics":["agent","ai","bash","llm","ollama","ollama-api","ollama-client"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Biont.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-26T21:22:46.000Z","updated_at":"2025-03-08T20:15:53.000Z","dependencies_parsed_at":"2024-10-28T01:34:44.164Z","dependency_job_id":"7138402a-1a75-44d8-bd86-e208cde29539","html_url":"https://github.com/Biont/shellm","commit_stats":null,"previous_names":["biont/shellm"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Biont/shellm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Biont%2Fshellm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Biont%2Fshellm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Biont%2Fshellm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Biont%2Fshellm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Biont","download_url":"https://codeload.github.com/Biont/shellm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Biont%2Fshellm/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266775354,"owners_count":23982273,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai","bash","llm","ollama","ollama-api","ollama-client"],"created_at":"2024-10-28T11:06:08.445Z","updated_at":"2025-07-24T01:03:55.388Z","avatar_url":"https://github.com/Biont.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Shellm: A Simple Ollama Client\n\n![shellm header image](https://github.com/user-attachments/assets/013184c1-56d7-4fb5-ad7f-7adb2970b77f)\n\n**Shellm** is a lightweight client for interacting with the [Ollama](https://ollama.com/) API, written entirely in a single Bash script. It provides a simple interface to generate responses from language models, interact with custom tools, and integrate AI capabilities into everyday Linux workflows.\n\n## Features\n\n- **Single File Script**: No complex dependencies—just a single Bash file.\n- **API Integration**: Interacts with an Ollama API server to generate predictions.\n- **Tool Execution**: Support for toolchain execution using custom JSON-defined tools.\n- **Expandable**: Tools are read from `config.yaml` files according to XDG Base Dir spec. Add your own!\n- **Model Download**: Transparently instructs Ollama to download unknown models\n- **Piping and Chaining**: Seamless integration into shell commands for input/output manipulation.\n- **Verbose Mode**: Detailed debugging for troubleshooting or learning.\n\n## Installation\n\n1. Save the `shellm` Bash script to a directory of your choice, e.g., `/usr/local/bin`.\n2. Make the script executable:\n   ```bash\n   chmod +x /usr/local/bin/shellm\n   ```\n3. Download the [config YAML](https://github.com/Biont/shellm/blob/main/config.yaml) and place it in [one of the recognized paths](https://github.com/Biont/shellm/blob/0141e467e96c6c06d30423bc292282d256a0d5b3/shellm#L68)\n4. Ensure the Ollama API is running on `localhost:11434` or set the `API_URL` environment variable to your specific endpoint.\n\n## Usage\n\n### Basic Command\n```bash\nshellm \"What is the weather like today?\"\n```\n\nThis will generate a response using the default model.\n\n### Options\n\n| Option     | Description                                                                                         |\n|------------|-----------------------------------------------------------------------------------------------------|\n| `-u`       | API URL (default: `http://localhost:11434/api`)                                                     |\n| `-m`       | Model name (default: `qwen2.5:3b-instruct-q5_K_M`)                                                  |\n| `-n`       | Number of predictions to generate (default: `200`)                                                  |\n| `-v [0-3]` | Log level (verbosity) mode for debugging                                                            |\n| `-t`       | Activate tool use, allowing Shellm to use and chain tools as specified in JSON configuration files. |\n| `prompt`   | The prompt for the model. If reading from stdin, this will prepend to the input.                    |\n\n### Example Commands\n\n#### Simple Prompt\nGenerate a response to a simple question:\n```bash\nshellm \"Why is the sky blue?\"\n```\n\n#### Custom Model\nUse a different model:\n```bash\nshellm -m \"newmodel-v1:6b\" \"Summarize the plot of 'The Great Gatsby'.\"\n```\n\n#### Use Tools\nEnable tool usage mode:\n```bash\nshellm -t \"Translate the following text to French: 'Hello, how are you?'\"\n```\n\n## Advanced Usage\n\n### Chaining Multiple Invocations\n\nShellm supports chaining multiple invocations, allowing the user to pass the output of one command as the input to the next. This is useful for refining AI responses or handling complex tasks:\n\n```bash\nresponse=$(shellm \"What is the capital of France?\")\nshellm \"Is $response a popular tourist destination?\"\n```\n\n### Integration with Linux Tasks\n\nShellm can be easily integrated into daily Linux workflows using piping. Here are a few examples:\n\n#### Example: File Content Summarization\nTo summarize the contents of a file:\n```bash\ncat myfile.txt | shellm \"Summarize this text\"\n```\n\n#### Example: AI-Powered Directory Listing\nGenerate a human-readable summary of files in a directory:\n```bash\nls -l | shellm \"Explain what these files are.\"\n```\n\n#### Example: Translating System Logs\nTo translate system logs to another language:\n```bash\njournalctl -xe | shellm -t \"Translate this to Spanish.\"\n```\n\n### Tool Calling\n\nShellm supports user-defined tools specified in JSON files. This allows Shellm to perform operations beyond simple language model predictions, such as executing shell commands or interacting with APIs. \nThis functionality is highly experimental and new tools will be added as soon as the underlying tool pipeline is more robust.\n\nTools are read from the `config.yaml` file which is searched in the following directories (priority order):\n\n1. `$XDG_CONFIG_HOME/shellm/config.yaml`\n2. `~/.config/shellm/config.yaml`\n3. `~/config.yaml`\n4. `$(dirname \"$0\")/config.yaml` (same directory as the script)\n\n#### Tool Definition Example\n\nHere’s a sample tool configuration within `config.yaml`:\n```yaml\nexecute_shell_command:\n  type: function\n  function:\n     name: execute_shell_command\n     description: \u003e-\n        Executes the specified shell command. Bash syntax allowed. The command string must be complete with all arguments, parameters, redirections and pipes. Multi-line commands are allowed.\n     parameters:\n        type: object\n        properties:\n           command:\n              type: string\n              description: \u003e-\n                 The shell command with all arguments. Warning: It is passed into eval as-is.\n              raw: true\n        required:\n           - command\n     exec: '{{command}}'\ngenerate:\n  type: function\n  function:\n     name: generate\n     description: Display LLM-generated output to the user.\n     parameters:\n        type: object\n        properties:\n           prompt:\n              type: string\n              description: \u003e-\n                 The prompt to be passed to the completion endpoint. Supports both\n                 Chat-like instructions and generic prediction/completion.\n           json:\n              type: boolean\n              description: \u003e-\n                 Set to true to format the output as JSON. Works only if JSON is also\n                 used in the prompt\n        required:\n           - prompt\n     # language=sh\n     exec: |\n        generate_response \"{{prompt}}\" 200\n```\n\n#### Example Tool Usage\nWhen tools are enabled (`-t` flag), Shellm can chain tool calls. Example:\n\n```bash\nshellm -t \"Get the current date and time and tell me if it's a weekend.\"\n```\n\n### Tool Execution Workflow\n\nShellm's tool execution works in multiple steps:\n\n1. **Parse Request**: The initial prompt is analyzed, and the AI identifies which tools to use.\n2. **Tool Execution**: Shellm executes the tools in sequence, using their output for the next tool if necessary.\n3. **Final Output**: The result is formatted and presented using a final `say` tool call.\n\n## Environment Variables\n\n| Variable        | Description                                   | Default                              |\n|-----------------|-----------------------------------------------|--------------------------------------|\n| `API_URL`       | URL of the Ollama API                          | `http://localhost:11434/api`         |\n| `MODEL_SMALL`   | Default model to use                           | `qwen2.5:3b-instruct-q5_K_M`         |\n| `VERBOSE`       | Enable verbose output                          | `0`                                  |\n| `USE_TOOL`      | Enable tool usage mode                         | `0`                                  |\n\n## Debugging\n\nFor verbose output, use the `-v` flag and specify the desired log level:\n\n * `-v 0` - Errors only\n * `-v 1` - Add warnings\n * `-v 2` - Add logs specific to tool use\n * `-v 3` - Add debug output\n\n```bash\nshellm -v 3 \"Debug the script behavior.\"\n```\n## About the name\n\nApart from banking on the significant overlap between \"shell\" and \"llm\", the name \"Shellm\" is also extremely close in spelling and pronunciation to the German word \"Schelm\", which means \"rogue\", or \"jokester\".\nThis adds charm and character to the tool, so bear this in mind when it fails spectacularly.\n\n## Contributing\n\nContributions are welcome! Feel free to open issues or submit pull requests for bug fixes or new features.\n\n## License\n\nShellm is released under the GPL License. See the [LICENSE](LICENSE) file for more details.\n\nEnjoy using Shellm to bring AI capabilities directly into your shell! 😊\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbiont%2Fshellm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbiont%2Fshellm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbiont%2Fshellm/lists"}