XH(1) دستورهای کاربری XH(1)

xh - ابزاری کاربرپسند و سریع برای ارسال درخواست‌های HTTP

xh [OPTIONS] [METHOD] URL [--] [REQUEST_ITEM ...]

xh یک کلاینت HTTP با یک رابط خط فرمان کاربرپسند است. این ابزار تلاش می‌کند تا خروجی خوانا و گزینه‌هایی با استفاده آسان ارائه دهد.

xh تا حد زیادی با HTTPie سازگار است: http(1) را ببینید.

از گزینه --curl می‌توان برای چاپ معادل دستوری در curl(1) به‌جای ارسال درخواست استفاده کرد.

[METHOD]
متد HTTP برای استفاده در درخواست.

پیش‌فرض آن GET است، یا در صورتی که درخواست دارای بدنه باشد POST خواهد بود.

نشانی اینترنتی (URL) مقصد برای ارسال درخواست.

طرح‌واره نشانی اینترنتی (URL scheme) در حالت عادی به‌طور پیش‌فرض "http://" است، یا اگر برنامه با عنوان "xhs" فراخوانی شود، برابر با "https://" خواهد بود.

یک دونقطه در ابتدای نشانی به عنوان کوته‌نوشتی برای localhost عمل می‌کند. ":8000" معادل "localhost:8000" است و ":/path" معادل "localhost/path".

[REQUEST_ITEM ...]
جفت‌های کلید-مقدار اختیاری برای گنجانده شدن در درخواست.

جداکننده برای تعیین نوع مورد استفاده قرار می‌گیرد:

افزودن یک رشته جستار (query string) به URL.
افزودن یک ویژگی JSON (--json) یا فیلد فرم (--form) به بدنه درخواست.
افزودن یک فیلد با مقدار صریح JSON به بدنه درخواست.

مثال: "numbers:=[1,2,3] enabled:=true"

بارگذاری یک فایل (نیازمند --form یا --multipart).

برای تعیین نام فایل و نوع داده (mimetype)، به ترتیب می‌توان از ";type=" و ";filename=" استفاده کرد.

مثال: "pfp@ra.jpg;type=image/jpeg;filename=profile.jpg"

@filename
استفاده از یک فایل به عنوان بدنه درخواست.
افزودن یک سرایند، مانند "user-agent:foobar"
حذف یک سرایند، مانند "connection:"
افزودن یک سرایند با مقدار خالی.
می‌توان از پیشوند "@" برای خواندن مقدار از یک فایل استفاده کرد. برای مثال: "x-api-key:@api-key.txt".

از یک بک‌اسلش می‌توان برای گریز (escape) از نویسه‌های ویژه استفاده کرد، مانند "weird\:key=value".

برای ساخت یک شیء پیچیده JSON، کلید REQUEST_ITEM می‌تواند به‌جای نام یک فیلد، یک مسیر JSON (یا JSON path) باشد. برای اطلاعات بیشتر درباره این نحو، به https://httpie.io/docs/cli/nested-json مراجعه کنید.

هر --OPTION را می‌توان با یک آرگومان --no-OPTION بازنشانی کرد.

(پیش‌فرض) سریال‌سازی موارد داده از خط فرمان به عنوان یک شیء JSON.

بر هر دو گزینه --form و --multipart اولویت دارد.

سریال‌سازی موارد داده از خط فرمان به عنوان فیلدهای فرم.

بر هر دو گزینه --json و --multipart اولویت دارد.

مشابه --form، اما یک درخواست multipart/form-data را حتی بدون وجود فایل اجبار می‌کند.

بر هر دو گزینه --json و --form اولویت دارد.

ارسال داده‌های خام درخواست بدون پردازش اضافه.
پردازش خروجی را کنترل می‌کند. مقادیر ممکن عبارت‌اند از:
(پیش‌فرض) فعال‌سازی هم‌زمان رنگ‌آمیزی و قالب‌بندی
اعمال برجسته‌سازی نحوی (syntax highlighting) بر روی خروجی
قالب‌بندی زیبای JSON و مرتب‌سازی سرایندها
غیرفعال‌سازی هم‌زمان رنگ‌آمیزی و قالب‌بندی
در صورتی که متغیر محیطی NO_COLOR تنظیم شده باشد، مقدار پیش‌فرض "format" است و در صورتی که خروجی استاندارد (stdout) از نوع tty نباشد، برابر "none" خواهد بود.
--format-options=FORMAT_OPTIONS
تنظیم گزینه‌های قالب‌بندی خروجی. گزینه‌های پشتیبانی‌شده عبارت‌اند از:
json.indent:<NUM>
json.format:<true|false>
xml.indent:<NUM>
xml.format:<true|false>
headers.sort:<true|false>
مثال: --format-options=json.indent:2,headers.sort:false.
سبک رنگ‌آمیزی خروجی.

