.nh
.TH "GH-API" "1" "Sep 2026" "" "GitHub CLI manual"

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

.SH "خلاصه دستور (SYNOPSIS)"
\fBgh api <endpoint> [flags]\fR

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

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

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

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

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

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

.PP
گزینه
.B \-F/\-\-field
بر اساس قالب مقدار، تبدیل نوع جادویی انجام می‌دهد:
.IP \(bu 2
مقادیر دقیق (literal)
.BR true ،
.BR false ،
.B null
و اعداد صحیح به انواع مناسب در JSON تبدیل می‌شوند؛
.IP \(bu 2
مقادیر جایگزین
.BR {owner} ،
.B {repo}
و
.B {branch}
با مقادیر مربوط به مخزن دایرکتوری جاری مقداردهی می‌شوند؛
.IP \(bu 2
اگر مقدار با
.B @
آغاز شود، باقی‌مانده مقدار به عنوان نام فایلی که مقدار باید از آن خوانده شود تفسیر می‌گردد\&. برای خواندن از ورودی استاندارد (stdin)، مقدار
.B \-
را ارسال کنید\&.

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

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

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

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

.SH "گزینه‌ها (OPTIONS)"
.TP
\fB\-\-allow\-escape\-sequences\fR
اجازه به چاپ توالی‌های گریز (escape sequences) ترمینال

.TP
\fB\-\-cache\fR \fB<duration>\fR
کش کردن پاسخ، برای مثال "3600s" ،"60m" ،"1h"

.TP
\fB\-F\fR, \fB\-\-field\fR \fB<key=value>\fR
افزودن یک پارامتر دارای نوع در قالب key=value (برای خواندن مقدار از فایل یا stdin از "@" یا "@\-" استفاده کنید)

.TP
\fB\-H\fR, \fB\-\-header\fR \fB<key:value>\fR
افزودن یک هدر درخواست HTTP در قالب key:value

.TP
\fB\-\-hostname\fR \fB<string>\fR
نام میزبان گیت‌هاب برای درخواست (پیش‌فرض "github.com")

.TP
\fB\-i\fR, \fB\-\-include\fR
گنجاندن خط وضعیت و هدرهای پاسخ HTTP در خروجی

.TP
\fB\-\-input\fR \fB<file>\fR
فایلی که به عنوان بدنه درخواست HTTP استفاده می‌شود (از "\-" برای خواندن از ورودی استاندارد استفاده کنید)

.TP
\fB\-q\fR, \fB\-\-jq\fR \fB<string>\fR
پرس‌وجو برای انتخاب مقادیر از پاسخ با استفاده از نحو jq

.TP
\fB\-X\fR, \fB\-\-method\fR \fB<string> (پیش‌فرض "GET")\fR
متد HTTP برای درخواست

.TP
\fB\-\-paginate\fR
ارسال درخواست‌های HTTP بیشتر برای واکشی تمامی صفحات نتایج

.TP
\fB\-p\fR, \fB\-\-preview\fR \fB<strings>\fR
فعال‌سازی پیش‌نمایش‌های رابط برنامه‌نویسی گیت‌هاب (نام‌ها باید بدون '\-preview' باشند)

.TP
\fB\-f\fR, \fB\-\-raw\-field\fR \fB<key=value>\fR
افزودن یک پارامتر رشته‌ای در قالب key=value

.TP
\fB\-\-silent\fR
عدم چاپ بدنه پاسخ

.TP
\fB\-\-slurp\fR
استفاده به همراه "\-\-paginate" برای بازگرداندن آرایه‌ای از تمام صفحات آرایه‌ها یا اشیاء JSON

.TP
\fB\-t\fR, \fB\-\-template\fR \fB<string>\fR
قالب‌بندی خروجی JSON با استفاده از الگوی Go؛ دستور "gh help formatting" را ببینید

.TP
\fB\-\-verbose\fR
گنجاندن درخواست و پاسخ کامل HTTP در خروجی

.SH "کدهای خروج (EXIT CODES)"
0: اجرای موفقیت‌آمیز

.PP
1: خطا

.PP
2: لغو دستور

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

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

.SH "مثال‌ها (EXAMPLES)"
.EX
# فهرست کردن انتشارها (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[])'

.EE

.SH "همچنین ببینید (SEE ALSO)"
\fBgh\fR(1)