gh-remotely

README

gh-remotely

Read, search, and safely change a GitHub repository without cloning it. Remote API calls use github.com/cli/go-gh/v2/pkg/api and the existing gh authentication context.

[!WARNING] This project was created by OpenCode using GPT-5.6 Terra. It has not received an independent security or production-readiness review, and no guarantee is made that it will work as intended. Review the code and test it in a non-critical repository before relying on it.

Create And Install

Create the precompiled Go extension scaffold with the GitHub CLI:

gh extension create --precompiled=go remotely
cd remotely

Replace the generated main.go and go.mod with the files in this repository, then build and install locally:

go build -o gh-remotely .
gh extension install .

With Mise, use these development tasks:

mise run build    # build gh-remotely in the repository root
mise run replace  # rebuild and replace the installed gh extension

For publishing, attach platform binaries named according to the precompiled extension convention, such as gh-remotely-darwin-arm64, to a GitHub release.

Usage

Set a default repository once; --repo remains available to override it:

gh remotely use OWNER/REPO
gh remotely use                 # print the active default
gh remotely use --clear         # remove it

Browse a repository, inspect a file, then edit it without cloning:

gh remotely ls docs --json --no-pager
gh remotely cat docs/guide.md --ref main --no-pager
gh remotely cat docs/guide.md --external glow
gh remotely tree wiki --depth 3 --json
gh remotely rg "wikilink" wiki --json

ls, cat, tree, and rg accept --ref for branches, tags, or commits. rg builds and removes a bounded temporary Zoekt index for each search. --repo overrides the configured default repository.

cat --external COMMAND pipes file content to an executable on PATH, which is useful for Markdown renderers such as glow. It cannot be combined with --json.

External defaults can be set in $XDG_CONFIG_HOME/gh-remotely/config.toml:

pager = "glow"
editor = "hx"

An explicit --external, --editor, or --no-pager flag overrides the configuration. Other useful external providers can be configured as long as they read file content from standard input or are valid editor executables.

Search results are cached for five minutes under the operating system cache directory. Pass --no-cache to force a fresh index, or set --cache-ttl:

gh remotely rg cv wiki --cache-ttl 30m

Writes default to an isolated branch, persist it as the active branch, and can be turned into a pull request. Use --direct only when an immediate commit is intended.

gh remotely edit wiki/profile/working-style.md --branch agent/update-context
gh remotely put ./working-style.md wiki/profile/working-style.md
gh remotely diff wiki/profile/working-style.md --source ./working-style.md
gh remotely pr --title "docs: update working style"

Git does not store empty directories. mkdir creates a directory by adding a .gitkeep marker; rmdir deletes every file below a directory. Start with its dry run, especially for directories with many files:

gh remotely touch --repo OWNER/REPO --target docs/draft.md
gh remotely mkdir --repo OWNER/REPO --target docs/drafts
gh remotely rm --repo OWNER/REPO --target docs/obsolete.md
gh remotely rm -r --repo OWNER/REPO --target docs/drafts --dry-run
gh remotely rm -r --repo OWNER/REPO --target docs/drafts

touch is a no-op when the file exists because Git does not track timestamps. rm -r uses one GitHub commit per deleted file, so partial completion is possible if a later deletion fails.

edit accepts any editor executable on PATH; it refuses to write unless the editor changed the file. diff exits successfully when files differ, matching the normal diff workflow. Generate basic shell completion with gh remotely completion fish, bash, or zsh.