.nh
.TH "glab" "1" "Sep 2026" "Auto generated by spf13/cobra" ""

.SH "نام (NAME)"
glab-api \- برقراری یک درخواست احراز هویت‌شده به API گیت‌لب


.SH "خلاصه دستور (SYNOPSIS)"
\fBglab api  [flags]\fP


.SH "توضیحات (DESCRIPTION)"
یک درخواست HTTP احراز هویت‌شده به GitLab API ارسال کرده و پاسخ را چاپ می‌کند.
یک مسیر به یکی از نقاط پایانی نسخه ۴ API گیت‌لب یا \fBgraphql\fR را برای دسترسی به
GitLab GraphQL API مشخص کنید.

.PP
برای کسب اطلاعات بیشتر، به موارد زیر مراجعه کنید:
.IP \(bu 2
مستندات GitLab REST API
\[la]https://docs.gitlab.com/api\[ra]
.IP \(bu 2
مستندات GitLab GraphQL
\[la]https://docs.gitlab.com/api/graphql\[ra]

.PP
اگر دایرکتوری جاری یک دایرکتوری گیت باشد، این دستور از میزبان احراز هویت‌شدهٔ گیت‌لب
در دایرکتوری جاری استفاده می‌کند. در غیر این صورت، از \fBgitlab.com\fR استفاده می‌شود.
برای تغییر نام میزبان گیت‌لب، از گزینه \fB--hostname\fR استفاده کنید.

.PP
هنگامی که این متغیرهای جایگزین در آرگومان نقطه پایانی (endpoint) به کار روند،
با مقادیر مربوط به مخزن در دایرکتوری جاری جایگزین می‌شوند:
.IP \(bu 2
\fB:branch\fR
.IP \(bu 2
\fB:fullpath\fR
.IP \(bu 2
\fB:group\fR
.IP \(bu 2
\fB:id\fR
.IP \(bu 2
\fB:namespace\fR
.IP \(bu 2
\fB:repo\fR
.IP \(bu 2
\fB:user\fR
.IP \(bu 2
\fB:username\fR

.PP
متد پیش‌فرض درخواست HTTP در صورتی که پارامتری افزوده نشود \fBGET\fR و در غیر این صورت \fBPOST\fR است.
برای تغییر متد، از گزینه \fB--method\fR استفاده کنید.

.PP
یک یا چند مقدار \fB--raw-field\fR را در قالب \fBkey=value\fR ارسال کنید تا
پارامترهای رشته‌ای کدگذاری‌شده به‌صورت JSON به بدنه درخواست \fBPOST\fR اضافه شوند.

.PP
گزینه \fB--field\fR مانند \fB--raw-field\fR عمل می‌کند اما مقادیر را بر اساس قالب آن‌ها تبدیل می‌نماید:
.IP \(bu 2
مقادیر صریح \fBtrue\fR، \fBfalse\fR، \fBnull\fR و اعداد صحیح به انواع متناظر در JSON تبدیل می‌شوند.
.IP \(bu 2
مقادیری که با \fB[\fR یا \fB{\fR شروع شوند، به عنوان آرایه‌ها یا اشیاء JSON تجزیه می‌شوند
(مانند \fB-F 'topics=["my-topic","GitLab"]'\fR). ساختار نامعتبر JSON یک خطا برمی‌گرداند.
مقدار باید حتماً با قلاب یا آکولاد آغاز شود: فاصله ابتدایی مانند
\fB-F 'topics= ["a"]'\fR بخشی از مقدار در نظر گرفته شده و به صورت رشته متنی ارسال می‌شود.
.IP \(bu 2
مقادیر جایگزین \fB:namespace\fR، \fB:repo\fR و \fB:branch\fR با مقادیر مربوط به مخزن در دایرکتوری جاری
جایگزین می‌شوند، حتی در داخل آرایه‌ها و اشیاء JSON (مانند \fB-F 'input={"projectPath":":fullpath"}'\fR).
.IP \(bu 2
اگر مقدار با \fB@\fR شروع شود، باقی‌مانده مقدار به عنوان نام فایلی برای خواندن داده‌ها تفسیر می‌شود.
برای خواندن از ورودی استاندارد (stdin)، مقدار \fB-\fR را بفرستید.

.PP
گزینه \fB--raw-field\fR آرایه‌ها یا اشیاء JSON را تجزیه نمی‌کند؛ این مقادیر به صورت رشته ارسال می‌شوند.
برای ارسال مستقیم بدنه JSON، از گزینه \fB--input\fR استفاده کنید.

.PP
یک مقدار درون قلاب برای \fB--raw-field\fR مانند \fB-f 'scopes=[api,read_api]'\fR به عنوان
رشته متنی مستقیم \fB"[api,read_api]"\fR ارسال می‌شود. در نسخه‌های قبلی این ساختار در بدنه درخواست
به یک آرایه تبدیل می‌شد که هرگز در مستندات \fB--raw-field\fR ذکر نشده بود. برای ایجاد آرایه از
\fB-F 'scopes=["api","read_api"]'\fR استفاده کنید.

.PP
برای درخواست‌های GraphQL، تمام فیلدها به جز \fBquery\fR و \fBoperationName\fR به عنوان
متغیرهای GraphQL تفسیر می‌شوند.

.PP
برای ارسال داده‌ها به صورت \fBmultipart/form-data\fR به جای JSON، از گزینه \fB--form\fR استفاده کنید.
این گزینه برای نقاط پایانی API که بارگذاری فایل را می‌پذیرند، مانند پیوست‌های ویکی، الزامی است.
یک یا چند مقدار \fB--form\fR را در قالب \fBkey=value\fR مشخص کنید. برای بارگذاری فایل، در ابتدای
مقدار از \fB@\fR و به دنبال آن مسیر فایل استفاده کنید. برای خواندن از ورودی استاندارد، \fB-\fR را ارسال کنید.
گزینه \fB--form\fR را با \fB--field\fR، \fB--raw-field\fR یا \fB--input\fR ترکیب نکنید.

.PP
برای ارسال بدنه خام یک درخواست، از گزینه \fB--input\fR همراه با مسیر فایل استفاده کنید. برای
خواندن از ورودی استاندارد، \fB-\fR را بفرستید. در این حالت، پارامترهای مشخص‌شده با گزینه‌های
\fB--field\fR به صورت پارامترهای پرسمان (query parameters) در URL قرار می‌گیرند.

.PP
در حالت \fB--paginate\fR، تمام صفحات نتایج به صورت متوالی درخواست می‌شوند تا زمانی که
صفحه‌ای باقی نماند. برای درخواست‌های GraphQL:
.IP \(bu 2
پرسمان اولیه باید یک متغیر \fB$endCursor: String\fR را بپذیرد.
.IP \(bu 2
پرسمان باید مجموعه فیلدهای \fBpageInfo{ hasNextPage, endCursor }\fR را از یک مجموعه (collection) دریافت کند.

.PP
گزینه \fB--output\fR قالب خروجی را کنترل می‌کند:
.IP \(bu 2
\fBjson\fR (پیش‌فرض): ساختار JSON خوانا و قالب‌بندی‌شده (Pretty-printed). آرایه‌ها به صورت یک آرایه واحد JSON چاپ می‌شوند.
.IP \(bu 2
\fBndjson\fR: ساختار JSON جداشده با خطوط جدید (Newline-delimited JSON)، مشهور به JSON Lines. هر عنصر
آرایه یا شیء در یک خط مجزا چاپ می‌شود. این قالب برای مجموعه‌داده‌های بزرگ از نظر مصرف حافظه بهینه‌تر بوده
و به خوبی با ابزارهایی مانند \fBjq\fR سازگار است.

.PP
برای مشاهده مشخصات قالب ndjson، به مستندات ndjson در
\[la]https://github.com/ndjson/ndjson\-spec\[ra] و JSON Lines در
\[la]https://jsonlines.org\[ra]\& مراجعه فرمایید.


.SH "گزینه‌ها (OPTIONS)"
\fB-F\fP, \fB--field\fP=[]
	افزودن پارامتری با نوع استنباط‌شده. استفاده از این سوییچ، متد پیش‌فرض HTTP را به POST تغییر می‌دهد.

.PP
\fB--form\fP=[]
	افزودن فیلد چندبخشی فرم (multipart form). برای بارگذاری یک فایل، در ابتدای مقدار از علامت @ و در پی آن مسیر فایل استفاده کنید. برای خواندن از ورودی استاندارد، از @- استفاده نمایید (حداکثر یک بار). استفاده از این سوییچ، متد پیش‌فرض HTTP را به POST تغییر می‌دهد.

.PP
\fB-H\fP, \fB--header\fP=[]
	افزودن یک هدر اضافی به درخواست HTTP.

.PP
\fB--hostname\fP=""
	نام میزبان گیت‌لب برای درخواست. پیش‌فرض gitlab.com، یا میزبان احراز هویت‌شده در دایرکتوری گیت جاری است.

.PP
\fB-i\fP, \fB--include\fP[=false]
	گنجاندن هدرهای پاسخ HTTP در خروجی.

.PP
\fB--input\fP=""
	فایلی که به عنوان بدنه درخواست HTTP استفاده می‌شود.

.PP
\fB-X\fP, \fB--method\fP="GET"
	متد HTTP برای ارسال درخواست.

.PP
\fB--output\fP="json"
	قالب‌بندی خروجی به صورت: json, ndjson.

.PP
\fB--paginate\fP[=false]
	ارسال درخواست‌های HTTP مکرر برای دریافت همه صفحات نتایج.

.PP
\fB-f\fP, \fB--raw-field\fP=[]
	افزودن یک پارامتر رشته‌ای متنی.

.PP
\fB--silent\fP[=false]
	جلوگیری از چاپ بدنه پاسخ در خروجی.


.SH "گزینه‌های به ارث رسیده از دستورات والد (OPTIONS INHERITED FROM PARENT COMMANDS)"
\fB-h\fP, \fB--help\fP[=false]
	نمایش راهنما برای این دستور.


.SH "مثال‌ها (EXAMPLES)"
.EX
# فهرست کردن نسخه‌های منتشرشده پروژه جاری، با بسط متغیر جایگزین :fullpath
glab api projects/:fullpath/releases

# فهرست کردن مشکلات (issues) یک پروژه با مسیر کدگذاری‌شده در URL
glab api projects/gitlab-com%2Fwww-gitlab-com/issues

# بارگذاری یک فایل در ویکی پروژه
glab api --method POST projects/:fullpath/wikis/attachments --form "file=@./image.png" --form "branch=main"

# اشکال‌زدایی درخواست و پاسخ HTTP، شامل هدرها و بدنه.
# استفاده از --input برای ارسال بدنه کامل درخواست JSON از ورودی استاندارد (stdin).
echo '{"allowed_to_push":[{"user_id":1}]}' | GLAB_DEBUG_HTTP=1 glab api -X PATCH "projects/:fullpath/protected_branches/main" --input -

# دریافت تمام صفحات مسائل (issues)
glab api issues --paginate

# دریافت تمام صفحات مسائل به صورت ndjson
glab api issues --paginate --output ndjson

# هدایت خروجی صفحه‌بندی‌شده به jq برای فیلتر کردن مسائل باز
glab api issues --paginate --output ndjson | jq 'select(.state == "opened")'

# اجرای یک پرسمان ساده GraphQL
glab api graphql -f query="query { currentUser { username } }"

# اجرای یک پرسمان چندخطی GraphQL برای دریافت متادیتای پروژه
glab api graphql -f query='
  query {
    project(fullPath: "gitlab-org/gitlab-docs") {
      name
      forksCount
      statistics {
        wikiSize
      }
      issuesEnabled
      boards {
        nodes {
          id
          name
        }
      }
    }
  }
\&'

# اجرای یک پرسمان صفحه‌بندی‌شده GraphQL با استفاده از متغیر endCursor
glab api graphql --paginate -f query='
  query($endCursor: String) {
    project(fullPath: "gitlab-org/graphql-sandbox") {
      name
      issues(first: 2, after: $endCursor) {
        edges {
          node {
            title
          }
        }
        pageInfo {
          endCursor
          hasNextPage
        }
      }
    }
  }'

.EE


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