README.md (8609B)
1 # Githrun 2 3 Githrun is a versatile command-line tool and VS Code extension that enables you to execute, explore, and install Python scripts directly from GitHub and Gists. It streamlines remote execution by handling dependencies, private repositories, and local tool installation. 4 5 [](https://pypi.org/project/githrun/) [](https://pypi.org/project/githrun/) [](https://github.com/notamitgamer/githrun/blob/main/LICENSE) [](https://pepy.tech/project/githrun) [](https://github.com/notamitgamer/githrun/commits/main) [](https://github.com/notamitgamer/githrun/graphs/contributors) 6 7 <a href="https://www.producthunt.com/products/githrun?embed=true&utm_source=badge-featured&utm_medium=badge&utm_campaign=badge-githrun" target="_blank" rel="noopener noreferrer"><img alt="Githrun - Execute remote Python scripts directly from GitHub. | Product Hunt" width="250" height="54" src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1078250&theme=light&t=1770971505390"></a> 8 <a href="https://www.producthunt.com/products/githrun/reviews/new?utm_source=badge-product_review&utm_medium=badge&utm_source=badge-githrun" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/product_review.svg?product_id=1163407&theme=light" alt="Githrun - Execute remote Python scripts directly from GitHub. | Product Hunt" style="width: 250px; height: 54px;" width="250" height="54" /></a> 9 <a href="https://www.producthunt.com/products/githrun?utm_source=badge-follow&utm_medium=badge&utm_source=badge-githrun" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/follow.svg?product_id=1163407&theme=light" alt="Githrun - Execute remote Python scripts directly from GitHub. | Product Hunt" style="width: 250px; height: 54px;" width="250" height="54" /></a> 10 --- 11 12 # VS Code Extension 13 14 ## Extension Installation & Setup 15 16 ### 1. Install the Extension 17 * **Marketplace:** Search for "Githrun" in the VS Code Extensions view and click Install. 18 * **Manual:** If installing from a VSIX file, go to Extensions -> ... -> Install from VSIX. 19 20 ### 2. Install the Core CLI (Required) 21 This extension acts as a bridge to the Githrun command-line tool. You **must** have the Githrun CLI installed on your system. 22 23 Open your terminal and run: 24 25 ```bash 26 pip install githrun 27 ``` 28 29 ## Extension Features & Usage 30 31 ### CodeLens Integration 32 The extension automatically scans Markdown, Python, and Text files for GitHub or Gist URLs. 33 * **Action:** Look for the "Run with Githrun" link appearing above any detected URL. 34 * **Click:** Clicking the link opens a terminal and executes the script immediately. 35 36 ### Context Menu 37 * **Action:** Highlight any GitHub URL in your editor. 38 * **Click:** Right-click the selection and choose **Githrun: Run Selected Text**. 39 40 ### Command Palette 41 * **Action:** Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on Mac). 42 * **Command:** Type `Githrun: Run from URL...` and paste your target link into the input box. 43 44 ## Extension Settings 45 The extension attempts to automatically detect your Githrun installation. 46 * It first checks for `githrun` in your global PATH. 47 * If not found, it tries `python -m githrun` (or `python3` on Mac/Linux). 48 49 --- 50 51 ## Features 52 53 * **Remote Execution**: Run scripts from GitHub or Gist URLs instantly. 54 * **Auto-Dependency Management**: Automatically creates temporary virtual environments and installs missing packages using the `--auto-install` flag. 55 * **Private Repo Access**: Authenticate securely with GitHub tokens to access private code and increase API rate limits. 56 * **Bookmarks**: Save long URLs as short aliases (e.g., `githrun run clean-db`). 57 * **Tool Installation**: Install remote scripts as permanent local CLI commands available in your system path. 58 * **Recursive Downloads**: Download entire folders or specific sub-directories from a repository. 59 * **Interactive Search**: Search for files in a repo and run them immediately from the results. 60 * **Smart Caching**: Caches API responses to speed up repeated searches and reduce API usage. 61 62 --- 63 64 ## CLI Usage 65 66 ### 1. Run Remote Code 67 Execute a script directly from a URL. 68 69 **Basic Execution:** 70 ```bash 71 githrun run [https://github.com/user/repo/blob/main/script.py](https://github.com/user/repo/blob/main/script.py) 72 ``` 73 74 **Run Gists:** 75 ```bash 76 githrun run [https://gist.github.com/user/1234567890abcdef](https://gist.github.com/user/1234567890abcdef) 77 ``` 78 79 **Auto-Install Dependencies:** 80 If a remote script requires packages you do not have installed (e.g., pandas, requests), use this flag to run it in an isolated environment: 81 ```bash 82 githrun run [https://github.com/user/repo/blob/main/data.py](https://github.com/user/repo/blob/main/data.py) --auto-install 83 ``` 84 85 **Inspect Code:** 86 View the source code with syntax highlighting before running it (Safety Check): 87 ```bash 88 githrun run [https://github.com/user/repo/blob/main/script.py](https://github.com/user/repo/blob/main/script.py) --inspect 89 ``` 90 91 ### 2. Authentication (Private Repos & Rate Limits) 92 GitHub limits unauthenticated requests to 60 per hour. Login to increase this limit to 5,000 and access private repositories. 93 94 ```bash 95 githrun login ghp_YourPersonalAccessToken... 96 ``` 97 *The token is stored securely in `~/.githrun/config.json`.* 98 99 ### 3. Bookmarks 100 Stop copy-pasting long URLs. Save them once, run them anywhere. 101 102 **Add a Bookmark:** 103 ```bash 104 githrun bookmark add clean-db [https://github.com/user/repo/blob/main/utils/cleanup.py](https://github.com/user/repo/blob/main/utils/cleanup.py) 105 ``` 106 107 **Run a Bookmark:** 108 ```bash 109 githrun run clean-db 110 ``` 111 112 **List Bookmarks:** 113 ```bash 114 githrun bookmark list 115 ``` 116 117 ### 4. Install as a Tool 118 Turn a remote Python script into a command you can run from anywhere in your terminal. 119 120 ```bash 121 githrun install [https://github.com/user/repo/blob/main/my-tool.py](https://github.com/user/repo/blob/main/my-tool.py) --name mytool 122 ``` 123 124 * **Windows:** Creates a `.bat` file in `~/.githrun/bin`. 125 * **Linux/Mac:** Creates an executable shim in `~/.githrun/bin`. 126 * *Note: You must add `~/.githrun/bin` to your system PATH.* 127 128 ### 5. Find & Search 129 Search for files inside a remote repository without cloning it. 130 131 ```bash 132 # Search for files containing "config" 133 githrun find [https://github.com/user/repo](https://github.com/user/repo) "config" 134 ``` 135 *This command is interactive. You can select a result number to run it immediately.* 136 137 ### 6. Download Files & Folders 138 Download artifacts to your local machine. 139 140 **Download a single file:** 141 ```bash 142 githrun download [https://github.com/user/repo/blob/main/script.py](https://github.com/user/repo/blob/main/script.py) 143 ``` 144 145 **Download a specific folder (Recursive):** 146 ```bash 147 githrun download [https://github.com/user/repo/tree/main/src/utils](https://github.com/user/repo/tree/main/src/utils) --output ./local_utils 148 ``` 149 150 ### 7. Show Folder Contents 151 List files in a remote directory to understand the structure. 152 153 ```bash 154 githrun show [https://github.com/user/repo/tree/main/src](https://github.com/user/repo/tree/main/src) 155 ``` 156 157 --- 158 159 ## Python API Usage 160 161 You can use Githrun inside your own Python scripts. 162 163 ```python 164 import githrun 165 166 # 1. Search a repository 167 results = githrun.search_repository("[https://github.com/user/repo](https://github.com/user/repo)", "test") 168 for item in results: 169 print(item['path'], item['raw_url']) 170 171 # 2. Download a file 172 githrun.download_file("[https://github.com/user/repo/blob/main/script.py](https://github.com/user/repo/blob/main/script.py)", output_path="script.py") 173 174 # 3. Download a full folder 175 githrun.download_folder("[https://github.com/user/repo/tree/main/src](https://github.com/user/repo/tree/main/src)") 176 177 # 4. Execute code programmatically 178 exit_code = githrun.execute_remote_code("[https://github.com/user/repo/blob/main/script.py](https://github.com/user/repo/blob/main/script.py)", args=["--verbose"]) 179 ``` 180 181 --- 182 183 ## Configuration 184 185 Githrun stores configuration and cache files in your home directory: 186 187 * **Config:** `~/.githrun/config.json` (Tokens, Bookmarks) 188 * **Cache:** `~/.githrun/cache/` (API responses) 189 * **Binaries:** `~/.githrun/bin/` (Installed tools) 190 191 ## License 192 193 This project is licensed under the MIT License.