GH-API(1) GitHub CLI manual GH-API(1)

gh-api - ارسال درخواست‌های معتبر به رابط برنامه‌نویسی گیت‌هاب (API)

gh api <endpoint> [flags]

یک درخواست HTTP معتبر (احراز هویت شده) به رابط برنامه‌نویسی گیت‌هاب (GitHub API) ارسال کرده و پاسخ را چاپ می‌کند.

آرگومان endpoint باید یا مسیر یک نقطه پایانی در نسخه ۳ رابط برنامه‌نویسی گیت‌هاب (GitHub API v3) باشد، یا graphql برای دسترسی به نسخه ۴ رابط برنامه‌نویسی گیت‌هاب (GitHub API v4).

مقادیر جایگزین {owner}، {repo} و {branch} در آرگومان endpoint با مقادیر مربوط به مخزن دایرکتوری جاری یا مخزن مشخص‌شده در متغیر محیطی GH_REPO جایگزین خواهند شد. توجه داشته باشید که در برخی پوسته‌ها مانند PowerShell، ممکن است نیاز باشد هر مقداری که حاوی {...} است را درون نقل‌قول قرار دهید تا از اعمال معنای خاص آکولادها توسط پوسته جلوگیری شود.

گزینه -p/--preview امکان فعال‌سازی پیش‌نمایش‌ها (previews) را فراهم می‌کند که همان نقاط پایانی یا رفتارهای آزمایشی و دارای فلگ ویژگی (feature-flagged) هستند. رابط برنامه‌نویسی انتظار دارد فعال‌سازی از طریق هدر Accept با قالب application/vnd.github.<preview-name>-preview+json انجام گیرد و این دستور آن را از طریق --preview <preview-name> تسهیل می‌کند. برای ارسال یک درخواست جهت پیش‌نمایش‌های corsair و scarlet witch، می‌توانید از -p corsair,scarlet-witch یا --preview corsair --preview scarlet-witch استفاده کنید.

متد پیش‌فرض درخواست HTTP در حالت عادی GET است و در صورتی که هر پارامتری اضافه شده باشد، به POST تغییر می‌کند. با استفاده از --method می‌توانید متد را بازنویسی کنید.

یک یا چند مقدار -f/--raw-field را در قالب key=value برای افزودن پارامترهای رشته‌ای ایستا به بار کاری (payload) درخواست ارسال کنید. برای افزودن مقادیر غیررشته‌ای یا مقادیری که با نگه‌دارنده مکان تعیین می‌شوند، -F/--field را در ادامه ببینید. توجه داشته باشید که افزودن پارامترهای درخواست، متد درخواست را به طور خودکار به POST تغییر می‌دهد. برای ارسال پارامترها در قالب رشته پرس‌وجو (query string) در متد GET، از --method GET استفاده کنید.

گزینه -F/--field بر اساس قالب مقدار، تبدیل نوع جادویی انجام می‌دهد:

  • مقادیر دقیق (literal) true، false، null و اعداد صحیح به انواع مناسب در JSON تبدیل می‌شوند؛
  • مقادیر جایگزین {owner}، {repo} و {branch} با مقادیر مربوط به مخزن دایرکتوری جاری مقداردهی می‌شوند؛
  • اگر مقدار با @ آغاز شود، باقی‌مانده مقدار به عنوان نام فایلی که مقدار باید از آن خوانده شود تفسیر می‌گردد. برای خواندن از ورودی استاندارد (stdin)، مقدار - را ارسال کنید.

برای درخواست‌های GraphQL، تمامی فیلدها به‌جز query و operationName به عنوان متغیرهای GraphQL تفسیر می‌شوند.

برای ارسال پارامترهای تودرتو در بار کاری درخواست، هنگام تعریف فیلدها از ساختار دستوری key[subkey]=value استفاده کنید. برای ارسال مقادیر تودرتو به صورت آرایه، چندین فیلد را با ساختار دستوری key[]=value1، key[]=value2 تعریف نمایید. برای ارسال یک آرایه خالی، از key[] بدون مقدار استفاده کنید.

برای ارسال JSON از پیش ساخته‌شده یا بار کاری در قالب‌های دیگر، بدنه درخواست می‌تواند از فایل مشخص‌شده توسط --input خوانده شود. از - برای خواندن از ورودی استاندارد استفاده کنید. هنگام ارسال بدنه درخواست از این روش، هر پارامتری که از طریق فلگ‌های فیلد تعیین شود، به رشته پرس‌وجو (query string) نشانی نقطه پایانی افزوده می‌شود.

در حالت --paginate، تمامی صفحات نتایج تا زمانی که صفحه دیگری از نتایج وجود نداشته باشد، به صورت متوالی درخواست می‌شوند. برای درخواست‌های GraphQL، این کار مستلزم آن است که پرس‌وجوی اصلی یک متغیر $endCursor: String را بپذیرد و مجموعه فیلدهای pageInfo{ hasNextPage, endCursor } را از یک مجموعه واکشی کند. هر صفحه یک آرایه یا شیء JSON جداگانه است. برای بسته‌بندی تمام صفحات آرایه‌ها یا اشیاء JSON در یک آرایه JSON بیرونی، --slurp را ارسال کنید.