[مقادیر ممکن: auto, solarized, monokai, fruity]

بازنویسی کدگذاری (encoding) پاسخ برای مقاصد نمایش در ترمینال.

مثال: --response-charset=latin1.

بازنویسی نوع MIME پاسخ برای رنگ‌آمیزی و قالب‌بندی در ترمینال.

مثال: --response-mime=application/json.

رشته‌ای که مشخص می‌کند خروجی باید شامل چه مواردی باشد
سرایندهای درخواست
بدنه درخواست
سرایندهای پاسخ
بدنه پاسخ
فراداده (متادیتای) پاسخ
مثال: --print=Hb..TP 4 -h, --headers فقط سرایندهای پاسخ چاپ شوند. میان‌بری برای --print=h.
-b, --body
فقط بدنهٔ پاسخ چاپ شود. میان‌بری برای --print=b.
-m, --meta
فقط فراداده‌های پاسخ چاپ شوند. میان‌بری برای --print=m.
کل درخواست و همچنین پاسخ چاپ شود.

علاوه بر این، این گزینه --all را برای چاپ درخواست‌ها/پاسخ‌های واسط هنگام دنبال‌کردن تغییر مسیرها فعال می‌کند.

استفادهٔ دوبار از گزینهٔ پرگویی، یعنی -vv، فراداده‌های پاسخ را نیز چاپ خواهد کرد.

معادل با --print=HhBb --all.

ردیابی کامل پشتهٔ خطاها (stack traces) و پیام‌های گزارش اشکال‌زدایی چاپ شوند.

ثبت وقایع (logging) را می‌توان با جزئیات بیشتر با استفاده از متغیر محیطی `$RUST_LOG` پیکربندی کرد. برای نمایش پیام‌های بیشتر مقدار `RUST_LOG=trace` را تنظیم کنید. به https://docs.rs/env_logger/0.11.3/env_logger/#enabling-logging مراجعه کنید.

--all
نمایش هرگونه درخواست/پاسخ واسط هنگام دنبال‌کردن تغییر مسیرها با --follow.
مشابه با --print اما تنها برای درخواست‌ها/پاسخ‌های واسط اعمال می‌شود.
چیزی در stdout یا stderr چاپ نشود.

استفادهٔ دوبار از حالت بی‌صدا، یعنی -qq، هشدارها را نیز غیرفعال می‌کند.

همیشه بدنهٔ پاسخ به‌صورت جاری (stream) دریافت شود.
محتوا با الگوریتم Deflate فشرده‌سازی (کدگذاری) شود.

سرایند Content-Encoding بر روی deflate تنظیم می‌شود.

اگر به نظر برسد نسبت فشرده‌سازی منفی است، از فشرده‌سازی صرف‌نظر می‌شود. با تکرار این گزینه می‌توان فشرده‌سازی را اجبار کرد.

نکته: در صورت وجود سرایند درخواست Content-Encoding نمی‌توان از فشرده‌سازی استفاده کرد.

ذخیرهٔ خروجی در FILE به‌جای stdout.
بارگیری بدنه در یک فایل به‌جای چاپ آن.

سرایند Accept-Encoding بر روی identity تنظیم شده و تمامی تغییر مسیرها دنبال خواهند شد.

ازسرگیری یک بارگیری قطع‌شده. نیازمند گزینه‌های --download و --output است.
ایجاد، یا استفادهٔ مجدد و به‌روزرسانی یک نشست (session).

درون یک نشست، سرایندهای سفارشی، مشخصات احراز هویت و هرگونه کوکی ارسال‌شده از سوی سرور میان درخواست‌ها حفظ می‌شوند.

ایجاد یا خواندن یک نشست بدون به‌روزرسانی آن از طریق تبادل درخواست/پاسخ.
تعیین سازوکار احراز هویت.

[مقادیر ممکن: basic, bearer, digest]

احراز هویت به‌عنوان USER با رمز عبور PASS (-A basic|digest) یا با TOKEN (-A bearer).

