Githrun Documentation

VS Code: Command Palette

You can access all Githrun features via the Command Palette (Ctrl+Shift+P).

• Githrun: Run from URL… – Opens an input box where you can paste any GitHub URL to run it immediately.
• Githrun: Run Selected Text – Executes the currently highlighted URL.
• Githrun: Install Githrun CLI – Runs the pip install command for you.

VS Code: Context Menus

If you don’t want to use the CodeLens or Command Palette, simply highlight a URL in your editor:

1. Select the URL text (e.g., https://gist.github.com/...).
2. Right-click the selection.
3. Choose Githrun: Run Selected Text.

Extension Settings

You can configure the extension behavior in VS Code Settings:

• githrun.autoInstallDeps (Boolean): If enabled, the extension appends --auto-install to every command, automatically handling missing Python dependencies for you.

CLI: Remote Execution

The run command is the core of the Githrun CLI. It fetches the raw content of a file and executes it locally.

Supported Sources

• GitHub Repositories: Standard blob URLs.
• GitHub Gists: Direct Gist URLs.

Safety First: Inspection

Before running code from the internet, you should verify it. Use the --inspect flag to print the syntax-highlighted code to your terminal without executing it.

githrun run https://github.com/user/repo/blob/main/script.py --inspect

CLI: Tool Installation

Found a useful script? Turn it into a permanent command-line tool on your system using install.

githrun install https://github.com/user/repo/blob/main/utils.py --name my-util

How it works:

1. Downloads the script to ~/.githrun/bin/my-util.py.
2. Creates an executable shim (.bat on Windows, shell script on Linux/Mac).
3. You add ~/.githrun/bin to your system PATH.
4. You can now type my-util in any terminal window.

CLI: Search & Find

Don’t clone a 1GB repo just to find one file. The find command recursively searches the remote repository tree.

githrun find https://github.com/notamitgamer/adpkg "test"

Interactive Mode: By default, this command displays a list of matches. You can type the number of a result to immediately execute that script.

CLI: Downloading

Githrun can download individual files or recursively download entire directories.

Single File

githrun download https://github.com/user/repo/blob/main/script.py

Recursive Folder

If you provide a tree URL, Githrun detects it and downloads the full folder structure.

githrun download https://github.com/user/repo/tree/main/src --output ./local_src

CLI: Bookmarks

Bookmarks allow you to alias long, complex GitHub URLs to short, memorable names.

Add a Bookmark

githrun bookmark add clean-db https://github.com/user/repo/blob/main/scripts/maintenance/clean_database.py

Run a Bookmark

githrun run clean-db

Authentication

By default, GitHub allows 60 unauthenticated API requests per hour. To increase this limit to 5,000/hr and to access Private Repositories, you need to login.

githrun login ghp_YourPersonalAccessToken...

The token is stored locally in ~/.githrun/config.json and is never sent anywhere except GitHub API endpoints.

Python Library API

Githrun exposes its core logic as a Python library, allowing you to build your own tools on top of it.

# main.py
import githrun

# 1. Search a repository for config files
results = githrun.search_repository("https://github.com/user/repo", "config")

# 2. Execute a remote setup script immediately
exit_code = githrun.execute_remote_code("https://github.com/user/repo/blob/main/setup.py")

Configuration

Githrun stores all its data in your home directory under .githrun.

• config.json: Stores your API key and bookmarks.
• cache/: Stores JSON responses from GitHub API (expiring).
• bin/: Stores scripts installed via githrun install.

Contributing

We welcome contributions from the community! Whether it’s a bug fix, new feature, or documentation improvement.

Contact the Developer: If you have questions or want to discuss a major feature, feel free to email:

[email protected]