http(1) HTTPie Manual http(1)

http - کلاینت خط فرمانی مدرن و کاربرپسند HTTP برای عصر API

http [METHOD] URL [REQUEST_ITEM ...]

HTTPie: کلاینت خط فرمانی مدرن و کاربرپسند HTTP برای عصر API. https://httpie.io

این آرگومان‌ها پس از گزینه‌ها و به ترتیبی که در اینجا فهرست شده‌اند می‌آیند. تنها وارد کردن URL الزامی است.

متد HTTP مورد استفاده برای درخواست (GET, POST, PUT, DELETE, ...).

این آرگومان می‌تواند حذف شود که در این صورت اگر داده‌ای برای ارسال وجود داشته باشد، HTTPie از متد POST استفاده خواهد کرد، در غیر این صورت از GET:


$ http example.org # => GET
$ http example.org hello=world # => POST

نشانی اینترنتی (URL) درخواست. اگر طرحواره در نشانی قید نشود، پیش‌فرض 'http://' است. (می‌توانید این رفتار را تغییر دهید با: --default-scheme=http/https)

همچنین می‌توانید از شیوه خلاصه برای localhost استفاده کنید:


$ http :3000 # => http://localhost:3000
$ http :/foo # => http://localhost/foo

جفت‌های کلید-مقدار اختیاری برای گنجاندن در درخواست. جداکننده استفاده‌شده نوع آن را تعیین می‌کند:

':' هدرهای HTTP:


Referer:https://httpie.io Cookie:foo=bar User-Agent:bacon/1.0

'==' پارامترهای URL برای الحاق به URI درخواست:


search==httpie

'=' فیلدهای داده برای سریال‌سازی در قالب یک شیء JSON (با --json, -j)
یا داده‌های فرم (با --form, -f):


name=HTTPie language=Python description='CLI HTTP client'

':=' فیلدهای داده غیراز نوع رشته در JSON (تنها با --json, -j):


awesome:=true amount:=42 colors:='["red", "green", "blue"]'

'@' فیلدهای فایل فرم (تنها با --form یا --multipart):


cv@~/Documents/CV.pdf
cv@'~/Documents/CV.pdf;type=application/pdf'

'=@' یک فیلد داده مانند '='، اما مسیر فایلی را دریافت کرده و محتوای آن را جاسازی می‌کند:


essay=@Documents/essay.txt

':=@' یک فیلد داده خام JSON مانند ':='، اما مسیر فایلی را دریافت کرده و محتوای آن را جاسازی می‌کند:


package:=@./package.json

می‌توانید از یک بک‌اسلش برای اسکیپ کردن جداکننده‌های تداخل‌دار در نام فیلد استفاده کنید:


field-name-with\:colon=value

(پیش‌فرض) آیتم‌های داده از خط فرمان به عنوان یک شیء JSON سریال‌سازی می‌شوند. هدرهای Content-Type و Accept (در صورت عدم تعیین) روی application/json تنظیم می‌شوند.

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

هدر Content-Type (در صورت عدم تعیین) روی application/x-www-form-urlencoded تنظیم می‌شود. وجود هرگونه فیلد فایل منجر به ایجاد یک درخواست multipart/form-data می‌گردد.

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

تعیین رشته مرزبندی (boundary) سفارشی برای درخواست‌های multipart/form-data. تنها به همراه --form اثر دارد.

این گزینه امکان می‌دهد داده‌های خام درخواست را بدون پردازش اضافی ارسال کنید (برخلاف ساختار دستوری اقلام درخواست ساختاریافته):


$ http --raw='data' pie.dev/post

می‌توانید با هدایت داده‌ها از طریق ورودی استاندارد (stdin) به همین نتیجه برسید:


$ echo data | http pie.dev/post

یا تنظیم کنید که HTTPie داده‌های خام را از یک فایل بارگذاری کند:


$ http pie.dev/post @data.txt

فشرده‌سازی (کدگذاری) محتوا با الگوریتم Deflate. هدر Content-Encoding روی deflate تنظیم می‌شود.

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