در صورت نبود PASS، اعلان ورود آن نمایش داده خواهد شد. برای احراز هویت تنها با نام کاربری، از دونقطه در انتها (یعنی "USER:") استفاده کنید.

اگر --auth-type=bearer باشد، مقدار TOKEN انتظار می‌رود.

اطلاعات احراز هویت از .netrc استفاده نشود.
ساخت درخواست‌های HTTP بدون ارسال آن‌ها.
(پیش‌فرض) خروج با کد وضعیت خطا در صورتی که سرور با خطا پاسخ دهد.

کد خروج در خطاهای 4xx (خطای کلاینت) برابر ۴، در خطاهای 5xx (خطای سرور) برابر ۵، و در خطاهای 3xx (تغییر مسیر) در صورتی که --follow تنظیم نشده باشد برابر ۳ خواهد بود.

اگر stdout تغییر مسیر داده شده باشد، یک هشدار در stderr نوشته می‌شود.

دنبال‌کردن تغییر مسیرها.
تعداد تغییر مسیرها برای دنبال‌کردن. تنها در صورت استفاده از --follow ترتیب اثر داده می‌شود.
مدت‌زمان انتظار اتصال (timeout) برای درخواست بر حسب ثانیه.

مقدار پیش‌فرض "0" است، یعنی هیچ محدودیت زمانی وجود ندارد.

استفاده از یک پیشکار (proxy) برای یک پروتکل. برای مثال: --proxy https:http://proxy.host:8080.

مقدار PROTOCOL می‌تواند "all" ،"http" یا "https" باشد.

اگر پیشکار شما نیازمند مشخصات احراز هویت است، آن‌ها را درون URL قرار دهید، مانند: --proxy http:socks5://user:password@proxy.host:8000.

با تکرار این گزینه می‌توانید برای چندین پروتکل پیشکارهای مختلف تعیین کنید.

متغیرهای محیطی "ALL_PROXY" ،"HTTP_PROXY" و "HTTPS_PROXY" نیز می‌توانند استفاده شوند، اما در صورت ارسال --proxy کاملاً نادیده گرفته می‌شوند.

اگر "no" باشد، اعتبارسنجی SSL نادیده گرفته می‌شود. اگر یک مسیر فایل باشد، به‌عنوان بستهٔ CA استفاده می‌شود.

تعیین بستهٔ CA، گواهی‌های ریشهٔ داخلی سیستم را غیرفعال می‌کند.

استفاده از "false" به‌جای "no" نیز کار می‌کند. پیش‌فرض "yes" ("true") است.

استفاده از یک گواهی سمت کلاینت برای SSL.
یک فایل کلید خصوصی برای استفاده همراه با --cert.

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

اجبار برای استفاده از یک نسخهٔ خاص TLS.

مقدار "auto" رفتار پیش‌فرض مذاکره بر سر نسخه با سرور را فراهم می‌کند.

[مقادیر ممکن: auto, tls1, tls1.1, tls1.2, tls1.3]

استفاده از کتابخانهٔ TLS سیستم به‌جای rustls (در صورت فعال بودن در زمان کامپایل).
ارسال درخواست‌ها به‌صورت HTTPS در صورتی که در URL مشخص نشده باشد.
نسخهٔ HTTP مورد استفاده.

[مقادیر ممکن: 1.0, 1.1, 2, 2-prior-knowledge, 3-prior-knowledge]

بازنویسی تحلیل نام DNS برای دامنه‌ای خاص به یک IP سفارشی.

با تکرار این گزینه می‌توانید چندین دامنه را بازنویسی کنید.

مثال: --resolve=example.com:127.0.0.1.

اتصال (bind) به یک رابط شبکه یا آدرس IP محلی.

مثال: --interface=eth0 --interface=192.168.0.2.

-4, --ipv4
تحلیل نام میزبان فقط به نشانی‌های ipv4.
-6, --ipv6
تحلیل نام میزبان فقط به نشانی‌های ipv6.
اتصال با استفاده از یک سوکت دامنهٔ یونیکس (Unix domain socket).

مثال: xh :/index.html --unix-socket=/var/run/temp.sock..TP 4 -I, --ignore-stdin برای خواندن ورودی استاندارد (stdin) تلاش نکن.

این گزینه رفتار پیش‌فرض مبنی بر خواندن بدنه درخواست از stdin در صورت تشخیص ورودی هدایت‌شده (redirected) را غیرفعال می‌کند.