اجازه به چاپ توالی‌های گریز (escape sequences) ترمینال
کش کردن پاسخ، برای مثال "3600s" ،"60m" ،"1h"
افزودن یک پارامتر دارای نوع در قالب key=value (برای خواندن مقدار از فایل یا stdin از "@" یا "@-" استفاده کنید)
افزودن یک هدر درخواست HTTP در قالب key:value
نام میزبان گیت‌هاب برای درخواست (پیش‌فرض "github.com")
گنجاندن خط وضعیت و هدرهای پاسخ HTTP در خروجی
فایلی که به عنوان بدنه درخواست HTTP استفاده می‌شود (از "-" برای خواندن از ورودی استاندارد استفاده کنید)
پرس‌وجو برای انتخاب مقادیر از پاسخ با استفاده از نحو jq
متد HTTP برای درخواست
ارسال درخواست‌های HTTP بیشتر برای واکشی تمامی صفحات نتایج
فعال‌سازی پیش‌نمایش‌های رابط برنامه‌نویسی گیت‌هاب (نام‌ها باید بدون '-preview' باشند)
افزودن یک پارامتر رشته‌ای در قالب key=value
عدم چاپ بدنه پاسخ
استفاده به همراه "--paginate" برای بازگرداندن آرایه‌ای از تمام صفحات آرایه‌ها یا اشیاء JSON
قالب‌بندی خروجی JSON با استفاده از الگوی Go؛ دستور "gh help formatting" را ببینید
گنجاندن درخواست و پاسخ کامل HTTP در خروجی

0: اجرای موفقیت‌آمیز

1: خطا

2: لغو دستور

4: احراز هویت لازم است

نکته: دستورات خاص ممکن است کدهای خروج دیگری نیز داشته باشند. برای اطلاعات بیشتر به راهنمای دستور مربوطه مراجعه کنید.

# فهرست کردن انتشارها (releases) در مخزن جاری
$ gh api repos/{owner}/{repo}/releases
# ارسال یک دیدگاه روی گزارش مشکل (issue)
$ gh api repos/{owner}/{repo}/issues/123/comments -f body='Hi from CLI'
# ارسال پارامتر تودرتو خوانده‌شده از یک فایل
$ gh api gists -F 'files[myfile.txt][content]=@myfile.txt'
# افزودن پارامترها به یک درخواست GET
$ gh api -X GET search/issues -f q='repo:cli/cli is:open remote'
# استفاده از یک فایل JSON به عنوان بدنه درخواست
$ gh api repos/{owner}/{repo}/rulesets --input file.json
# تنظیم یک هدر سفارشی HTTP
$ gh api -H 'Accept: application/vnd.github.v3.raw+json' ...
# فعال‌سازی پیش‌نمایش‌های رابط برنامه‌نویسی گیت‌هاب
$ gh api --preview baptiste,nebula ...
# چاپ تنها فیلدهای مشخصی از پاسخ
$ gh api repos/{owner}/{repo}/issues --jq '.[].title'
# استفاده از یک الگو برای قالب‌بندی خروجی
$ gh api repos/{owner}/{repo}/issues --template \
  '{{range .}}{{.title}} ({{.labels | pluck "name" | join ", " | color "yellow"}}){{"\n"}}{{end}}'
# به‌روزرسانی مقادیر مجاز ویژگی سفارشی "environment" در یک آرایه عمیقاً تودرتو
$ gh api -X PATCH /orgs/{org}/properties/schema \
   -F 'properties[][property_name]=environment' \
   -F 'properties[][default_value]=production' \
   -F 'properties[][allowed_values][]=staging' \
   -F 'properties[][allowed_values][]=production'
# فهرست کردن انتشارها با GraphQL
$ gh api graphql -F owner='{owner}' -F name='{repo}' -f query='
  query($name: String!, $owner: String!) {
    repository(owner: $owner, name: $name) {
      releases(last: 3) {
        nodes { tagName }
      }
    }
  }
'
# فهرست کردن تمام مخازن یک کاربر
$ gh api graphql --paginate -f query='
  query($endCursor: String) {
    viewer {
      repositories(first: 100, after: $endCursor) {
        nodes { nameWithOwner }
        pageInfo {
          hasNextPage
          endCursor
        }
      }
    }
  }
'
# محاسبه درصد انشعاب‌ها (forks) برای کاربر فعلی
$ gh api graphql --paginate --slurp -f query='
  query($endCursor: String) {
    viewer {
      repositories(first: 100, after: $endCursor) {
        nodes { isFork }
        pageInfo {
          hasNextPage
          endCursor
        }
      }
    }
  }
' | jq 'def count(e): reduce e as $_ (0;.+1);
[.[].data.viewer.repositories.nodes[]] as $r | count(select($r[].isFork))/count($r[])'

gh(1)

Sep 2026