.TH "kitten-@-ls" "1" "Jul 30, 2026" "0.48.2" "kitten Manual"
.SH "نام (NAME)"
kitten-@-ls \- فهرست کردن پنجره‌ها، تب‌ها و سیستم‌های عامل ترمینال kitty
.SH "نحوه استفاده (USAGE)"
.SY "kitten @ ls "
.YS
.SH "توضیحات (DESCRIPTION)"
فهرست کردن پنجره‌ها. این فهرست در قالب یک درخت JSON بازگردانده می‌شود. بالاترین سطح، فهرستی از پنجره‌های سیستم‌عامل kitty است. هر پنجرهٔ سیستم‌عامل دارای یک شناسه (id) و فهرستی از زبانه‌ها (tabs) است. هر زبانه دارای شناسه، عنوان و فهرستی از پنجره‌ها است. هر پنجره دارای شناسه، عنوان، دایرکتوری کاری جاری، شناسه فرایند (PID)، خط فرمان و متغیرهای محیطی فرایند در حال اجرا در آن پنجره است. علاوه بر این، هنگام اجرای دستور درون یک پنجرهٔ kitty، آن پنجره با پارامتر is_self مشخص می‌شود.

می‌توانید از این معیارها برای انتخاب پنجره‌ها/زبانه‌ها جهت استفاده در سایر دستورات بهره ببرید.

می‌توانید پنجره‌ها/زبانه‌ها را در خروجی با استفاده از گزینه‌های
.B \-\-match
و
.B \-\-match\-tab
محدود کنید.
.SH "گزینه‌ها (OPTIONS)"
.TP
.BI "--all-env-vars" " [=no]"
نمایش تمام متغیرهای محیطی در خروجی، نه فقط متغیرهایی که تفاوت دارند.
.TP
.BI "--self" " [=no]"
فقط پنجره‌ای را که این دستور در آن اجرا می‌شود فهرست کند.
.TP
.BI "--output-format" " [=json]"
خروجی در قالب JSON یا قالب نشست (session) در kitty

انتخاب‌ها: json، session
.TP
.BI "--match, -m"
پنجره‌ای که باید مطابقت داده شود. مشخصات تطبیق به صورت field:query هستند؛ که field می‌تواند یکی از موارد زیر باشد: id، title، pid، cwd، cmdline، num، env، var، state، neighbor، session و recent. عبارت query عبارتی است که باید مطابقت داده شود. عبارت‌ها می‌توانند یک عدد یا یک عبارت باقاعده (regular expression) باشند، و می‌توان آن‌ها را با عملگرهای بولی ترکیب کرد.

مقدار ویژهٔ all با تمام پنجره‌ها مطابقت دارد.

برای فیلدهای عددی: id، pid، num و recent، عبارت به عنوان یک عدد تفسیر می‌شود، نه یک عبارت باقاعده. مقادیر منفی برای id از بالاترین شمارهٔ شناسه به سمت پایین مطابقت می‌یابند؛ به ویژه \-1 نشان‌دهندهٔ جدیدترین پنجرهٔ ایجادشده است.

فیلد num به موقعیت پنجره در زبانهٔ جاری اشاره دارد که از صفر شروع شده و در جهت عقربه‌های ساعت شمارش می‌شود (این ترتیب همان ترتیبی است که پنجره‌ها توسط دستور kitten @ ls گزارش می‌شوند).

شناسهٔ پنجرهٔ جاری از طریق متغیر محیطی
.B KITTY_WINDOW_ID
در دسترس است.

فیلد recent به پنجره‌های اخیراً فعال در زبانهٔ فعال فعلی اشاره دارد؛ به طوری که صفر پنجرهٔ فعال فعلی، یک پنجرهٔ فعال قبلی و به همین ترتیب است.

فیلد neighbor به همسایهٔ پنجرهٔ فعال در جهت مشخص‌شده اشاره دارد که می‌تواند یکی از موارد زیر باشد: left، right، top یا bottom.

