gh-attach

gh-attach

A GitHub CLI extension that uploads files to GitHub attachments.

Quick Start

gh extension install sudosubin/gh-attach
gh attach ./image.png -R owner/repo

Installation

Requires GitHub CLI. Browser-cookie mode also requires gh auth login. Session-token mode does not when the repository ID is available from GitHub's page.

gh extension install sudosubin/gh-attach
gh attach ./image.png -R owner/repo

Usage

$ gh attach ./image.png -R owner/repo
https://github.com/user-attachments/assets/550e8400-e29b-41d4-a716-446655440000

$ gh attach ./image.png ./report.pdf -R owner/repo
https://github.com/user-attachments/assets/550e8400-e29b-41d4-a716-446655440000
https://github.com/user-attachments/files/123/report.pdf

$ gh attach ./image.png ./report.pdf --markdown
![image.png](https://github.com/user-attachments/assets/550e8400-e29b-41d4-a716-446655440000)
[report.pdf](https://github.com/user-attachments/files/123/report.pdf)

$ gh attach ./image.png -R owner/repo --browser chrome --profile Default
https://github.com/user-attachments/assets/550e8400-e29b-41d4-a716-446655440000

$ GH_ATTACH_SESSION_TOKEN="$USER_SESSION" gh attach ./image.png -R owner/repo
https://github.com/user-attachments/assets/550e8400-e29b-41d4-a716-446655440000

$ gh attach ./image.png --json id,href,name
[
  {
    "href": "https://github.com/user-attachments/assets/550e8400-e29b-41d4-a716-446655440000",
    "id": 123,
    "name": "image.png"
  }
]

$ gh attach ./image.png --json href --jq '.[].href'
https://github.com/user-attachments/assets/550e8400-e29b-41d4-a716-446655440000

$ gh attach ./image.png --json href,name --template '{{range .}}{{.name}} -> {{.href}}{{"\n"}}{{end}}'
image.png -> https://github.com/user-attachments/assets/550e8400-e29b-41d4-a716-446655440000

Up to two files are uploaded concurrently, and per-file failures do not stop the remaining uploads. With --json, results are always returned as an array.

Options

• -R, --repo <[HOST/]OWNER/REPO>: Target repository. Auto detection is available from current repository.
• --browser <name>: Browser to read cookies from (auto|arc|atlas|brave|chrome|chromium|comet|dia|edge|firefox|floorp|helium|librewolf|opera|safari|vivaldi|waterfox|whale|zen).
• --profile <name>: Browser profile name. For Firefox-family multi-account containers, append :<container-name> or :id=<container-id> to pin a specific container (e.g. default:Work, default:id=2).
• --cookie-store-path <path>: Explicit cookie DB file path.
• --session-token <value>: Bare user_session cookie value. Prefer the GH_ATTACH_SESSION_TOKEN environment variable to keep this account credential out of command history and process arguments. Explicit browser options override the environment variable.
• --markdown: Output Markdown references.
• --json <fields>: Output JSON with selected fields.
• -q, --jq <expression>: Apply jq filter to JSON output (requires --json).
• -t, --template <go-template>: Format JSON output using Go template (requires --json).
• -v, --verbose: Print cookie source resolution logs to stderr.
• -h, --help: Show help.

Configuration

You can use a config file to register frequently used browser settings without having to pass them as command line arguments each time.

The config file is loaded from ${XDG_CONFIG_HOME:-~/.config}/gh/attach.yml.

Example

browsers:
  - browser: chrome
    profile: Default
  - browser: firefox
    profile: default-release
  - browser: safari

Schema

• browser: Browser to read cookies from (Required, one of auto|arc|atlas|brave|chrome|chromium|comet|dia|edge|firefox|floorp|helium|librewolf|opera|safari|vivaldi|waterfox|whale|zen)
• profile: Browser profile name/path (Optional, name or path)
• cookie_store_path: Explicit cookie DB file path (Optional)

Supported Browsers

• Chromium family (Arc, Atlas, Brave, Chrome, Chromium, Comet, Dia, Edge, Helium, Opera, Vivaldi, Whale)
• Firefox family (Firefox, Floorp, LibreWolf, Waterfox, Zen)
• Safari

How It Works

• It first resolves the target repository (owner/repo).
• With browser-cookie mode, it resolves the current GitHub login via the gh API and selects a browser session whose dotcom_user matches it.
• With --session-token or GH_ATTACH_SESSION_TOKEN, it uses the supplied bare user_session value without reading a browser.
• Using that session cookie, it requests GitHub upload policies (/upload/policies/assets) and uploads each file binary.
• It finalizes each user-attachments asset and prints the results as URLs or formatted output via --json.

Development

go test ./...
go build ./...

License

MIT, see LICENSE.