參考資料
互動原則
gh 在非 TTY 環境中已能正確運作：它會略過分頁器、移除 ANSI 色彩，並在有幫助的訊息中快速報錯，而非進行提示（例如 must provide --title and --body when not running interactively）。您不需要防禦性地設定 GH_PAGER 或傳遞 --no-pager（此旗標不存在）。
解析 JSON
gh 的人類可讀輸出為欄位格式。如果您需要結構化資料：
- 加上
--json field1,field2,...以取得結構化輸出。 - 執行命令時加上
--json且不提供欄位列表，即可列印所有可用的欄位，然後選取您需要的部分。 - 使用
--jq '<expr>'進行過濾，而無需透過獨立的jq進行管線處理。 - 當您需要格式化的文字輸出時，可使用
--template '<go-template>'（與--json一起使用）。請注意，--template/-T會與少數命令中的 body-template 旗標衝突（例如gh pr create -T、gh issue create -T）；在假設您使用的是哪個旗標之前，請務必先查看--help。
分頁與靜默截斷
列表命令會限制結果數量。
gh issue list、gh pr list、gh search ...：傳遞-L N（--limit N）。預設值通常為 30。gh issue list/gh pr list不會透過--json公開彙總總數，例如totalCount。如果您需要真實的總數，請使用gh api graphql查詢totalCount；否則，請將-L視為目前呼叫的上限。- 對於原始 API 呼叫，請使用
gh api --paginate <path>。結合--jq和（可選的）--slurp來組合一個陣列。
儲存庫定位
gh 會從當前工作目錄的 git 遠端推斷儲存庫。
傳遞 --repo OWNER/REPO（-R）以覆蓋已解析的當前工作目錄儲存庫。
搜尋 vs 列表
gh search issues|prs|code|repos|commits|users使用 GitHub 的搜尋索引，並接受完整的搜尋語法（is:open、author:、label:、repo:owner/name、in:title、...）。將整個查詢作為一個引號字串傳遞，就像您對--search所做的那樣：gh search issues "is:open author:foo repo:cli/cli"。對於任何跨儲存庫或按作者/標籤過濾的內容，都應優先使用它。gh issue list --search "..."和gh pr list --search "..."接受相同的語法，但僅限於一個儲存庫的範圍。
對於 --json 未公開的內容，請使用 gh api 作為備用
有時有用的資料並不在類型命令中。例如：
- PR 上的審閱執行緒評論：
gh api repos/{owner}/{repo}/pulls/{n}/comments（gh pr view上的--comments旗標僅顯示議題層級的評論）。 - 任意 GraphQL：
gh api graphql -f query='...' -F var=value。 - REST 快捷方式：
gh api repos/{owner}/{repo}/...- 請注意，當從具有已偵測遠端的儲存庫執行時，{owner}/{repo}佔位符會為您填入；如果您想要確定性，請逐字傳遞它們。
驗證
gh auth status會列印作用中的主機、使用者，以及正在使用哪個環境變數（如果有的話）。- 支援
gh auth status --json。
其他注意事項
gh pr checkout <n>會切換分支。如果您只需要讀取，請使用gh pr diff <n>或gh pr view <n>。- 支援
NO_COLOR、CLICOLOR_FORCE和GH_FORCE_TTY。如果您希望在代理程式環境中取得 TTY 風格的輸出（色彩、表格、分頁器、互動性），請設定GH_FORCE_TTY=1；除非必要，否則保留未設定狀態。