پردازش خروجی را کنترل می‌کند. مقدار می‌تواند "none" برای زیباسازی نکردن خروجی (پیش‌فرض هنگام تغییرمسیر خروجی)، "all" برای اعمال هم‌زمان رنگ‌ها و قالب‌بندی (پیش‌فرض برای خروجی ترمینال)، "colors" یا "format" باشد.

سبک رنگ‌آمیزی خروجی (پیش‌فرض "auto" است). می‌تواند یکی از موارد زیر باشد:


auto, pie, pie-dark, pie-light, solarized

برای مشاهده تمام سبک‌های موجود در سیستم، دستور زیر را امتحان کنید:

$ http --style

سبک "auto" از سبک‌های رنگ ANSI ترمینال شما پیروی می‌کند. برای اینکه سبک‌های غیر-auto به درستی کار کنند، لطفاً مطمئن شوید که متغیر محیطی $TERM روی "xterm-256color" یا مشابه آن تنظیم شده باشد (مثلاً از طریق `export TERM=xterm-256color' در فایل ~/.bashrc شما).

همه مرتب‌سازی‌ها را در هنگام قالب‌بندی خروجی غیرفعال می‌کند. این یک میانبر است برای:


--format-options=headers.sort:false,json.sort_keys:false

تمامی گزینه‌های مرتب‌سازی را در هنگام قالب‌بندی خروجی مجدداً فعال می‌کند. میانبری است برای:


--format-options=headers.sort:true,json.sort_keys:true

کدگذاری پاسخ را جهت نمایش در ترمینال بازنویسی می‌کند، مثلاً:


--response-charset=utf8
--response-charset=big5

نوع MIME پاسخ را برای رنگ‌آمیزی و قالب‌بندی در ترمینال بازنویسی می‌کند، مثلاً:


--response-mime=application/json
--response-mime=text/xml

قالب‌بندی خروجی را کنترل می‌کند. تنها زمانی مرتبط است که قالب‌بندی از طریق گزینه --pretty=all یا --pretty=format (صریح یا ضمنی) فعال شده باشد. گزینه‌های پیش‌فرض عبارتند از:


headers.sort:true
json.format:true
json.indent:4
json.sort_keys:true
xml.format:true
xml.indent:2

می‌توانید چندین بار از این گزینه استفاده کرده یا چندین گزینه را هم‌زمان با کاما جدا کنید. به عنوان مثال، این دستور تنظیمات را برای غیرفعال کردن مرتب‌سازی کلیدهای JSON و تنظیم اندازه تورفتگی به ۲ تغییر می‌دهد:


--format-options json.sort_keys:false,json.indent:2

این تنظیم معمولاً درون فایل کانفیگ قرار می‌گیرد.

رشته‌ای که مشخص می‌کند خروجی باید شامل چه مواردی باشد:


'H' هدرهای درخواست
'B' بدنه درخواست
'h' هدرهای پاسخ
'b' بدنه پاسخ
'm' متادیتای پاسخ

رفتار پیش‌فرض 'hb' است (یعنی هدرها و بدنه پاسخ چاپ می‌شوند)، البته در صورتی که خروجی استاندارد تغییر مسیر داده نشده باشد. اگر خروجی به برنامه‌ای دیگر پایپ شود یا درون یک فایل ذخیره گردد، به طور پیش‌فرض فقط بدنه پاسخ چاپ می‌شود.

فقط هدرهای پاسخ را چاپ می‌کند. میانبری برای --print=h.

فقط متادیتای پاسخ را چاپ می‌کند. میانبری برای --print=m.

فقط بدنه پاسخ را چاپ می‌کند. میانبری برای --print=b.

خروجی با جزئیات کامل. برای سطح یک (با یک بار درج `-v`/`--verbose`)، کل درخواست و همچنین پاسخ را چاپ می‌کند. همچنین تمامی درخواست‌ها و پاسخ‌های واسطه‌ای (مانند ریدایرکت‌ها) را چاپ می‌نماید. برای سطح دو و بالاتر، این موارد و همچنین متادیتای پاسخ را نیز چاپ می‌کند.

سطح یک میانبری است برای: --all --print=BHbh سطح دو میانبری است برای: --all --print=BHbhm

به طور پیش‌فرض، فقط درخواست/پاسخ نهایی نشان داده می‌شود. از این پرچم برای نمایش هرگونه درخواست/پاسخ واسطه‌ای نیز استفاده کنید. درخواست‌های واسطه‌ای شامل تغییرمسیرهای دنبال‌شده (با --follow)، نخستین درخواست غیرمجاز هنگام استفاده از احراز هویت دایجِست (--auth=digest) و موارد مشابه است.

همواره بدنه پاسخ را سطر به سطر استریم می‌کند، یعنی رفتاری شبیه به `tail -f'.

بدون --stream و در صورت فعال بودن --pretty (چه صریح و چه ضمنی)، HTTPie کل پاسخ را پیش از خروجی دادن داده‌های پردازش‌شده دریافت می‌کند.

این گزینه را زمانی تنظیم کنید که می‌خواهید پاسخی طولانی‌مدت و پیوسته را به شکلی خوانا و زیبا نمایش دهید، مانند استریم‌های API توییتر.

همچنین بدون --pretty نیز کاربرد دارد: تضمین می‌کند که خروجی با دفعات بیشتر و در تکه‌های کوچکتری تخلیه (flush) شود.

ذخیره خروجی در FILE به جای خروجی استاندارد (stdout). اگر --download نیز تنظیم شده باشد، تنها بدنه پاسخ در FILE ذخیره می‌شود. سایر بخش‌های تبادل HTTP در خروجی خطا (stderr) چاپ می‌شوند.

بدنه پاسخ را در خروجی استاندارد چاپ نمی‌کند، بلکه آن را دانلود کرده و در یک فایل ذخیره می‌نماید. نام فایل حدس زده می‌شود مگر اینکه با --output [filename] مشخص گردد. این عمل مشابه رفتار پیش‌فرض wget است.

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

هیچ پیامی در stdout یا stderr چاپ نمی‌کند، به جز خطاها و هشدارها در صورتی که این گزینه یک بار مشخص شده باشد. مشخص کردن آن برای دو بار، هشدارها را نیز غیرفعال می‌کند. اگر --output مشخص شده باشد، خروجی استاندارد همچنان تغییر مسیر می‌یابد. این پرچم تأثیری بر روند دانلود به جز عدم چاپ در ترمینال ندارد.

ایجاد یا استفاده مجدد و به‌روزرسانی یک نشست. درون یک نشست، هدرهای سفارشی، اطلاعات احراز هویت و همچنین تمامی کوکی‌های ارسالی سرور میان درخواست‌ها حفظ می‌شوند.

فایل‌های نشست در مسیر زیر ذخیره می‌شوند:


[HTTPIE_CONFIG_DIR]/<HOST>/<SESSION_NAME>.json

برای مشاهده دایرکتوری پیش‌فرض HTTPIE_CONFIG_DIR صفحه زیر را ببینید:


https://httpie.io/docs/cli/config-file-directory

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

برای سازوکارهای احراز هویت مبتنی بر نام کاربری/رمز عبور (مانند احراز هویت پایه basic یا digest) اگر تنها نام کاربری ارائه شود (-a username)، HTTPie رمز عبور را به صورت تعاملی می‌پرسد.

سازوکار احراز هویت مورد استفاده. مقدار پیش‌فرض "basic" است.

"basic": احراز هویت پایه Basic HTTP

"digest": احراز هویت Digest HTTP

"bearer": احراز هویت Bearer HTTP

برای مشاهده تمام انواع احراز هویت موجود در سیستم (شامل موارد نصب‌شده از طریق افزونه‌ها)، دستور زیر را اجرا کنید:

$ http --auth-type

نادیده گرفتن اطلاعات هویتی و اعتبارنامه‌ها از فایل .netrc.

درخواست را می‌سازد و چاپ می‌کند اما آن را ارسال نمی‌کند.

رشته‌ای برای نگاشت پروتکل به نشانی URL پروکسی (مانند http:http://foo.bar:3128). می‌توانید چندین پروکسی با پروتکل‌های گوناگون مشخص کنید. متغیرهای محیطی $ALL_PROXY ،$HTTP_PROXY و $HTTPS_proxy نیز پشتیبانی می‌شوند.

دنبال کردن تغییر مسیرهای 30x Location.

به طور پیش‌فرض، درخواست‌ها حداکثر تا ۳۰ تغییر مسیر دارند (همراه با --follow عمل می‌کند).

حداکثر تعداد هدرهای پاسخ برای خواندن پیش از صرف‌نظر کردن (پیش‌فرض ۰، به معنی نامحدود).

مهلت زمانی (تایم‌اوت) اتصال درخواست بر حسب ثانیه. مقدار پیش‌فرض ۰ است، یعنی هیچ محدودیتی برای تایم‌اوت وجود ندارد. این محدودیت زمانی برای کل دانلود پاسخ نیست؛ بلکه اگر سرور به مدت ثانیه‌های تعیین‌شده پاسخی ارسال نکند، خطا گزارش می‌شود (دقیق‌تر بگوییم، اگر به مدت این ثانیه‌ها هیچ بایتی در سوکت دریافت نشود).

به طور پیش‌فرض، HTTPie هنگامی که خطای شبکه یا خطای مهلک دیگری رخ ندهد با کد ۰ خارج می‌شود. این فلگ به HTTPie دستور می‌دهد تا کد وضعیت HTTP را نیز بررسی کرده و در صورت وجود خطا در کد وضعیت، با خطا خارج شود.

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

دور زدن ادغام قطعات نقطه‌ای (/../ یا /./) در URL.

فعال‌سازی استریمینگ از طریق کدگذاری انتقال تکه‌ای (chunked transfer encoding). هدر Transfer-Encoding روی chunked تنظیم می‌شود.

تنظیم روی "no" (یا "false") برای نادیده گرفتن بررسی گواهی SSL هاست. پیش‌فرض "yes" (یا "true") است. همچنین می‌توانید مسیر فایل CA_BUNDLE را برای گواهی‌های خصوصی ارسال کنید. (یا متغیر محیطی REQUESTS_CA_BUNDLE را تنظیم نمایید).

نسخه پروتکل مورد نظر برای استفاده. پیش‌فرض SSL v2.3 خواهد بود که بالاترین پروتکل مورد پشتیبانی سرور و نصب OpenSSL شما را مذاکره می‌کند. پروتکل‌های موجود ممکن است بسته به نصب OpenSSL متفاوت باشند (در اینجا فقط پروتکل‌های پشتیبانی‌شده نشان داده شده‌اند).

رشته‌ای با قالب فهرست رمزهای OpenSSL.

برای مشاهده فهرست پیش‌فرض رمزها در سیستم خود، راهنمای `http --help` را ببینید.

می‌توانید یک گواهی محلی برای استفاده به عنوان گواهی SSL کلاینت تعیین کنید. این فایل ممکن است هم شامل کلید خصوصی و هم گواهی باشد، یا می‌توانید --cert-key را جداگانه مشخص کنید.

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

عبارت عبور (passphrase) کلید خصوصی داده‌شده. تنها در صورتی لازم است که --cert-key داده شده باشد و فایل کلید نیازمند عبارت عبور باشد. در صورت مشخص نشدن، به صورت تعاملی درخواست خواهد شد.

تلاش نکردن برای خواندن از stdin.

نمایش این پیام راهنما و خروج.

نمایش راهنمای کامل.

نمایش نسخه و خروج.

در صورت بروز استثنا (exception)، ردگیری کامل پشته خطا را چاپ می‌کند.

طرحواره پیش‌فرض برای استفاده در صورتی که در نشانی URL مشخص نشده باشد.

در صورت بروز استثنا، ردگیری پشته و همچنین اطلاعات دیگر مفید برای دیباگ کردن HTTPie و گزارش باگ‌ها را چاپ می‌کند.

به ازای هر گزینه --OPTION یک گزینه --no-OPTION نیز وجود دارد که مقدار OPTION را به حالت پیش‌فرض بازمی‌گرداند.

پیشنهادات و گزارش باگ‌ها مورد استقبال قرار می‌گیرند: https://github.com/httpie/cli/issues

2024-07-10 HTTPie 3.2.4