{"id":26686787,"url":"https://github.com/statico/llmscript","last_synced_at":"2026-04-12T03:01:49.233Z","repository":{"id":284464948,"uuid":"954882273","full_name":"statico/llmscript","owner":"statico","description":"🧑‍💻 Write your shell scripts in natural language","archived":false,"fork":false,"pushed_at":"2025-03-26T03:01:17.000Z","size":116,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-26T03:23:46.277Z","etag":null,"topics":["bash","chatgpt","claude","cli","command-line","command-line-tool","go","golang","llm","llms","ollama","openai","shell","shell-script","shell-scripting","shell-scripts","tools","unix"],"latest_commit_sha":null,"homepage":"https://github.com/statico/llmscript/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/statico.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":"2025-03-25T19:02:30.000Z","updated_at":"2025-03-26T03:10:57.000Z","dependencies_parsed_at":"2025-03-31T20:45:18.824Z","dependency_job_id":null,"html_url":"https://github.com/statico/llmscript","commit_stats":null,"previous_names":["statico/llmscript"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/statico/llmscript","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statico%2Fllmscript","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statico%2Fllmscript/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statico%2Fllmscript/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statico%2Fllmscript/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/statico","download_url":"https://codeload.github.com/statico/llmscript/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statico%2Fllmscript/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31702581,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-11T21:17:31.016Z","status":"online","status_checked_at":"2026-04-12T02:00:06.763Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","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":["bash","chatgpt","claude","cli","command-line","command-line-tool","go","golang","llm","llms","ollama","openai","shell","shell-script","shell-scripting","shell-scripts","tools","unix"],"created_at":"2025-03-26T12:14:30.520Z","updated_at":"2026-04-12T03:01:49.207Z","avatar_url":"https://github.com/statico.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# llmscript\n\n[![CI](https://github.com/statico/llmscript/actions/workflows/ci.yml/badge.svg)](https://github.com/statico/llmscript/actions/workflows/ci.yml)\n\nllmscript is a shell script that uses a large language model (LLM) to build and test shell programs so that you can write scripts in natural language instead of bash or other shell scripting languages.\n\n\u003cimg src=\"https://github.com/user-attachments/assets/6257eb3c-fe66-41b0-9b45-39ec29b40a3a\" width=\"640\" alt=\"a terminal window showing a demonstration of the llmscript tool to print hello world\" /\u003e\n\nYou can configure it to use [Ollama](https://ollama.com/) (free and local), [Claude](https://www.anthropic.com/claude) (paid), or [OpenAI](https://openai.com/) (paid).\n\n\u003e [!NOTE]\n\u003e Does this actually work? Yeah, somewhat! Could it create scripts that erase your drive? Maybe! Good luck!\n\u003e\n\u003e Most of this project was written by [Claude](https://www.anthropic.com/claude) with [Cursor](https://www.cursor.com). I can't actually claim that I \"wrote\" any of the source code. I barely know Go.\n\n## Example\n\n```\n#!/usr/bin/env llmscript\n\nCreate an output directory, `output`.\nFor every PNG file in `input`:\n  - Convert it to 256x256 with ImageMagick\n  - Run pngcrush\n```\n\nRunning it with a directory of PNG files would look like this:\n\n```\n$ ./convert-pngs\n✓ Script generated successfully!\nCreating output directory\nConvering input/1.png\nConvering input/2.png\nConvering input/3.png\nRunning pngcrush on output/1.png\nRunning pngcrush on output/2.png\nRunning pngcrush on output/3.png\nDone!\n```\n\nRunning it again will use the cache and not generate any new scripts:\n\n```\n$ ./convert-pngs\n✓ Cached script found\nCreating output directory\nConvering input/1.png\n...\n```\n\nIf you want to generate a new script, use the `--no-cache` flag.\n\n## Prerequisites\n\n- [Go](https://go.dev/) (1.22 or later)\n- One of:\n  - [Ollama](https://ollama.com/) running locally\n  - A [Claude](https://www.anthropic.com/claude) API key\n  - An [OpenAI](https://openai.com/) API key\n\n## Installation\n\n```\ngo install github.com/statico/llmscript/cmd/llmscript@latest\n```\n\n(Can't find it? Check `~/go/bin`.)\n\nOr, if you're spooked by running LLM-generated shell scripts (good for you!), consider running llmscript via Docker:\n\n```\ndocker run --network host -it -v \"$(pwd):/data\" -w /data ghcr.io/statico/llmscript --verbose examples/hello-world\n```\n\n## Usage\n\nCreate a script file like the above example, or check out the [examples](examples) directory for more. You can use a shebang like:\n\n```\n#!/usr/bin/env llmscript\n```\n\nor run it directly like:\n\n```\n$ llmscript hello-world\n```\n\nBy default, llmscript will use Ollama with the `llama3.2` model. You can configure this by creating a config file with the `llmscript --write-config` command to create a config file in `~/.config/llmscript/config.yaml` which you can edit. You can also use command-line args (see below).\n\n## How it works\n\nWant to see it all in action? Run `llmscript --verbose examples/hello-world`\n\nGiven a script description written in natural language, llmscript works by:\n\n1. Generating a feature script that implements the functionality\n2. Generating a test script that verifies the feature script works correctly\n3. Running the test script to verify the feature script works correctly, fixing the feature script if necessary, possibly going back to step 1 if the test script fails too many times\n4. Caching the scripts for future use\n5. Running the feature script with any additional arguments you provide\n\nFor example, given a simple hello world script:\n\n```\n#!/usr/bin/env llmscript\n\nPrint hello world\n```\n\nllmscript might generate the following feature script:\n\n```bash\n#!/bin/bash\necho \"Hello, world!\"\n```\n\n...and the following test script to test it:\n\n```bash\n#!/bin/bash\n[ \"$(./script.sh)\" = \"Hello, world!\" ] || exit 1\n```\n\n## Configuration\n\nllmscript can be configured using a YAML file located at `~/.config/llmscript/config.yaml`. You can auto-generate a configuration file using the `llmscript --write-config` command.\n\nHere's an example configuration:\n\n```yaml\n# LLM configuration\nllm:\n  # The LLM provider to use (required)\n  provider: \"ollama\" # or \"claude\", \"openai\", etc.\n\n  # Provider-specific settings\n  ollama:\n    model: \"llama3.2\" # The model to use\n    host: \"http://localhost:11434\" # Optional: Ollama host URL\n\n  claude:\n    api_key: \"${CLAUDE_API_KEY}\" # Environment variable reference\n    model: \"claude-3-opus-20240229\"\n\n  openai:\n    api_key: \"${OPENAI_API_KEY}\"\n    model: \"gpt-4-turbo-preview\"\n\n# Maximum number of attempts to fix the script allowed before restarting from step 2\nmax_fixes: 10\n\n# Maximum number of attempts to generate a working script before giving up completely\nmax_attempts: 3\n\n# Timeout for script execution during testing (in seconds)\ntimeout: 30\n\n# Additional prompt to provide to the LLM\nadditional_prompt: |\n  Use ANSI color codes to make the output more readable.\n```\n\n### Environment Variables\n\nYou can use environment variables in the configuration file using the `${VAR_NAME}` syntax. This is particularly useful for API keys and sensitive information.\n\n### Configuration Precedence\n\n1. Command line flags (highest priority)\n2. Environment variables\n3. Configuration file\n4. Default values (lowest priority)\n\n### Command Line Flags\n\nYou can override configuration settings using command line flags:\n\n```shell\nllmscript --llm.provider=claude --timeout=10 script.txt\n```\n\n## Caveats\n\n\u003e [!WARNING]\n\u003e This is an experimental project. It generates and executes shell scripts, which could be dangerous if the LLM generates malicious code. Use at your own risk and always review generated scripts before running them.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatico%2Fllmscript","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstatico%2Fllmscript","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatico%2Fllmscript/lists"}