فیلد session با پنجره‌هایی که در نشست (session) مشخص‌شده ایجاد شده‌اند مطابقت می‌یابد. از عبارت \(ha$ برای مطابقت با پنجره‌هایی که در هیچ نشستی ایجاد نشده‌اند، از . برای تطبیق با نشست فعال فعلی و از \(ti برای تطبیق با نشست فعال فعلی یا آخرین نشست فعال در زمانی که هیچ نشستی فعال نیست استفاده کنید.

هنگام استفاده از فیلد env برای تطبیق بر روی متغیرهای محیطی، می‌توانید فقط نام متغیر محیطی یا نام و مقدار را مشخص کنید؛ برای مثال env:MY_ENV_VAR=2.

به طور مشابه، فیلد var با متغیرهای کاربری تنظیم‌شده روی پنجره مطابقت دارد. می‌توانید مانند فیلد env، نام یا نام و مقدار را مشخص کنید.

فیلد state بر اساس وضعیت پنجره مطابقت می‌دهد. وضعیت‌های پشتیبانی‌شده عبارتند از: active، focused، needs_attention، parent_active، parent_focused، focused_os_window، self و overlay_parent. پنجره‌های فعال (active) پنجره‌هایی هستند که در زبانهٔ والد خود فعال هستند. تنها یک پنجرهٔ فوکوس‌شده (focused) وجود دارد و آن پنجره‌ای است که رویدادهای صفحه‌کلید به آن تحویل داده می‌شوند. اگر هیچ پنجره‌ای فوکوس نشده باشد، با آخرین پنجرهٔ فوکوس‌شده مطابقت داده می‌شود. مقدار focused_os_window با تمام پنجره‌ها در پنجرهٔ سیستم‌عامل دارای فوکوس فعلی مطابقت دارد. مقدار self با پنجره‌ای که دستور کنترل از راه دور در آن اجرا می‌شود مطابقت دارد. مقدار overlay_parent با پنجره‌ای که زیر پنجرهٔ self قرار دارد (هنگامی که پنجرهٔ self یک لایهٔ رویی یا overlay است) مطابقت می‌یابد.

توجه داشته باشید که می‌توانید از دستور kitten @ ls برای دریافت فهرستی از پنجره‌ها استفاده کنید.
.TP
.BI "--match-tab, -t"
زبانه‌ای که باید مطابقت داده شود. مشخصات تطبیق به صورت field:query هستند؛ که field می‌تواند یکی از موارد زیر باشد: id، index، title، window_id، window_title، pid، cwd، cmdline، env، var، state، session و recent. عبارت query عبارتی است که باید مطابقت داده شود. عبارت‌ها می‌توانند عدد یا یک عبارت باقاعده باشند، و می‌توان آن‌ها را با عملگرهای بولی ترکیب کرد.

مقدار ویژهٔ all با تمام زبانه‌ها مطابقت دارد.

برای فیلدهای عددی: id، index، window_id، pid و recent، عبارت به عنوان یک عدد تفسیر می‌شود، نه یک عبارت باقاعده. مقادیر منفی برای id/window_id از بالاترین شمارهٔ شناسه به سمت پایین مطابقت می‌یابند؛ به ویژه \-1 نشان‌دهندهٔ جدیدترین زبانه/پنجرهٔ ایجادشده است.

هنگام استفاده از title یا id، ابتدا به دنبال یک زبانهٔ منطبق جستجو می‌شود و در صورت پیدا نشدن، به دنبال یک پنجرهٔ منطبق گشته و زبانهٔ مربوط به آن پنجره استفاده می‌شود.

همچنین می‌توانید از window_id و window_title برای مطابقت با زبانه‌ای که حاوی پنجره با شناسه یا عنوان مشخص‌شده است استفاده کنید.

شمارهٔ index برای مطابقت با n-امین زبانه در پنجرهٔ سیستم‌عامل فعال فعلی استفاده می‌شود. شمارهٔ recent با زبانه‌های اخیراً فعال در پنجرهٔ سیستم‌عامل فعال فعلی مطابقت دارد؛ به طوری که صفر زبانهٔ فعال فعلی، یک زبانهٔ فعال قبلی و به همین ترتیب است.

فیلد session با زبانه‌هایی که در نشست مشخص‌شده ایجاد شده‌اند مطابقت می‌یابد. از عبارت \(ha$ برای مطابقت با زبانه‌هایی که در هیچ نشستی ایجاد نشده‌اند، از . برای تطبیق با نشست فعال فعلی و از \(ti برای تطبیق با نشست فعال فعلی یا آخرین نشست فعال در زمانی که هیچ نشستی فعال نیست استفاده کنید.

هنگام استفاده از فیلد env برای تطبیق بر روی متغیرهای محیطی، می‌توانید فقط نام متغیر محیطی یا نام و مقدار را مشخص کنید؛ برای مثال env:MY_ENV_VAR=2. زبانه‌هایی که حاوی هر پنجره‌ای با متغیرهای محیطی مشخص‌شده باشند مطابقت داده می‌شوند. به همین ترتیب، var با زبانه‌های حاوی هر پنجره با متغیر کاربری مشخص‌شده مطابقت دارد.

فیلد state بر اساس وضعیت زبانه مطابقت می‌دهد. وضعیت‌های پشتیبانی‌شده عبارتند از: active، focused، needs_attention، parent_active، parent_focused و focused_os_window. زبانه‌های فعال، زبانه‌هایی هستند که در پنجرهٔ سیستم‌عامل والد خود فعال هستند. تنها یک زبانهٔ فوکوس‌شده وجود دارد و آن زبانه‌ای است که رویدادهای صفحه‌کلید به آن تحویل داده می‌شوند. اگر هیچ زبانه‌ای فوکوس نشده باشد، با آخرین زبانهٔ فوکوس‌شده مطابقت داده می‌شود. مقدار focused_os_window با تمام زبانه‌ها در پنجرهٔ سیستم‌عامل دارای فوکوس فعلی مطابقت دارد.

توجه داشته باشید که می‌توانید از دستور kitten @ ls برای دریافت فهرستی از زبانه‌ها استفاده کنید.
.TP
.BI "--help, -h" " [=no]"
نمایش راهنمای این دستور
.SH "گزینه‌های عمومی (GLOBAL OPTIONS)"
.TP
.BI "--to"
آدرسی برای نمونهٔ kitty جهت کنترل. متناظر با آدرسی است که از طریق گزینهٔ
.B \-\-listen\-on
یا تنظیم
.B listen_on
در
.I kitty.conf
به نمونهٔ kitty داده شده است. در صورت مشخص نشدن، متغیر محیطی
.B KITTY_LISTEN_ON
بررسی می‌شود. اگر آن هم یافت نشود، پیام‌ها به ترمینال کنترل‌کنندهٔ این فرایند ارسال می‌شوند؛ یعنی فقط در صورتی کار خواهند کرد که این فرایند درون یک پنجرهٔ kitty اجرا شود.
.TP
.BI "--password"
رمز عبوری برای استفاده هنگام برقراری ارتباط با kitty. این کار باعث می‌شود kitty از کاربر برای انجام عمل مشخص‌شده اجازه بخواهد، مگر اینکه رمز عبور قبلاً پذیرفته شده باشد یا از قبل در
.I kitty.conf
پیکربندی شده باشد. برای استفاده از رمز عبور خالی، گزینهٔ
.B \-\-use\-password
را روی always تنظیم کنید.
.TP
.BI "--password-file" " [=rc\-pass]"
فایلی که رمز عبور از آن خوانده می‌شود. فاصله‌های خالی انتهایی نادیده گرفته می‌شوند. مسیرهای نسبی نسبت به دایرکتوری پیکربندی kitty حل می‌شوند. از \- برای خواندن از STDIN استفاده کنید. از fd:num برای خواندن از توصیف‌کنندهٔ فایل num استفاده کنید. در صورتی استفاده می‌شود که گزینه‌ای برای
.B \-\-password
ارائه نشده باشد. به طور پیش‌فرض وجود فایل
.I rc\-pass
در دایرکتوری پیکربندی kitty بررسی می‌شود.
.TP
.BI "--password-env" " [=KITTY_RC_PASSWORD]"
نام متغیر محیطی برای خواندن رمز عبور از آن. در صورتی استفاده می‌شود که گزینه‌ای برای
.B \-\-password\-file
ارائه نشده باشد. به طور پیش‌فرض متغیر محیطی
.B KITTY_RC_PASSWORD
بررسی می‌شود.
.TP
.BI "--use-password" " [=if\-available]"
اگر هیچ رمز عبوری در دسترس نباشد، kitty معمولاً دستور کنترل از راه دور را بدون رمز عبور ارسال می‌کند. از این گزینه می‌توان برای اجبار به استفادهٔ همیشگی یا عدم استفاده از رمز عبور ارائه‌شده استفاده کرد. اگر روی always تنظیم شود و هیچ رمز عبوری ارائه نشده باشد، از رمز عبور خالی استفاده می‌شود.

انتخاب‌ها: if-available، always، never