رابط خط فرمان اندروید (Android CLI) یک رابط خط فرمان است که به شما امکان میدهد با استفاده از هر ابزاری که انتخاب میکنید، به راحتی و با کارایی بیشتری برای اندروید برنامه بسازید. این رابط، شایستگیهای اصلی توسعه را برای گردشهای کاری مبتنی بر عامل (agent-first) استانداردسازی میکند و نقطه ورود به ابزارها، مهارتها و دانش رسمی مورد نیاز برای توسعه مؤثرتر را فراهم میکند. همچنین میتواند CI، نگهداری و هرگونه اتوماسیون اسکریپتشده دیگر را برای ماهیت توزیعشده فزاینده توسعه اندروید سادهسازی کند.
برای مثال، یک عامل یا اسکریپت میتواند از رابط خط فرمان (CLI) برای خودکارسازی راهاندازی محیط، ایجاد پروژههای جدید از قالبها و مدیریت دستگاههای مجازی مستقیماً از ترمینال شما استفاده کند. همچنین به عاملهای شما امکان دسترسی به مهارتهای اندروید و پایگاه دانش تخصصی اندروید را میدهد تا اطمینان حاصل شود که پروژههای شما از الگوها و بهترین شیوههای توصیهشده اندروید استفاده میکنند.
نصب رابط خط فرمان اندروید (CLI)
برای نصب رابط خط فرمان اندروید (Android CLI)، مراحل زیر را دنبال کنید:
برای اطمینان از اینکه از آخرین نسخه استفاده میکنید، رابط خط فرمان اندروید (Android CLI) را بهروزرسانی کنید:
android update
برای بررسی اینکه آیا رابط خط فرمان اندروید (Android CLI) از قبل روی دستگاه شما نصب شده است یا خیر، which android یا command -v android را اجرا کنید: اگر مسیری را برگرداند، پس نصب شده است.
برای نمایندگان تنظیم کنید
برای کمک به اپراتورها در درک و استفاده از Android CLI، init برای نصب مهارت android-cli اجرا کنید:
android init
مشکلات شناخته شده
- دستور
android emulatorبرای ویندوز در حال حاضر غیرفعال است.
گزینههای جهانی
اینها پرچمهای اختیاری هستند که میتوانید با سایر دستورات CLI اندروید از آنها استفاده کنید.
-h, --help
کاربرد: android <command> -h
توضیحات: نمایش راهنمای ابزار یا دستور خاص مورد نظر.
مثالها:
-
android -h -
android create -h
--sdk
کاربرد: android --sdk=<path-to-sdk> <command>
توضیحات: مسیر SDK اندروید که میخواهید برای دستور زیر استفاده کنید. میتوانید از تنظیم --sdk برای لغو موقت SDK پیشفرض اندروید استفاده کنید، به جای اینکه هر بار که میخواهید تغییر دهید، متغیرهای محیطی سراسری خود را تغییر دهید. برای بررسی اینکه از کدام SDK اندروید به طور پیشفرض استفاده میکنید، android info اجرا کنید.
مثال: android --sdk=<path/to/sdk> sdk list
دستورات
این بخش تمام دستورات رابط خط فرمان اندروید (Android CLI) را فهرست کرده و عملکرد آنها را شرح میدهد. قبل از همه این دستورات باید از android استفاده شود، برای مثال android create ، android run و غیره. اصلاحکنندههای اختیاری در داخل براکت [] قرار میگیرند و آرگومانهای اجباری در داخل براکت قرار نمیگیرند.
create
کاربرد: android create [--dry-run] [--verbose] [--name=<application-name>] [--output=<dest-path>] [<template-name>]
توضیحات: یک پروژه جدید را از یک قالب مقداردهی اولیه کنید. برای دیدن گزینههای قالب، android create -h اجرا کنید.
آرگومانها (اجباری):
-
-o, --output- مسیر دایرکتوری پروژه مقصد.
گزینهها:
-
--dry-run- کل فرآیند ایجاد پروژه را بدون ذخیره هیچ فایلی شبیهسازی میکند. برای مثال، میتوانید قبل از اعمال یک الگو، یک اجرای آزمایشی انجام دهید تا ببینید الگوهای مختلف چه عملکردی دارند. -
--verbose- خروجی verbose را فعال میکند، از جمله اطلاعاتی مانند اینکه کدام فایلها از قالب کپی میشوند. -
--name=<application-name>- نام دایرکتوری پروژه. در صورت حذف، از دایرکتوری خروجی استفاده میشود. -
<template-name>- نام قالبی که قرار است پروژه جدید از روی آن ایجاد شود. در صورت حذف،empty-activity-agp-9استفاده میشود.
مثال: android create --dry-run --verbose empty-activity-agp-9
create list
کاربرد: android create list
توضیحات: فهرستی از تمام قالبهای موجود برای ایجاد یک پروژه جدید.
describe
کاربرد: android describe [--project_dir=<project-directory>]
شرح: یک پروژه اندروید را برای تولید فرادادههای توصیفی تجزیه و تحلیل میکند. این دستور مسیرهای فایلهای JSON را که جزئیات ساختار پروژه، از جمله اهداف ساخت و مکانهای مصنوعات خروجی مربوطه (به عنوان مثال، فایلهای APK) را شرح میدهند، شناسایی و خروجی میدهد. این اطلاعات به ابزارها و دستورات دیگر امکان میدهد تا مصنوعات ساخت را به طور موثر پیدا کنند.
گزینهها:
-
--project_dir- دایرکتوری پروژه برای توصیف. در صورت حذف، دایرکتوری فعلی استفاده میشود.
مثال: android describe --project_dir=/path/to/your/project
docs
طریقه استفاده:
-
android docs search <query> -
android docs fetch <kb-url>
شرح: دستور android docs یک فرآیند دو مرحلهای برای دسترسی مستقیم به پایگاه دانش اندروید از طریق رابط خط فرمان (CLI) است. ابتدا، با استفاده از دستور search ، مستندات مربوط به درخواست خود را جستجو کنید. نتایج جستجو شامل URL های ویژهای است که با kb:// شروع میشوند، که میتوانید از آنها با دستور fetch برای خروجی دستورات مستندات به ترمینال استفاده کنید.
مثالها:
-
android docs search 'How do I improve my app performance?' -
android docs fetch kb://android/topic/performance/overview
emulator create
کاربرد: android emulator create [--list-profiles] [--profile=<profile-name>]
توضیحات: ایجاد یک دستگاه مجازی
گزینهها:
-
--list-profiles- فهرست پروفایلهای دستگاهی که میتوانند برای ایجاد یک دستگاه استفاده شوند. -
--profile=<profile-name>- یک دستگاه با مشخصات مشخص شده ایجاد کنید. اگر این مورد حذف شود، مشخصاتmedium_phoneایجاد خواهد شد.
emulator list
کاربرد: android emulator list
توضیحات: فهرست کردن دستگاههای مجازی موجود.
emulator start
کاربرد: android emulator start <device-name>
توضیحات: دستگاه مجازی مشخص شده را راه اندازی کنید.
آرگومانها (اجباری):
-
<device-name>- نام دستگاهی که قرار است شروع شود (برای مثال،medium_phone).android emulator listبرای دیدن دستگاههای موجود استفاده کنید.
مثال: android emulator start medium_phone
emulator stop
کاربرد: android emulator stop <device-serial-number>
توضیحات: دستگاه مجازی مشخص شده را متوقف کنید.
آرگومانها (اجباری):
-
<device-serial-number>- شماره سریال دستگاهی که قرار است متوقف شود.
مثال: android emulator stop emulator-5554
info
کاربرد: android info
توضیحات: مسیر SDK پیشفرض اندروید مورد استفاده را نمایش میدهد. برای تغییر SDK اندروید مورد استفاده، از --sdk استفاده کنید.
init
کاربرد: android init
توضیحات: با نصب مهارت android-cli ، محیط خود را برای عاملها تنظیم کنید.
layout
کاربرد: android layout [--pretty] [--output] [--diff]
توضیحات: طرحبندی رابط کاربری (UI layout) برنامهی فعال اندروید (که از طریق یک دستگاه فیزیکی یا شبیهساز متصل شده است) را با فرمت JSON برمیگرداند.
گزینهها:
-
-p, --pretty- خروجی JSON را با تورفتگی و پرش به خط جدید برای خوانایی بیشتر توسط انسان قالببندی میکند. -
-o, --output- محل ذخیره درخت طرحبندی را مشخص میکند. در صورت حذف، JSON مستقیماً در stdout چاپ میشود. -
-d, --diff- به جای نمایش کامل درخت طرحبندی، فهرستی از تنها عناصر طرحبندی که از آخرین اسنپشات داخلی گرفته شده (آخرین باری که طرحبندی اجرا شد) تغییر کردهاند را برمیگرداند.
مثال: : android layout --output=./hierarchy.json
skills add
مهارتهای اندروید، دستورالعملهای ویژهای هستند که برای کمک به عاملها در درک و اجرای بهتر الگوهای خاصی که از بهترین شیوهها و راهنماییها در توسعه اندروید پیروی میکنند، طراحی شدهاند. برای کسب اطلاعات بیشتر، به مقدمهای بر مهارتهای اندروید مراجعه کنید.
کاربرد: android skills add [--all] [--agent=<agent-name>] [--skill=<skill-name>]
توضیحات: مهارتهای اندروید را برای همه عاملهای شناساییشده در دایرکتوریهای مهارتها نصب کنید. اگر هیچ دایرکتوری عامل موجود ندارید و عاملهای خاصی را مشخص نکردهاید، مهارتها برای Gemini و Antigravity در ~/.gemini/antigravity/skills نصب خواهند شد.
گزینهها:
-
--all- تمام مهارتهای اندروید را یکجا اضافه میکند. اگر حذف شود (و--skillمشخص نشود)، فقط مهارتandroid-cliنصب خواهد شد. -
--agent- فهرستی از عاملهایی که با کاما از هم جدا شدهاند تا مهارت برای آنها نصب شود. در صورت حذف، مهارت برای همه عاملهای شناسایی شده نصب خواهد شد. -
--skill- نام مهارتی که میخواهید نصب کنید. اگر حذف شود (و--allمشخص نشده باشد)، فقط مهارتandroid-cliنصب خواهد شد.
مثال: android skills add --agent='gemini' edge-to-edge
skills find
کاربرد: android skills find <string>
توضیحات: مهارتهایی را پیدا کنید که با یک رشتهی داده شده مطابقت دارند.
آرگومانها (اجباری):
-
string- رشتهای که با شرح مهارت مطابقت دارد.
مثال: android skills find 'performance'
skills list
کاربرد: android skills list [--long]
شرح: مهارتهای موجود را فهرست کنید.
گزینهها:
-
--long- اطلاعات اضافی برای هر مهارت، از جمله شرح مهارت و اینکه برای کدام ایجنتها از قبل نصب شده است، را نمایش میدهد.
skills remove
کاربرد: android skills remove [--agent] --skill=<skill-name>
شرح: حذف یک مهارت. اگر ماموران خاصی را مشخص نکنید، آن مهارت برای همه ماموران حذف خواهد شد.
آرگومانها (اجباری):
-
--skill- نام مهارتی که باید حذف شود.
گزینهها:
-
--agent- فهرستی از عاملها که با کاما از هم جدا شدهاند تا مهارت از آنها حذف شود. در صورت حذف، مهارت برای همه عاملها حذف خواهد شد.
مثال: android skills remove --agent='gemini' --skill=edge-to-edge
screen capture
کاربرد: android screen capture [--output] [--annotate]
توضیحات: از دستگاه متصل شده اسکرین شات میگیرد.
گزینهها:
-
-o, --output- محل ذخیره تصویر صفحه را مشخص میکند. در صورت حذف، دادههای خام PNG مستقیماً در stdout چاپ میشوند. -
-a, --annotate- کادرهای محصورکننده برچسبگذاریشده را دور تمام عناصر رابط کاربری شناساییشده روی تصویر رسم میکند تا با دستورresolveاستفاده شود.
مثال: android screen capture --output=ui.png
screen resolve
کاربرد: android screen resolve --screenshot=<path> --string=<string>
توضیحات: برچسبهای بصری را از یک اسکرینشات حاشیهنویسیشده که با استفاده از screen capture گرفته شده است، به مختصات واقعی صفحه (x، y) تبدیل میکند. برای اسکریپتنویسی کلیکها روی عناصر بدون نیاز به محاسبه دستی موقعیت آنها مفید است.
پرچمها:
-
--screenshot- مسیر اسکرینشات حاشیهنویسی شده. -
--string- رشتهای که حداقل شامل یک placeholder مربوط به برچسب عنصر رابط کاربری با فرمت#<number>است. قسمت#<number>با مختصات صفحه نمایش جایگزین میشود.
مثال:
اگر برچسب ۵ در مختصات (۵۰۰، ۱۰۰۰) باشد، آنگاه دستور
android screen resolve --screenshot=ui.png --string="input tap #5"
خروجی را برمیگرداند
input tap 500 1000
sdk install
طریقه استفاده: android sdk install <package[@version]> [--beta] [--canary] [--force]
توضیحات: بسته(های) SDK مشخص شده را نصب کنید.
آرگومانها (اجباری):
-
package[@version]- فهرستی از بستههایی که باید نصب شوند و با فاصله از هم جدا شدهاند. اگر نسخهای مشخص نشده باشد، آخرین نسخه بسته در کانال (بهطور پیشفرض کانال پایدار) نصب میشود.
گزینهها:
-
--beta- بستههای بتا را اضافه کنید. -
--canary- شامل بستههای قناری. -
--force- مجبور کردن به بازگشت به نسخه قدیمیتر.
مثالها:
-
android sdk install platforms/android-34 build-tools/34.0.0- آخرین نسخههای بستههای Android SDK Platform 34 و SDK Built Tools 34.0.0 را از کانال پایدار نصب کنید. -
android sdk install platforms/android-34@2- نسخه ۲ از بسته Android SDK Platform 34 را نصب کنید. -
android sdk install --canary system-images/android-35/google_apis/x86_6- آخرین نسخه از تصویر سیستم اندروید ۳۵ را از کانال قناری نصب کنید. -
android sdk install --force platforms/android-33@1- بازگشت به نسخه ۱ پکیج Android SDK Platform 33 از کانال پایدار.
sdk list
کاربرد: android sdk list <package-pattern>
توضیحات: فهرست بستههای SDK نصبشده و موجود را نمایش دهید.
آرگومانها (اجباری):
-
<package-pattern>- بستهها را بر اساس الگو فیلتر میکند. از عبارات منظم پشتیبانی میکند.
گزینهها:
-
--all- نمایش تمام بستههای نصب شده و موجود. -
--all-versions- نمایش تمام نسخههای هر بسته. -
--beta- بستههای بتا را اضافه کنید. -
--canary- شامل بستههای قناری.
sdk remove
کاربرد: android sdk remove <package-name>
توضیحات: حذف یک بسته از SDK.
آرگومانها (اجباری):
-
<package-name>- نام بستهای که قرار است حذف شود.
مثال: android sdk remove build-tools/36.1.0
run
کاربرد: android run [--debug] [--activity=<activity-name>] [--device=<serial-number>] [--type=<param>] --apks=<apk-paths>
توضیحات: یک برنامه اندروید را روی یک دستگاه متصل یا شبیهساز مستقر کنید. این برنامه هیچ مرحله ساختی انجام نمیدهد؛ شما باید مسیر (مسیرهای) فایلهای APK که میخواهید نصب کنید را ارائه دهید.
آرگومانها (اجباری):
-
--apks- فهرستی از مسیر(های) فایلهای APK که میخواهید نصب کنید و با کاما از هم جدا شدهاند. این مسیر نسبت به مکانی که در حال حاضر در سیستم فایل قرار دارید، تعیین میشود.
گزینهها:
-
--activity- نام فعالیتی که پس از نصب APK اجرا میشود. اگر چندین فعالیت وجود دارد، باید ابتدا یک فعالیت را برای اجرا مشخص کنید. -
--debug- برنامه را در حالت اشکالزدایی مستقر میکند. پس از اجرای برنامه در حالت اشکالزدایی، برای شروع اشکالزدایی باید اشکالزدای خود را از یک IDE مانند اندروید استودیو یا یک ابزار خط فرمان متصل کنید . -
--device- شماره سریال دستگاه هدف یا شبیهساز. فقط در صورت اتصال چندین دستگاه مورد نیاز است. برای یافتن شماره سریال دستگاه، دستورadb devicesرا اجرا کنید. -
--type- نوع کامپوننتی که قرار است شروع شود. اگر میخواهید به جای یک فعالیت رابط کاربری، یک سرویس پسزمینه را مستقیماً شروع کنید، از این استفاده کنید. انواع پشتیبانی شده:-
ACTIVITY -
WATCH_FACE -
TILE -
COMPLICATION -
DECLARATIVE_WATCH_FACE
-
مثالها:
-
android run --apks=app/build/outputs/apk/debug/app-debug.apk- یک فایل APK واحد را روی دستگاه پیشفرض مستقر میکند. -
android run --apks=base.apk,density-hdpi.apk,lang-en.apk- چندین APK را روی دستگاه پیشفرض مستقر میکند. -
android run --apks=app-debug.apk --type=SERVICE --activity=.sync.DataSyncService- تست یک سرویس بدون اکتیویتی. -
android run --apks=app-debug.apk --device=emulator-5554- فایل APK را روی یک دستگاه خاص مستقر میکند.
sdk update
کاربرد: android sdk update [--beta] [--canary] [<package-name>]
توضیحات: یک یا همه بستهها را به آخرین نسخه در کانال (به طور پیشفرض کانال پایدار) بهروزرسانی کنید. اگر بستهای را مشخص نکنید، همه بستهها بهروزرسانی خواهند شد.
گزینهها:
-
<package-name>- نام بستهای که قرار است بهروزرسانی شود. -
--beta- بستههای بتا را اضافه کنید. -
--canary- شامل بستههای قناری. -
--force- مجبور کردن به بازگشت به نسخه قدیمیتر.
مثالها:
-
android sdk update- بهروزرسانیها را برای همه چیز در SDK خود بررسی و نصب کنید. -
android sdk update build-tools/34.0.0- بسته Android SDK Build Tools 34.0.0 را به آخرین نسخه در کانال پایدار بهروزرسانی کنید. -
android sdk update --canary platforms/android-35- بسته Android SDK Platforms 35 را به آخرین نسخه در کانال canary بهروزرسانی کنید.
update
کاربرد: android update
توضیحات: رابط خط فرمان اندروید (CLI) را بهروزرسانی کنید.
-V, --version
توضیحات: نسخه فعلی رابط خط فرمان اندروید (Android CLI) را نمایش میدهد.