توصیه می‌شود هنگام استفاده از xh برای اهداف اسکریپت‌نویسی، این پرچم مشخص شود. برای اطلاعات بیشتر، به https://httpie.io/docs/cli/best-practices مراجعه کنید.

چاپ معادل دستور در قالب یک دستور curl.

برای ترجمه معکوس، به https://curl2httpie.online مراجعه کنید.

استفاده از نسخه بلند پرچم‌های curl.
تولید تکمیل‌کننده‌های پوسته (shell completions) یا صفحات راهنما. مقادیر معتبر عبارتند از:
تولید تکمیل‌کننده برای bash
تولید تکمیل‌کننده برای elvish
تولید تکمیل‌کننده برای fish
تولید تکمیل‌کننده برای nushell
تولید تکمیل‌کننده برای powershell
تولید تکمیل‌کننده برای zsh
تولید صفحه راهنما در قالب roff
man-markdown
تولید صفحه راهنما در قالب markdown
مثال: xh --generate=complete-bash > xh.bash.
چاپ راهنما.
چاپ نسخه.

0
اجرای موفقیت‌آمیز برنامه.
1
خطای کاربرد، نحو (syntax) یا شبکه.
2
پایان مهلت زمانی درخواست (timeout).
3
تغییر مسیر غیرمنتظره HTTP 3xx.
4
خطای سمت کلاینت HTTP 4xx.
5
خطای سمت سرور HTTP 5xx.
6
تغییر مسیرهای بیش از حد (too many redirects).

محل جستجو برای فایل config.json و داده‌های نشست‌های نام‌گذاری‌شده را مشخص می‌کند. مقدار پیش‌فرض در Linux/macOS برابر ~/.config/xh و در Windows برابر %APPDATA%\xh است.
حالت سازگاری با HTTPie را فعال می‌کند. تنها تفاوت فعلی این است که --check-status به‌طور پیش‌فرض فعال نیست. راهکار جایگزین به‌جای تنظیم این متغیر محیطی، تغییر نام فایل باینری اجرایی به http یا https است.
مسیر سفارشی بسته گواهی‌های CA (CA bundle) را تنظیم می‌کند.
سرور پروکسی را برای همه درخواست‌ها تنظیم می‌کند (مگر اینکه برای پروتکلی خاص بازنویسی شده باشد).
سرور پروکسی مورد استفاده برای HTTP را مشخص می‌کند.
سرور پروکسی مورد استفاده برای HTTPS را مشخص می‌کند.
فهرستی از میزبان‌های جداشده با کاما که باید سایر متغیرهای محیطی پروکسی برای آن‌ها نادیده گرفته شوند. "*" با همه نام‌های میزبان مطابقت دارد.
مکان فایل .netrc.
رنگ‌آمیزی خروجی را غیرفعال می‌کند. ببینید https://no-color.org
پیکربندی پیام‌های اشکال‌زدایی سطح پایین. ببینید https://docs.rs/env_logger/0.11.3/env_logger/#enabling-logging

~/.config/xh/config.json
فایل پیکربندی xh. تنها گزینه قابل‌پیکربندی "default_options" است که فهرستی از آرگومان‌های پیش‌فرض پوسته را مشخص می‌کند که به xh ارسال می‌شوند. مثال:
{ "default_options": ["--native-tls", "--style=solarized"] }
~/.netrc, ~/_netrc
فایل اطلاعات ورود خودکار (auto-login).
~/.config/xh/sessions
دایرکتوری داده‌های نشست (session) که بر اساس دامنه و شماره پورت دسته‌بندی شده‌اند..SH "مثال‌ها (EXAMPLES)"
ارسال یک درخواست GET.
ارسال یک درخواست POST با بدنهٔ {"name": "ahmed", "age": 24}.
ارسال یک درخواست GET به http://httpbin.org/json?id=5&sort=true.
ارسال یک درخواست GET به همراه سرآیندی به نام X-Api-Key با مقدار 12345.
ارسال یک درخواست POST با بدنه‌ای که از stdin خوانده می‌شود.
ارسال یک درخواست PUT و لوله‌کشی (pipe) نتیجه به less.
دانلود و ذخیره در res.json.
برقراری یک درخواست با عامل کاربر (User-Agent) سفارشی.
برقراری یک درخواست HTTPS به https://example.com.

بخش مسائل گیت‌هاب xh در https://github.com/ducaale/xh/issues

curl(1), http(1)

مستندات برخط HTTPie در https://httpie.io/docs/cli

2026-07-26 0.26.2