XH(1) دستورهای کاربری XH(1) نام (NAME) xh - ابزاری کاربرپسند و سریع برای ارسال درخواست‌های HTTP خلاصه دستور (SYNOPSIS) xh [OPTIONS] [METHOD] URL [--] [REQUEST_ITEM ...] توضیحات (DESCRIPTION) xh یک کلاینت HTTP با یک رابط خط فرمان کاربرپسند است. این ابزار تلاش می‌کند تا خروجی خوانا و گزینه‌هایی با استفاده آسان ارائه دهد. xh تا حد زیادی با HTTPie سازگار است: http(1) را ببینید. از گزینه --curl می‌توان برای چاپ معادل دستوری در curl(1) به‌جای ارسال درخواست استفاده کرد. آرگومان‌های مکانی (POSITIONAL ARGUMENTS) [METHOD] متد HTTP برای استفاده در درخواست. پیش‌فرض آن GET است، یا در صورتی که درخواست دارای بدنه باشد POST خواهد بود. URL نشانی اینترنتی (URL) مقصد برای ارسال درخواست. طرح‌واره نشانی اینترنتی (URL scheme) در حالت عادی به‌طور پیش‌فرض "http://" است، یا اگر برنامه با عنوان "xhs" فراخوانی شود، برابر با "https://" خواهد بود. یک دونقطه در ابتدای نشانی به عنوان کوته‌نوشتی برای localhost عمل می‌کند. ":8000" معادل "localhost:8000" است و ":/path" معادل "localhost/path". [REQUEST_ITEM ...] جفت‌های کلید-مقدار اختیاری برای گنجانده شدن در درخواست. جداکننده برای تعیین نوع مورد استفاده قرار می‌گیرد: key==value افزودن یک رشته جستار (query string) به URL. key=value افزودن یک ویژگی JSON (--json) یا فیلد فرم (--form) به بدنه درخواست. key:=value افزودن یک فیلد با مقدار صریح JSON به بدنه درخواست. مثال: "numbers:=[1,2,3] enabled:=true" key@filename بارگذاری یک فایل (نیازمند --form یا --multipart). برای تعیین نام فایل و نوع داده (mimetype)، به ترتیب می‌توان از ";type=" و ";filename=" استفاده کرد. مثال: "pfp@ra.jpg;type=image/jpeg;filename=profile.jpg" @filename استفاده از یک فایل به عنوان بدنه درخواست. header:value افزودن یک سرایند، مانند "user-agent:foobar" header: حذف یک سرایند، مانند "connection:" header; افزودن یک سرایند با مقدار خالی. می‌توان از پیشوند "@" برای خواندن مقدار از یک فایل استفاده کرد. برای مثال: "x-api-key:@api-key.txt". از یک بک‌اسلش می‌توان برای گریز (escape) از نویسه‌های ویژه استفاده کرد، مانند "weird\:key=value". برای ساخت یک شیء پیچیده JSON، کلید REQUEST_ITEM می‌تواند به‌جای نام یک فیلد، یک مسیر JSON (یا JSON path) باشد. برای اطلاعات بیشتر درباره این نحو، به https://httpie.io/docs/cli/nested-json مراجعه کنید. گزینه‌ها (OPTIONS) هر --OPTION را می‌توان با یک آرگومان --no-OPTION بازنشانی کرد. -j, --json (پیش‌فرض) سریال‌سازی موارد داده از خط فرمان به عنوان یک شیء JSON. بر هر دو گزینه --form و --multipart اولویت دارد. -f, --form سریال‌سازی موارد داده از خط فرمان به عنوان فیلدهای فرم. بر هر دو گزینه --json و --multipart اولویت دارد. --multipart مشابه --form، اما یک درخواست multipart/form-data را حتی بدون وجود فایل اجبار می‌کند. بر هر دو گزینه --json و --form اولویت دارد. --raw=RAW ارسال داده‌های خام درخواست بدون پردازش اضافه. --pretty=STYLE پردازش خروجی را کنترل می‌کند. مقادیر ممکن عبارت‌اند از: all (پیش‌فرض) فعال‌سازی هم‌زمان رنگ‌آمیزی و قالب‌بندی colors اعمال برجسته‌سازی نحوی (syntax highlighting) بر روی خروجی format قالب‌بندی زیبای JSON و مرتب‌سازی سرایندها none غیرفعال‌سازی هم‌زمان رنگ‌آمیزی و قالب‌بندی در صورتی که متغیر محیطی NO_COLOR تنظیم شده باشد، مقدار پیش‌فرض "format" است و در صورتی که خروجی استاندارد (stdout) از نوع tty نباشد، برابر "none" خواهد بود. --format-options=FORMAT_OPTIONS تنظیم گزینه‌های قالب‌بندی خروجی. گزینه‌های پشتیبانی‌شده عبارت‌اند از: json.indent: json.format: xml.indent: xml.format: headers.sort: مثال: --format-options=json.indent:2,headers.sort:false. -s, --style=THEME سبک رنگ‌آمیزی خروجی. [مقادیر ممکن: auto, solarized, monokai, fruity] --response-charset=ENCODING بازنویسی کدگذاری (encoding) پاسخ برای مقاصد نمایش در ترمینال. مثال: --response-charset=latin1. --response-mime=MIME_TYPE بازنویسی نوع MIME پاسخ برای رنگ‌آمیزی و قالب‌بندی در ترمینال. مثال: --response-mime=application/json. -p, --print=FORMAT رشته‌ای که مشخص می‌کند خروجی باید شامل چه مواردی باشد H سرایندهای درخواست B بدنه درخواست h سرایندهای پاسخ b بدنه پاسخ m فراداده (متادیتای) پاسخ مثال: --print=Hb..TP 4 -h, --headers فقط سرایندهای پاسخ چاپ شوند. میان‌بری برای --print=h. -b, --body فقط بدنهٔ پاسخ چاپ شود. میان‌بری برای --print=b. -m, --meta فقط فراداده‌های پاسخ چاپ شوند. میان‌بری برای --print=m. -v, --verbose کل درخواست و همچنین پاسخ چاپ شود. علاوه بر این، این گزینه --all را برای چاپ درخواست‌ها/پاسخ‌های واسط هنگام دنبال‌کردن تغییر مسیرها فعال می‌کند. استفادهٔ دوبار از گزینهٔ پرگویی، یعنی -vv، فراداده‌های پاسخ را نیز چاپ خواهد کرد. معادل با --print=HhBb --all. --debug ردیابی کامل پشتهٔ خطاها (stack traces) و پیام‌های گزارش اشکال‌زدایی چاپ شوند. ثبت وقایع (logging) را می‌توان با جزئیات بیشتر با استفاده از متغیر محیطی `$RUST_LOG` پیکربندی کرد. برای نمایش پیام‌های بیشتر مقدار `RUST_LOG=trace` را تنظیم کنید. به https://docs.rs/env_logger/0.11.3/env_logger/#enabling-logging مراجعه کنید. --all نمایش هرگونه درخواست/پاسخ واسط هنگام دنبال‌کردن تغییر مسیرها با --follow. -P, --history-print=FORMAT مشابه با --print اما تنها برای درخواست‌ها/پاسخ‌های واسط اعمال می‌شود. -q, --quiet چیزی در stdout یا stderr چاپ نشود. استفادهٔ دوبار از حالت بی‌صدا، یعنی -qq، هشدارها را نیز غیرفعال می‌کند. -S, --stream همیشه بدنهٔ پاسخ به‌صورت جاری (stream) دریافت شود. -x, --compress محتوا با الگوریتم Deflate فشرده‌سازی (کدگذاری) شود. سرایند Content-Encoding بر روی deflate تنظیم می‌شود. اگر به نظر برسد نسبت فشرده‌سازی منفی است، از فشرده‌سازی صرف‌نظر می‌شود. با تکرار این گزینه می‌توان فشرده‌سازی را اجبار کرد. نکته: در صورت وجود سرایند درخواست Content-Encoding نمی‌توان از فشرده‌سازی استفاده کرد. -o, --output=FILE ذخیرهٔ خروجی در FILE به‌جای stdout. -d, --download بارگیری بدنه در یک فایل به‌جای چاپ آن. سرایند Accept-Encoding بر روی identity تنظیم شده و تمامی تغییر مسیرها دنبال خواهند شد. -c, --continue ازسرگیری یک بارگیری قطع‌شده. نیازمند گزینه‌های --download و --output است. --session=FILE ایجاد، یا استفادهٔ مجدد و به‌روزرسانی یک نشست (session). درون یک نشست، سرایندهای سفارشی، مشخصات احراز هویت و هرگونه کوکی ارسال‌شده از سوی سرور میان درخواست‌ها حفظ می‌شوند. --session-read-only=FILE ایجاد یا خواندن یک نشست بدون به‌روزرسانی آن از طریق تبادل درخواست/پاسخ. -A, --auth-type=AUTH_TYPE تعیین سازوکار احراز هویت. [مقادیر ممکن: basic, bearer, digest] -a, --auth=USER[:PASS] | TOKEN احراز هویت به‌عنوان USER با رمز عبور PASS (-A basic|digest) یا با TOKEN (-A bearer). در صورت نبود PASS، اعلان ورود آن نمایش داده خواهد شد. برای احراز هویت تنها با نام کاربری، از دونقطه در انتها (یعنی "USER:") استفاده کنید. اگر --auth-type=bearer باشد، مقدار TOKEN انتظار می‌رود. --ignore-netrc اطلاعات احراز هویت از .netrc استفاده نشود. --offline ساخت درخواست‌های HTTP بدون ارسال آن‌ها. --check-status (پیش‌فرض) خروج با کد وضعیت خطا در صورتی که سرور با خطا پاسخ دهد. کد خروج در خطاهای 4xx (خطای کلاینت) برابر ۴، در خطاهای 5xx (خطای سرور) برابر ۵، و در خطاهای 3xx (تغییر مسیر) در صورتی که --follow تنظیم نشده باشد برابر ۳ خواهد بود. اگر stdout تغییر مسیر داده شده باشد، یک هشدار در stderr نوشته می‌شود. -F, --follow دنبال‌کردن تغییر مسیرها. --max-redirects=NUM تعداد تغییر مسیرها برای دنبال‌کردن. تنها در صورت استفاده از --follow ترتیب اثر داده می‌شود. --timeout=SEC مدت‌زمان انتظار اتصال (timeout) برای درخواست بر حسب ثانیه. مقدار پیش‌فرض "0" است، یعنی هیچ محدودیت زمانی وجود ندارد. --proxy=PROTOCOL:URL استفاده از یک پیشکار (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 کاملاً نادیده گرفته می‌شوند. --verify=VERIFY اگر "no" باشد، اعتبارسنجی SSL نادیده گرفته می‌شود. اگر یک مسیر فایل باشد، به‌عنوان بستهٔ CA استفاده می‌شود. تعیین بستهٔ CA، گواهی‌های ریشهٔ داخلی سیستم را غیرفعال می‌کند. استفاده از "false" به‌جای "no" نیز کار می‌کند. پیش‌فرض "yes" ("true") است. --cert=FILE استفاده از یک گواهی سمت کلاینت برای SSL. --cert-key=FILE یک فایل کلید خصوصی برای استفاده همراه با --cert. تنها در صورتی لازم است که کلید خصوصی در فایل گواهی گنجانده نشده باشد. --ssl=VERSION اجبار برای استفاده از یک نسخهٔ خاص TLS. مقدار "auto" رفتار پیش‌فرض مذاکره بر سر نسخه با سرور را فراهم می‌کند. [مقادیر ممکن: auto, tls1, tls1.1, tls1.2, tls1.3] --native-tls استفاده از کتابخانهٔ TLS سیستم به‌جای rustls (در صورت فعال بودن در زمان کامپایل). --https ارسال درخواست‌ها به‌صورت HTTPS در صورتی که در URL مشخص نشده باشد. --http-version=VERSION نسخهٔ HTTP مورد استفاده. [مقادیر ممکن: 1.0, 1.1, 2, 2-prior-knowledge, 3-prior-knowledge] --resolve=HOST:ADDRESS بازنویسی تحلیل نام DNS برای دامنه‌ای خاص به یک IP سفارشی. با تکرار این گزینه می‌توانید چندین دامنه را بازنویسی کنید. مثال: --resolve=example.com:127.0.0.1. --interface=NAME اتصال (bind) به یک رابط شبکه یا آدرس IP محلی. مثال: --interface=eth0 --interface=192.168.0.2. -4, --ipv4 تحلیل نام میزبان فقط به نشانی‌های ipv4. -6, --ipv6 تحلیل نام میزبان فقط به نشانی‌های ipv6. --unix-socket=FILE اتصال با استفاده از یک سوکت دامنهٔ یونیکس (Unix domain socket). مثال: xh :/index.html --unix-socket=/var/run/temp.sock..TP 4 -I, --ignore-stdin برای خواندن ورودی استاندارد (stdin) تلاش نکن. این گزینه رفتار پیش‌فرض مبنی بر خواندن بدنه درخواست از stdin در صورت تشخیص ورودی هدایت‌شده (redirected) را غیرفعال می‌کند. توصیه می‌شود هنگام استفاده از xh برای اهداف اسکریپت‌نویسی، این پرچم مشخص شود. برای اطلاعات بیشتر، به مراجعه کنید. --curl چاپ معادل دستور در قالب یک دستور curl. برای ترجمه معکوس، به مراجعه کنید. --curl-long استفاده از نسخه بلند پرچم‌های curl. --generate=KIND تولید تکمیل‌کننده‌های پوسته (shell completions) یا صفحات راهنما. مقادیر معتبر عبارتند از: complete-bash تولید تکمیل‌کننده برای bash complete-elvish تولید تکمیل‌کننده برای elvish complete-fish تولید تکمیل‌کننده برای fish complete-nushell تولید تکمیل‌کننده برای nushell complete-powershell تولید تکمیل‌کننده برای powershell complete-zsh تولید تکمیل‌کننده برای zsh man تولید صفحه راهنما در قالب roff man-markdown تولید صفحه راهنما در قالب markdown مثال: xh --generate=complete-bash > xh.bash. --help چاپ راهنما. -V, --version چاپ نسخه. وضعیت خروج (EXIT STATUS) 0 اجرای موفقیت‌آمیز برنامه. 1 خطای کاربرد، نحو (syntax) یا شبکه. 2 پایان مهلت زمانی درخواست (timeout). 3 تغییر مسیر غیرمنتظره HTTP 3xx. 4 خطای سمت کلاینت HTTP 4xx. 5 خطای سمت سرور HTTP 5xx. 6 تغییر مسیرهای بیش از حد (too many redirects). محیط (ENVIRONMENT) XH_CONFIG_DIR محل جستجو برای فایل config.json و داده‌های نشست‌های نام‌گذاری‌شده را مشخص می‌کند. مقدار پیش‌فرض در Linux/macOS برابر ~/.config/xh و در Windows برابر %APPDATA%\xh است. XH_HTTPIE_COMPAT_MODE حالت سازگاری با HTTPie را فعال می‌کند. تنها تفاوت فعلی این است که --check-status به‌طور پیش‌فرض فعال نیست. راهکار جایگزین به‌جای تنظیم این متغیر محیطی، تغییر نام فایل باینری اجرایی به http یا https است. REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE مسیر سفارشی بسته گواهی‌های CA (CA bundle) را تنظیم می‌کند. ALL_PROXY=[protocol://][:port] سرور پروکسی را برای همه درخواست‌ها تنظیم می‌کند (مگر اینکه برای پروتکلی خاص بازنویسی شده باشد). HTTP_PROXY=[protocol://][:port] سرور پروکسی مورد استفاده برای HTTP را مشخص می‌کند. HTTPS_PROXY=[protocol://][:port] سرور پروکسی مورد استفاده برای HTTPS را مشخص می‌کند. NO_PROXY فهرستی از میزبان‌های جداشده با کاما که باید سایر متغیرهای محیطی پروکسی برای آن‌ها نادیده گرفته شوند. "*" با همه نام‌های میزبان مطابقت دارد. NETRC مکان فایل .netrc. NO_COLOR رنگ‌آمیزی خروجی را غیرفعال می‌کند. ببینید RUST_LOG پیکربندی پیام‌های اشکال‌زدایی سطح پایین. ببینید فایل‌ها (FILES) ~/.config/xh/config.json فایل پیکربندی xh. تنها گزینه قابل‌پیکربندی "default_options" است که فهرستی از آرگومان‌های پیش‌فرض پوسته را مشخص می‌کند که به xh ارسال می‌شوند. مثال: { "default_options": ["--native-tls", "--style=solarized"] } ~/.netrc, ~/_netrc فایل اطلاعات ورود خودکار (auto-login). ~/.config/xh/sessions دایرکتوری داده‌های نشست (session) که بر اساس دامنه و شماره پورت دسته‌بندی شده‌اند..SH "مثال‌ها (EXAMPLES)" xh httpbin.org/json ارسال یک درخواست GET. xh httpbin.org/post name=ahmed age:=24 ارسال یک درخواست POST با بدنهٔ {"name": "ahmed", "age": 24}. xh get httpbin.org/json id==5 sort==true ارسال یک درخواست GET به http://httpbin.org/json?id=5&sort=true. xh get httpbin.org/json x-api-key:12345 ارسال یک درخواست GET به همراه سرآیندی به نام X-Api-Key با مقدار 12345. echo "[1, 2, 3]" | xh post httpbin.org/post ارسال یک درخواست POST با بدنه‌ای که از stdin خوانده می‌شود. xh put httpbin.org/put id:=49 age:=25 | less ارسال یک درخواست PUT و لوله‌کشی (pipe) نتیجه به less. xh -d httpbin.org/json -o res.json دانلود و ذخیره در res.json. xh httpbin.org/get user-agent:foobar برقراری یک درخواست با عامل کاربر (User-Agent) سفارشی. xhs example.com برقراری یک درخواست HTTPS به https://example.com. گزارش باگ‌ها (BUGS) بخش مسائل گیت‌هاب xh در همچنین ببینید (SEE ALSO) curl(1), http(1) مستندات برخط HTTPie در 0.26.2 2026-07-26 XH(1)