From 51caacc5cfd0f3f21a8f9a7cf191927a03ee87e5 Mon Sep 17 00:00:00 2001
From: Kerry Hatcher <kerry@kerryhatcher.com>
Date: Sun, 26 Jul 2026 13:57:51 -0400
Subject: [PATCH 1/3] feat: add Open Plugins v1.0.0 plugin manifest and command
 files
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add .plugin/plugin.json and commands/*.md so that CherryPi and other
conformant agent tools can discover and install gor as an Open Plugins
plugin. Each command file teaches the AI agent how to invoke gor for a
specific domain (PRs, issues, repos, CI, releases, search, etc.).

- .plugin/plugin.json — Plugin manifest (name, version, metadata)
- commands/auth.md — Authentication (login, logout, status, token)
- commands/repo.md — Repository management (CRUD, fork, clone, sync)
- commands/pr.md — Pull requests (list, view, create, merge, review)
- commands/issue.md — Issues (CRUD, lock, pin, transfer)
- commands/release.md — Releases (CRUD, upload, download)
- commands/search.md — Search (repos, issues, PRs, code, commits)
- commands/ci.md — Actions workflows, runs, and caches
- commands/codespace.md — Codespaces (list, create, stop, delete, SSH)
- commands/gist.md — Gists (CRUD, clone)
- commands/secrets.md — Secrets, variables, SSH keys, GPG keys
- commands/label.md — Labels (CRUD, clone)
- commands/other.md — Browse, API, config, orgs, projects, etc.

AGENTS.md: document plugin structure and installation instructions.
---
 .plugin/plugin.json   | 12 ++++++++
 AGENTS.md             | 43 ++++++++++++++++++++++++++++
 commands/auth.md      | 65 +++++++++++++++++++++++++++++++++++++++++++
 commands/ci.md        | 38 +++++++++++++++++++++++++
 commands/codespace.md | 23 +++++++++++++++
 commands/gist.md      | 26 +++++++++++++++++
 commands/issue.md     | 54 +++++++++++++++++++++++++++++++++++
 commands/label.md     | 18 ++++++++++++
 commands/other.md     | 50 +++++++++++++++++++++++++++++++++
 commands/pr.md        | 64 ++++++++++++++++++++++++++++++++++++++++++
 commands/release.md   | 44 +++++++++++++++++++++++++++++
 commands/repo.md      | 52 ++++++++++++++++++++++++++++++++++
 commands/search.md    | 43 ++++++++++++++++++++++++++++
 commands/secrets.md   | 39 ++++++++++++++++++++++++++
 14 files changed, 571 insertions(+)
 create mode 100644 .plugin/plugin.json
 create mode 100644 commands/auth.md
 create mode 100644 commands/ci.md
 create mode 100644 commands/codespace.md
 create mode 100644 commands/gist.md
 create mode 100644 commands/issue.md
 create mode 100644 commands/label.md
 create mode 100644 commands/other.md
 create mode 100644 commands/pr.md
 create mode 100644 commands/release.md
 create mode 100644 commands/repo.md
 create mode 100644 commands/search.md
 create mode 100644 commands/secrets.md

diff --git a/.plugin/plugin.json b/.plugin/plugin.json
new file mode 100644
index 0000000..6fbf689
--- /dev/null
+++ b/.plugin/plugin.json
@@ -0,0 +1,12 @@
+{
+  "name": "gor",
+  "version": "0.1.0",
+  "description": "GitHub CLI — manage PRs, issues, repos, CI, releases, search, codespaces, and more via the GitHub API",
+  "author": {
+    "name": "kerryhatcher"
+  },
+  "repository": "https://github.com/kerryhatcher/gor",
+  "homepage": "https://github.com/kerryhatcher/gor",
+  "license": "MIT OR Apache-2.0",
+  "keywords": ["github", "cli", "git", "pr", "issues", "ci", "devops"]
+}
diff --git a/AGENTS.md b/AGENTS.md
index e7ba3c1..a2c1b4e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -310,3 +310,46 @@ Always create a story file before implementing a new command or subcommand.
 - `docs/research/research-architecture.md` — Crate ecosystem and architecture patterns
 - `docs/research/research-docs.md` — Documentation best practices
 - `docs/research/research-deployment.md` — Distribution and release automation
+
+---
+
+## Open Plugins Integration
+
+gor bundles an [Open Plugins](https://open-plugins.com/) v1.0.0 plugin manifest
+and command files, so CherryPi and other conformant agent tools can discover
+gor as an installable plugin.
+
+### Plugin structure
+
+```
+.plugin/plugin.json       # Manifest: name, version, metadata
+commands/*.md             # Command files teaching agents how to use gor
+```
+
+Each `.md` file in `commands/` is loaded as a namespaced command available
+at `/gor:<name>` (e.g. `/gor:pr`, `/gor:repo`).
+
+### Installing the plugin
+
+Any conformant agent tool that scans Open Plugins directories will discover
+gor automatically when the repo root or a symlink is in the search path:
+
+```bash
+ln -s /path/to/gor ~/.local/share/cherrypi/plugins/gor
+```
+
+Or install via cargo and copy the plugin directory:
+
+```bash
+cargo install gor-cli
+cp -r .plugin commands ~/.local/share/cherrypi/plugins/gor/
+```
+
+### Key principles
+
+- The manifest (`name: "gor"`) namespaces all commands as `gor:<name>`.
+- Command files are documentation-first: they teach the AI how to invoke `gor`
+  with the right flags and `--json` output.
+- Changes to the CLI surface (new subcommands, changed flags) should be
+  reflected in the corresponding command file.
+- Adding a new command group? Create a matching `commands/<group>.md`.
diff --git a/commands/auth.md b/commands/auth.md
new file mode 100644
index 0000000..f0f95b6
--- /dev/null
+++ b/commands/auth.md
@@ -0,0 +1,65 @@
+---
+description: Authenticate with GitHub — login, logout, status, and token management
+---
+
+# GitHub Authentication via gor
+
+Use the `gor` CLI to authenticate with GitHub. Supports fine-grained PATs,
+classic PATs, and OAuth device flow.
+
+## Login
+
+Authenticate via OAuth device flow (opens a browser):
+
+```bash
+gor auth login
+```
+
+Or provide a token directly from a file or pipe:
+
+```bash
+gor auth login --with-token < ~/.gh-token
+```
+
+## Check status
+
+Verify you're authenticated and see which host and user:
+
+```bash
+gor auth status
+```
+
+## Logout
+
+Remove stored credentials:
+
+```bash
+gor auth logout
+```
+
+## View token
+
+Print the current token for debugging:
+
+```bash
+gor auth token
+```
+
+## Environment variables
+
+The following env vars are read automatically (no `auth login` needed):
+
+| Variable | Purpose |
+|---|---|
+| `GH_TOKEN` or `GITHUB_TOKEN` | Token for github.com |
+| `GH_ENTERPRISE_TOKEN` or `GITHUB_ENTERPRISE_TOKEN` | Token for GHES |
+| `GH_HOST` | Target hostname for GHES |
+
+## GitHub Enterprise Server
+
+Target a GHES instance on any command:
+
+```bash
+gor --hostname github.mycompany.com auth status
+gor --hostname github.mycompany.com repo view org/repo
+```
diff --git a/commands/ci.md b/commands/ci.md
new file mode 100644
index 0000000..2c617bf
--- /dev/null
+++ b/commands/ci.md
@@ -0,0 +1,38 @@
+---
+description: Manage GitHub Actions — workflows, runs, caches, and CI/CD operations
+---
+
+# CI/CD via gor
+
+Use the `gor` CLI to manage GitHub Actions workflows, runs, and caches.
+
+## Workflows
+
+```bash
+gor workflow list -R owner/repo
+gor workflow view .github/workflows/ci.yml -R owner/repo
+gor workflow run .github/workflows/ci.yml -R owner/repo
+gor workflow run .github/workflows/ci.yml -R owner/repo --ref main
+gor workflow enable .github/workflows/ci.yml -R owner/repo
+gor workflow disable .github/workflows/ci.yml -R owner/repo
+```
+
+## Workflow runs
+
+```bash
+gor run list -R owner/repo
+gor run list -R owner/repo --status failure --branch main
+gor run view 1234567890 -R owner/repo
+gor run watch 1234567890 -R owner/repo
+gor run cancel 1234567890 -R owner/repo
+gor run rerun 1234567890 -R owner/repo --failed
+gor run download 1234567890 -R owner/repo --dir ./artifacts
+```
+
+## Cache management
+
+```bash
+gor cache list -R owner/repo
+gor cache list -R owner/repo --json key,size_in_bytes,ref
+gor cache delete --key "node-modules-" -R owner/repo
+```
diff --git a/commands/codespace.md b/commands/codespace.md
new file mode 100644
index 0000000..a9ae07d
--- /dev/null
+++ b/commands/codespace.md
@@ -0,0 +1,23 @@
+---
+description: Manage GitHub Codespaces — list, create, stop, delete, and SSH
+---
+
+# Codespaces via gor
+
+Use the `gor` CLI to manage GitHub Codespaces.
+
+```bash
+gor codespace list
+gor codespace list --json name,repository,state,branch
+
+gor codespace create -R owner/repo
+gor codespace create -R owner/repo --branch feature-branch
+
+gor codespace ssh
+gor codespace ssh --codespace my-codespace-name
+
+gor codespace stop --codespace my-codespace-name
+
+gor codespace delete --codespace my-codespace-name
+gor codespace delete --all
+```
diff --git a/commands/gist.md b/commands/gist.md
new file mode 100644
index 0000000..8601549
--- /dev/null
+++ b/commands/gist.md
@@ -0,0 +1,26 @@
+---
+description: Manage Gists — list, view, create, edit, delete, and clone
+---
+
+# Gists via gor
+
+Use the `gor` CLI to manage GitHub gists.
+
+```bash
+gor gist list
+gor gist list --limit 10 --json id,description,files
+
+gor gist view GIST_ID
+gor gist view GIST_ID --json id,description,files,created_at
+
+gor gist create file.md
+gor gist create file1.rs file2.rs --description "Rust examples" --public
+
+gor gist edit GIST_ID --add new_file.rs
+gor gist edit GIST_ID --remove old_file.rs
+
+gor gist delete GIST_ID
+
+gor gist clone GIST_ID
+gor gist clone GIST_ID --target ./my-gist
+```
diff --git a/commands/issue.md b/commands/issue.md
new file mode 100644
index 0000000..e5f5c52
--- /dev/null
+++ b/commands/issue.md
@@ -0,0 +1,54 @@
+---
+description: Manage GitHub Issues — list, view, create, comment, close, and edit
+---
+
+# Issues via gor
+
+Use the `gor` CLI to manage GitHub issues.
+
+## List issues
+
+```bash
+gor issue list -R owner/repo
+gor issue list -R owner/repo --state closed --label bug
+gor issue list -R owner/repo --json number,title,labels,assignees
+```
+
+## View an issue
+
+```bash
+gor issue view 123 -R owner/repo
+gor issue view 123 -R owner/repo --json number,title,body,comments
+```
+
+## Create an issue
+
+```bash
+gor issue create -R owner/repo --title "Bug found" --body "Steps to reproduce..."
+gor issue create -R owner/repo --title "Feature request" --label enhancement
+```
+
+## Modify an issue
+
+```bash
+gor issue comment 123 -R owner/repo --body "I can reproduce this"
+gor issue close 123 -R owner/repo
+gor issue reopen 123 -R owner/repo
+gor issue edit 123 -R owner/repo --title "Updated title"
+```
+
+## Locking and pins
+
+```bash
+gor issue lock 123 -R owner/repo --reason spam
+gor issue unlock 123 -R owner/repo
+gor issue pin 123 -R owner/repo
+gor issue unpin 123 -R owner/repo
+```
+
+## Transfer and delete
+
+```bash
+gor issue transfer 123 -R owner/repo --target-repo target-owner/target-repo
+gor issue delete 123 -R owner/repo
+```
diff --git a/commands/label.md b/commands/label.md
new file mode 100644
index 0000000..d746f1e
--- /dev/null
+++ b/commands/label.md
@@ -0,0 +1,18 @@
+---
+description: Manage repository labels — list, create, edit, delete, and clone
+---
+
+# Labels via gor
+
+Use the `gor` CLI to manage repository labels.
+
+```bash
+gor label list -R owner/repo
+gor label list -R owner/repo --json name,color,description
+
+gor label create bug -R owner/repo --color d73a4a --description "Bug report"
+gor label edit bug -R owner/repo --name bug --color d73a4a
+gor label delete bug -R owner/repo
+
+gor label clone -R source/repo --target target/repo
+```
diff --git a/commands/other.md b/commands/other.md
new file mode 100644
index 0000000..2a7b22a
--- /dev/null
+++ b/commands/other.md
@@ -0,0 +1,50 @@
+---
+description: Additional commands — browse, API, config, orgs, projects, rulesets, extensions, attestations, copilot, classroom
+---
+
+# Additional Commands via gor
+
+```bash
+# Browse — open in browser
+gor browse                     # Open current repo
+gor browse --issue 123         # Open issue
+gor browse --pr 42             # Open PR
+gor browse --settings          # Open repo settings
+
+# API — arbitrary REST calls
+gor api /repos/owner/repo
+gor api /repos/owner/repo/issues --method POST --field title="Bug"
+gor api graphql -f query="query { viewer { login } }"
+
+# Config
+gor config list
+gor config set --host github.com git_protocol ssh
+
+# Organizations
+gor org list
+gor org view my-org
+
+# Projects (GitHub Projects v2)
+gor project list -R owner/repo
+gor project view PROJECT_NUMBER -R owner/repo
+gor project item-add PROJECT_NUMBER -R owner/repo --title "Task"
+
+# Rulesets
+gor ruleset list -R owner/repo
+gor ruleset view RULESET_ID -R owner/repo
+
+# Extensions
+gor extension list
+gor extension install owner/repo
+
+# Attestations
+gor attestation verify path/to/artifact
+
+# Copilot
+gor copilot status
+gor copilot usage --org my-org
+
+# Classroom
+gor classroom list
+gor classroom view ASSIGNMENT_ID
+```
diff --git a/commands/pr.md b/commands/pr.md
new file mode 100644
index 0000000..a77527b
--- /dev/null
+++ b/commands/pr.md
@@ -0,0 +1,64 @@
+---
+description: Manage GitHub Pull Requests — list, view, create, merge, review, checkout, and more
+---
+
+# Pull Requests via gor
+
+Use the `gor` CLI to manage pull requests. Always prefer `--json` for
+programmatic consumption.
+
+## List pull requests
+
+```bash
+gor pr list -R owner/repo
+gor pr list -R owner/repo --state closed --limit 20
+gor pr list -R owner/repo --json number,title,author,state
+```
+
+## View a pull request
+
+```bash
+gor pr view 42 -R owner/repo
+gor pr view 42 -R owner/repo --json number,title,body,mergeable
+```
+
+## Create a pull request
+
+```bash
+gor pr create -R owner/repo --title "Fix bug" --body "Description of fix"
+gor pr create -R owner/repo --title "WIP: feature" --draft
+```
+
+## Merge a pull request
+
+```bash
+gor pr merge 42 -R owner/repo
+gor pr merge 42 -R owner/repo --squash
+gor pr merge 42 -R owner/repo --merge --delete-branch
+```
+
+## Review a pull request
+
+```bash
+gor pr review 42 -R owner/repo --approve --body "Looks good!"
+gor pr review 42 -R owner/repo --request-changes --body "Needs tests"
+gor pr review 42 -R owner/repo --comment --body "What about edge cases?"
+```
+
+## Checkout locally
+
+```bash
+gor pr checkout 42 -R owner/repo
+```
+
+## Other operations
+
+```bash
+gor pr comment 42 -R owner/repo --body "Fixed in latest commit"
+gor pr close 42 -R owner/repo
+gor pr reopen 42 -R owner/repo
+gor pr ready 42 -R owner/repo
+gor pr diff 42 -R owner/repo
+gor pr checks 42 -R owner/repo
+gor pr edit 42 -R owner/repo --title "New title"
+```
diff --git a/commands/release.md b/commands/release.md
new file mode 100644
index 0000000..9fefb10
--- /dev/null
+++ b/commands/release.md
@@ -0,0 +1,44 @@
+---
+description: Manage GitHub Releases — list, view, create, edit, upload, and download assets
+---
+
+# Releases via gor
+
+Use the `gor` CLI to manage GitHub releases.
+
+## List releases
+
+```bash
+gor release list -R owner/repo
+gor release list -R owner/repo --limit 5 --json tag_name,created_at
+```
+
+## View a release
+
+```bash
+gor release view v1.0.0 -R owner/repo
+gor release view v1.0.0 -R owner/repo --json tag_name,body,assets
+```
+
+## Create a release
+
+```bash
+gor release create v1.0.0 -R owner/repo --title "v1.0.0" --body "Release notes..."
+gor release create v1.0.0 -R owner/repo --notes-file CHANGELOG.md --prerelease
+```
+
+## Upload and download assets
+
+```bash
+gor release upload v1.0.0 -R owner/repo ./binary.tar.gz
+gor release upload v1.0.0 -R owner/repo ./binary.tar.gz --label "Linux binary"
+
+gor release download v1.0.0 -R owner/repo --dir ./downloads
+```
+
+## Edit and delete
+
+```bash
+gor release edit v1.0.0 -R owner/repo --title "New title"
+gor release delete v1.0.0 -R owner/repo
+```
diff --git a/commands/repo.md b/commands/repo.md
new file mode 100644
index 0000000..29af13e
--- /dev/null
+++ b/commands/repo.md
@@ -0,0 +1,52 @@
+---
+description: Manage GitHub repositories — view, list, create, fork, clone, edit, and delete
+---
+
+# Repository Management via gor
+
+Use the `gor` CLI to manage GitHub repositories.
+
+## View a repository
+
+```bash
+gor repo view owner/repo
+gor repo view owner/repo --json name,description,stars,language
+```
+
+## List repositories
+
+```bash
+gor repo list
+gor repo list --org my-org
+gor repo list --type fork --sort updated
+```
+
+## Create a repository
+
+```bash
+gor repo create my-new-repo --description "A great project" --public
+```
+
+## Fork a repository
+
+```bash
+gor repo fork owner/repo
+gor repo fork owner/repo --org my-org
+```
+
+## Clone a repository
+
+```bash
+gor repo clone owner/repo
+gor repo clone owner/repo --target ./my-dir
+```
+
+## Other operations
+
+```bash
+gor repo edit owner/repo --description "New description"
+gor repo archive owner/repo
+gor repo rename owner/repo new-name
+gor repo delete owner/repo
+gor repo sync
+```
diff --git a/commands/search.md b/commands/search.md
new file mode 100644
index 0000000..1df006f
--- /dev/null
+++ b/commands/search.md
@@ -0,0 +1,43 @@
+---
+description: Search GitHub — repositories, issues, pull requests, code, and commits
+---
+
+# Search via gor
+
+Use the `gor` CLI to search GitHub across multiple domains.
+
+## Search repositories
+
+```bash
+gor search repos "rust cli"
+gor search repos "rust cli" --limit 10 --json name,stars,description
+```
+
+## Search issues and pull requests
+
+```bash
+gor search issues "bug in login" -R owner/repo
+gor search prs "state:open label:enhancement" -R owner/repo
+```
+
+## Search code
+
+```bash
+gor search code "fn main" --lang rust
+gor search code "TODO" -R owner/repo --path src/
+```
+
+## Search commits
+
+```bash
+gor search commits "fix clippy" -R owner/repo
+```
+
+## Useful qualifiers
+
+```bash
+gor search issues "label:bug is:open"
+gor search prs "author:username"
+gor search issues "created:>2024-01-01"
+gor search code "class Repository" --lang python
+```
diff --git a/commands/secrets.md b/commands/secrets.md
new file mode 100644
index 0000000..d552ab1
--- /dev/null
+++ b/commands/secrets.md
@@ -0,0 +1,39 @@
+---
+description: Manage secrets, variables, SSH keys, and GPG keys
+---
+
+# Secrets, Variables & Keys via gor
+
+Use the `gor` CLI to manage secrets, variables, SSH keys, and GPG keys.
+
+## Secrets
+
+```bash
+gor secret list -R owner/repo
+gor secret set MY_SECRET -R owner/repo
+gor secret delete MY_SECRET -R owner/repo
+```
+
+## Variables
+
+```bash
+gor variable list -R owner/repo
+gor variable set MY_VAR -R owner/repo
+gor variable delete MY_VAR -R owner/repo
+```
+
+## SSH keys
+
+```bash
+gor ssh-key list
+gor ssh-key add ~/.ssh/id_ed25519.pub --title "My laptop"
+gor ssh-key delete KEY_ID
+```
+
+## GPG keys
+
+```bash
+gor gpg-key list
+gor gpg-key add ~/.gnupg/pubkey.asc
+gor gpg-key delete KEY_ID
+```

From 17214a45338f2d55ddb6ec31bcfe6d7809bc7dd1 Mon Sep 17 00:00:00 2001
From: Kerry Hatcher <kerry@kerryhatcher.com>
Date: Sun, 26 Jul 2026 14:04:22 -0400
Subject: [PATCH 2/3] fix: address CodeRabbit review findings

- .plugin/plugin.json: bump version to 1.0.0
- AGENTS.md: annotate code fence with text language tag
- commands/auth.md: add setup-git subcommand docs, add --secure token
  flag, add token disclosure warning
- commands/gist.md: fix --desc flag (was --description), remove
  nonexistent --remove and clone subcommands
---
 .plugin/plugin.json |  2 +-
 AGENTS.md           |  2 +-
 commands/auth.md    | 20 ++++++++++++++++++--
 commands/gist.md    | 13 +++++--------
 4 files changed, 25 insertions(+), 12 deletions(-)

diff --git a/.plugin/plugin.json b/.plugin/plugin.json
index 6fbf689..a995517 100644
--- a/.plugin/plugin.json
+++ b/.plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "gor",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "GitHub CLI — manage PRs, issues, repos, CI, releases, search, codespaces, and more via the GitHub API",
   "author": {
     "name": "kerryhatcher"
diff --git a/AGENTS.md b/AGENTS.md
index a2c1b4e..1f54579 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -321,7 +321,7 @@ gor as an installable plugin.
 
 ### Plugin structure
 
-```
+```text
 .plugin/plugin.json       # Manifest: name, version, metadata
 commands/*.md             # Command files teaching agents how to use gor
 ```
diff --git a/commands/auth.md b/commands/auth.md
index f0f95b6..ff101e1 100644
--- a/commands/auth.md
+++ b/commands/auth.md
@@ -1,5 +1,5 @@
 ---
-description: Authenticate with GitHub — login, logout, status, and token management
+description: Authenticate with GitHub — login, logout, status, token, and git credential setup
 ---
 
 # GitHub Authentication via gor
@@ -39,10 +39,26 @@ gor auth logout
 
 ## View token
 
-Print the current token for debugging:
+Print the current token. Use `--secure` to mask the output (shows only first
+and last few characters):
 
 ```bash
 gor auth token
+gor auth token --secure
+```
+
+> **Warning:** Tokens grant full API access. Never expose them in logs,
+> terminal history, screenshots, or agent output. Use `--secure` whenever
+> possible to reduce accidental disclosure.
+
+## Configure git credential helper
+
+Set up git to use `gor` as a credential helper (so git commands authenticate
+via your stored token):
+
+```bash
+gor auth setup-git
+gor auth setup-git --hostname github.mycompany.com
 ```
 
 ## Environment variables
diff --git a/commands/gist.md b/commands/gist.md
index 8601549..9dad216 100644
--- a/commands/gist.md
+++ b/commands/gist.md
@@ -1,5 +1,5 @@
 ---
-description: Manage Gists — list, view, create, edit, delete, and clone
+description: Manage Gists — list, view, create, edit, and delete
 ---
 
 # Gists via gor
@@ -13,14 +13,11 @@ gor gist list --limit 10 --json id,description,files
 gor gist view GIST_ID
 gor gist view GIST_ID --json id,description,files,created_at
 
-gor gist create file.md
-gor gist create file1.rs file2.rs --description "Rust examples" --public
+gor gist create file.md --desc "A useful snippet"
+gor gist create file1.rs file2.rs --desc "Rust examples" --public
 
-gor gist edit GIST_ID --add new_file.rs
-gor gist edit GIST_ID --remove old_file.rs
+gor gist edit GIST_ID --desc "Updated description"
+gor gist edit GIST_ID --add new_file.rs --filename old_name:new_name
 
 gor gist delete GIST_ID
-
-gor gist clone GIST_ID
-gor gist clone GIST_ID --target ./my-gist
 ```

From 1204a612d425627a646c3bbc91324785a1899786 Mon Sep 17 00:00:00 2001
From: Kerry Hatcher <kerry@kerryhatcher.com>
Date: Sun, 26 Jul 2026 14:10:49 -0400
Subject: [PATCH 3/3] fix: address Copilot CLI flag findings across command
 files

Align all commands/*.md examples with the actual CLI surface on main:

- commands/codespace.md: ssh/stop/delete use positional name arg, not
  --codespace; delete has --yes not --all
- commands/repo.md: create uses --private (not --public); clone uses
  --directory (not --target); edit uses -R/--repo not positional;
  remove nonexistent archive/rename subcommands
- commands/ci.md: run list has no --status; run rerun uses --failed-jobs
  not --failed; cache delete uses --key (exact match) or --all
- commands/release.md: upload uses --name not --label
- commands/label.md: clone takes positional source + -R/--repo target
- commands/secrets.md: secret/variable are org/env-scoped (no -R);
  gpg-key add uses --file not positional path
- commands/issue.md: transfer takes positional destination repo;
  remove nonexistent issue delete
- commands/search.md: code uses --language (not --lang); no --path/-R;
  no search prs subcommand; commits uses --repo not -R
---
 commands/ci.md        | 11 ++++++++---
 commands/codespace.md | 17 ++++++++++-------
 commands/issue.md     |  5 ++---
 commands/label.md     |  3 ++-
 commands/release.md   |  2 +-
 commands/repo.md      | 18 ++++++++++++------
 commands/search.md    | 17 ++++++++---------
 commands/secrets.md   | 18 +++++++++---------
 8 files changed, 52 insertions(+), 39 deletions(-)

diff --git a/commands/ci.md b/commands/ci.md
index 2c617bf..b104244 100644
--- a/commands/ci.md
+++ b/commands/ci.md
@@ -21,11 +21,11 @@ gor workflow disable .github/workflows/ci.yml -R owner/repo
 
 ```bash
 gor run list -R owner/repo
-gor run list -R owner/repo --status failure --branch main
+gor run list -R owner/repo --branch main --workflow ci.yml
 gor run view 1234567890 -R owner/repo
 gor run watch 1234567890 -R owner/repo
 gor run cancel 1234567890 -R owner/repo
-gor run rerun 1234567890 -R owner/repo --failed
+gor run rerun 1234567890 -R owner/repo --failed-jobs
 gor run download 1234567890 -R owner/repo --dir ./artifacts
 ```
 
@@ -34,5 +34,10 @@ gor run download 1234567890 -R owner/repo --dir ./artifacts
 ```bash
 gor cache list -R owner/repo
 gor cache list -R owner/repo --json key,size_in_bytes,ref
-gor cache delete --key "node-modules-" -R owner/repo
+
+# Delete by exact key
+gor cache delete --key "node-linux-pnpm-" -R owner/repo
+
+# Delete all caches
+gor cache delete --all -R owner/repo
 ```
diff --git a/commands/codespace.md b/commands/codespace.md
index a9ae07d..991f0c8 100644
--- a/commands/codespace.md
+++ b/commands/codespace.md
@@ -7,17 +7,20 @@ description: Manage GitHub Codespaces — list, create, stop, delete, and SSH
 Use the `gor` CLI to manage GitHub Codespaces.
 
 ```bash
+# List
 gor codespace list
 gor codespace list --json name,repository,state,branch
 
-gor codespace create -R owner/repo
-gor codespace create -R owner/repo --branch feature-branch
+# Create
+gor codespace create owner/repo
+gor codespace create owner/repo --branch feature-branch
 
-gor codespace ssh
-gor codespace ssh --codespace my-codespace-name
+# SSH (positional: codespace name)
+gor codespace ssh my-codespace-name
 
-gor codespace stop --codespace my-codespace-name
+# Stop (positional: codespace name)
+gor codespace stop my-codespace-name
 
-gor codespace delete --codespace my-codespace-name
-gor codespace delete --all
+# Delete (positional: codespace name, use --yes to skip prompt)
+gor codespace delete my-codespace-name --yes
 ```
diff --git a/commands/issue.md b/commands/issue.md
index e5f5c52..3433982 100644
--- a/commands/issue.md
+++ b/commands/issue.md
@@ -46,9 +46,8 @@ gor issue pin 123 -R owner/repo
 gor issue unpin 123 -R owner/repo
 ```
 
-## Transfer and delete
+## Transfer to another repository
 
 ```bash
-gor issue transfer 123 -R owner/repo --target-repo target-owner/target-repo
-gor issue delete 123 -R owner/repo
+gor issue transfer 123 -R owner/repo target-owner/target-repo
 ```
diff --git a/commands/label.md b/commands/label.md
index d746f1e..95f8ea5 100644
--- a/commands/label.md
+++ b/commands/label.md
@@ -14,5 +14,6 @@ gor label create bug -R owner/repo --color d73a4a --description "Bug report"
 gor label edit bug -R owner/repo --name bug --color d73a4a
 gor label delete bug -R owner/repo
 
-gor label clone -R source/repo --target target/repo
+# Clone labels: source is positional, target via -R
+gor label clone source-owner/source-repo -R target-owner/target-repo
 ```
diff --git a/commands/release.md b/commands/release.md
index 9fefb10..380b9c3 100644
--- a/commands/release.md
+++ b/commands/release.md
@@ -31,7 +31,7 @@ gor release create v1.0.0 -R owner/repo --notes-file CHANGELOG.md --prerelease
 
 ```bash
 gor release upload v1.0.0 -R owner/repo ./binary.tar.gz
-gor release upload v1.0.0 -R owner/repo ./binary.tar.gz --label "Linux binary"
+gor release upload v1.0.0 -R owner/repo ./binary.tar.gz --name "linux-amd64.tar.gz"
 
 gor release download v1.0.0 -R owner/repo --dir ./downloads
 ```
diff --git a/commands/repo.md b/commands/repo.md
index 29af13e..e17837c 100644
--- a/commands/repo.md
+++ b/commands/repo.md
@@ -1,5 +1,5 @@
 ---
-description: Manage GitHub repositories — view, list, create, fork, clone, edit, and delete
+description: Manage GitHub repositories — view, list, create, fork, clone, and edit
 ---
 
 # Repository Management via gor
@@ -23,8 +23,11 @@ gor repo list --type fork --sort updated
 
 ## Create a repository
 
+Default visibility is public; use `--private` for private repos:
+
 ```bash
-gor repo create my-new-repo --description "A great project" --public
+gor repo create my-new-repo --description "A great project"
+gor repo create private-repo --description "Internal tool" --private
 ```
 
 ## Fork a repository
@@ -38,15 +41,18 @@ gor repo fork owner/repo --org my-org
 
 ```bash
 gor repo clone owner/repo
-gor repo clone owner/repo --target ./my-dir
+gor repo clone owner/repo --directory ./my-dir
 ```
 
 ## Other operations
 
 ```bash
-gor repo edit owner/repo --description "New description"
-gor repo archive owner/repo
-gor repo rename owner/repo new-name
+# Edit repo settings (use -R for target)
+gor repo edit -R owner/repo --description "New description" --visibility private
+
+# Delete
 gor repo delete owner/repo
+
+# Sync a fork with its upstream
 gor repo sync
 ```
diff --git a/commands/search.md b/commands/search.md
index 1df006f..7a665a9 100644
--- a/commands/search.md
+++ b/commands/search.md
@@ -1,10 +1,10 @@
 ---
-description: Search GitHub — repositories, issues, pull requests, code, and commits
+description: Search GitHub — repositories, issues, code, and commits
 ---
 
 # Search via gor
 
-Use the `gor` CLI to search GitHub across multiple domains.
+Use the `gor` CLI to search GitHub.
 
 ## Search repositories
 
@@ -13,31 +13,30 @@ gor search repos "rust cli"
 gor search repos "rust cli" --limit 10 --json name,stars,description
 ```
 
-## Search issues and pull requests
+## Search issues
 
 ```bash
 gor search issues "bug in login" -R owner/repo
-gor search prs "state:open label:enhancement" -R owner/repo
+gor search issues "state:open label:bug" --limit 20
 ```
 
 ## Search code
 
 ```bash
-gor search code "fn main" --lang rust
-gor search code "TODO" -R owner/repo --path src/
+gor search code "fn main" --language rust
+gor search code "TODO" --repo owner/repo
 ```
 
 ## Search commits
 
 ```bash
-gor search commits "fix clippy" -R owner/repo
+gor search commits "fix clippy" --repo owner/repo
 ```
 
 ## Useful qualifiers
 
 ```bash
 gor search issues "label:bug is:open"
-gor search prs "author:username"
 gor search issues "created:>2024-01-01"
-gor search code "class Repository" --lang python
+gor search code "class Repository" --language python
 ```
diff --git a/commands/secrets.md b/commands/secrets.md
index d552ab1..5e74f75 100644
--- a/commands/secrets.md
+++ b/commands/secrets.md
@@ -6,20 +6,20 @@ description: Manage secrets, variables, SSH keys, and GPG keys
 
 Use the `gor` CLI to manage secrets, variables, SSH keys, and GPG keys.
 
-## Secrets
+## Secrets (org- or environment-scoped)
 
 ```bash
-gor secret list -R owner/repo
-gor secret set MY_SECRET -R owner/repo
-gor secret delete MY_SECRET -R owner/repo
+gor secret list --org my-org
+gor secret set MY_SECRET --body "value-here" --org my-org
+gor secret delete MY_SECRET --org my-org
 ```
 
-## Variables
+## Variables (org- or environment-scoped)
 
 ```bash
-gor variable list -R owner/repo
-gor variable set MY_VAR -R owner/repo
-gor variable delete MY_VAR -R owner/repo
+gor variable list --org my-org
+gor variable set MY_VAR --body "value-here" --org my-org
+gor variable delete MY_VAR --org my-org
 ```
 
 ## SSH keys
@@ -34,6 +34,6 @@ gor ssh-key delete KEY_ID
 
 ```bash
 gor gpg-key list
-gor gpg-key add ~/.gnupg/pubkey.asc
+gor gpg-key add --file ~/.gnupg/pubkey.asc
 gor gpg-key delete KEY_ID
 ```