نظرة عامة على واجهة سطر الأوامر في Android

‫Android CLI هي واجهة سطر أوامر تتيح لك إنشاء تطبيقات لنظام التشغيل Android بسهولة وفعالية أكبر باستخدام أي أداة تختارها. وهي توحّد كفاءات التطوير الأساسية لسير العمل الذي يركّز على الوكلاء، ما يوفّر نقطة دخول إلى الأدوات والمهارات والمعارف الرسمية التي تحتاج إليها للتطوير بفعالية أكبر. يمكنها أيضًا تبسيط التكامل المستمر والصيانة وأي عملية برمجة آلية أخرى مكتوبة لزيادة الطبيعة الموزّعة لتطوير Android.

على سبيل المثال، يمكن لوكيل أو نص برمجي استخدام واجهة سطر الأوامر لأتمتة عملية إعداد البيئة، وإنشاء مشاريع جديدة من النماذج، وإدارة الأجهزة الافتراضية مباشرةً من جهازك. كما تمنح الوكلاء إمكانية الوصول إلى مهارات Android وقاعدة معارف Android المتخصّصة للمساعدة في ضمان تطبيق الأنماط وأفضل الممارسات التي يوصي بها Android في مشاريعك.

تثبيت Android CLI

لتثبيت Android CLI، اتّبِع الخطوات التالية:

  1. نزِّل Android CLI.

  2. للتأكّد من استخدام أحدث إصدار، حدِّث Android CLI:

    android update

لمعرفة ما إذا كانت واجهة سطر الأوامر Android CLI مثبّتة على جهازك، شغِّل الأمر which android أو command -v android: إذا ظهر مسار، يعني ذلك أنّها مثبّتة.

الإعداد للوكلاء

لمساعدة الوكلاء في فهم Android CLI واستخدامه، شغِّل الأمر init لتثبيت مهارة android-cli:

android init

المشاكل المعروفة

  • تم إيقاف الأمر android emulator لنظام التشغيل Windows حاليًا.
  • لا يتوفّر حاليًا تنزيل Android CLI من Windows PowerShell.

إذا واجهت أي مشاكل أو أردت تقديم ملاحظات، يُرجى الإبلاغ عن خطأ.

ضبط Android CLI

أنشِئ ملفًا باسم .androidrc لتطبيق العلامات والخيارات تلقائيًا في كل مرة تستدعي فيها Android CLI. احفظ الملف في الموقع التالي، بناءً على نظام التشغيل:

  • macOS وLinux: ~/.androidrc
  • Windows: %USERPROFILE%\.androidrc

أضِف العلامات التي تريد تطبيقها تلقائيًا إلى الملف، مع وضع كل علامة في سطر منفصل.

على سبيل المثال، لجعل Android CLI يستخدم حزمة Android SDK معيّنة تلقائيًا في كل مرة، أضِف العلامة --sdk إلى ملفك:

--sdk=<path-to-sdk>

الخيارات العامّة

هذه علامات اختيارية يمكنك استخدامها مع أوامر Android CLI الأخرى.

-h, --help

الاستخدام: android <command> -h

الوصف: عرض دليل المساعدة للأداة أو الأمر المحدّد.

أمثلة:

  • android -h
  • android create -h

--sdk

الاستخدام: android --sdk=<path-to-sdk> <command>

الوصف: مسار حزمة Android SDK التي تريد استخدامها للأمر التالي. يمكنك استخدام الإعداد --sdk لتجاوز حزمة Android SDK التلقائية مؤقتًا بدلاً من تغيير متغيّرات البيئة العامة في كل مرة تريد فيها التبديل. لمعرفة حزمة Android 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 - تفعيل الناتج المفصّل، بما في ذلك معلومات مثل الملفات التي يتم نسخها من النموذج.
  • --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>]

الوصف: تحليل مشروع Android لإنشاء بيانات وصفية. يحدّد هذا الأمر مسارات ملفات JSON التي توضّح بنية المشروع، بما في ذلك أهداف الإنشاء ومواقع عناصر الناتج المقابلة (مثل ملفات APK)، ويعرضها. تتيح هذه المعلومات للأدوات والأوامر الأخرى تحديد مواقع عناصر الإنشاء بكفاءة.

الخيارات:

  • --project_dir - دليل المشروع المطلوب وصفه إذا لم يتم تحديد دليل، سيتم استخدام الدليل الحالي.

مثال: android describe --project_dir=/path/to/your/project

docs

الاستخدام:

  • android docs search <query>
  • android docs fetch <kb-url>

الوصف: الأمر android docs هو عملية من خطوتَين للوصول إلى قاعدة معارف Android مباشرةً من واجهة سطر الأوامر. أولاً، ابحث عن مستندات ذات صلة بطلبك باستخدام الأمر 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

الوصف: عرض مسار حزمة Android SDK التلقائية المستخدَمة لتغيير حزمة Android SDK المستخدَمة، استخدِم --sdk.

init

الاستخدام: android init

الوصف: إعداد البيئة للوكلاء من خلال تثبيت مهارة android-cli

layout

الاستخدام: android layout [--pretty] [--output] [--diff]

الوصف: عرض تنسيق واجهة مستخدم تطبيق Android النشط (المتصل من خلال جهاز فعلي أو محاكي) بتنسيق JSON

الخيارات:

  • -p, --pretty - تنسيق ناتج JSON باستخدام المسافات البادئة وفواصل الأسطر لتسهيل قراءته
  • -o, --output - تحديد موقع ملف لحفظ شجرة التنسيق إذا لم يتم تحديد موقع، ستتم طباعة JSON مباشرةً إلى الإخراج العادي.
  • -d, --diff - عرض قائمة بعناصر التنسيق التي تغيّرت فقط منذ آخر لقطة شاشة داخلية تم التقاطها (آخر مرة تم فيها تشغيل التنسيق)، بدلاً من شجرة التنسيق الكاملة

مثال:: android layout --output=./hierarchy.json

skills add

مهارات Android هي تعليمات خاصة مصمّمة لمساعدة الوكلاء في فهم وتنفيذ أنماط معيّنة بشكل أفضل تتبع أفضل الممارسات والإرشادات المتعلّقة بتطوير Android. لمزيد من المعلومات، اطّلِع على مقالة مقدّمة عن مهارات Android.

الاستخدام: android skills add [--all] [--agent=<agent-name>] [--skill=<skill-name>]

الوصف: تثبيت مهارات Android في أدلة المهارات لجميع الوكلاء الذين تم رصدهم إذا لم يكن لديك أي أدلة وكلاء حالية ولم تحدّد وكلاء معيّنين، سيتم تثبيت المهارات لـ Gemini وAntigravity في ~/.gemini/antigravity/skills.

الخيارات:

  • --all - إضافة جميع مهارات Android في آنٍ واحد إذا لم يتم تحديد هذا الخيار (ولم يتم تحديد --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 الأولية مباشرةً إلى الإخراج العادي.
  • -a, --annotate - رسم مربّعات إحاطة مصنّفة حول جميع عناصر واجهة المستخدم التي تم رصدها في الصورة، لاستخدامها مع الأمر resolve

مثال: android screen capture --output=ui.png

screen resolve

الاستخدام: android screen resolve --screenshot=<path> --string=<string>

الوصف: ترجمة التصنيفات المرئية من لقطة شاشة مصنّفة، تم التقاطها باستخدام screen capture، إلى إحداثيات الشاشة الفعلية (س، ص) مفيدة لبرمجة النقرات على العناصر بدون الحاجة إلى حساب مواضعها يدويًا

العلامات:

  • --screenshot - مسار لقطة الشاشة المصنّفة
  • --string - سلسلة تتضمّن عنصر نائب واحدًا على الأقل يتطابق مع تصنيف عنصر في واجهة المستخدم بالتنسيق #<number> سيتم استبدال الجزء #<number> بـ إحداثيات الشاشة.

مثال:

إذا كان التصنيف 5 عند الإحداثيات (500، 1000)، فإنّ الأمر

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 - تضمين حِزم الإصدار التجريبي 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 - تثبيت الإصدار 2 من حزمة Android SDK Platform 34
  • android sdk install --canary system-images/android-35/google_apis/x86_6 - تثبيت أحدث إصدار من صورة نظام Android 35 من قناة الإصدار التجريبي Canary.
  • android sdk install --force platforms/android-33@1 - الرجوع إلى الإصدار 1 من حزمة Android SDK Platform 33 من القناة الثابتة

sdk list

الاستخدام: android sdk list <package-pattern>

الوصف: عرض حِزم SDK المثبّتة والمتاحة

الوسيطات (إلزامية):

  • <package-pattern> - فلترة الحِزم حسب النمط يدعم التعبيرات العادية.

الخيارات:

  • --all - عرض جميع الحِزم المثبّتة والمتاحة
  • --all-versions - عرض جميع إصدارات كل حزمة
  • --beta - تضمين حِزم الإصدار التجريبي
  • --canary - تضمين حِزم الإصدار التجريبي 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>

الوصف: نشر تطبيق Android على جهاز متصل أو محاكي لا يتم تنفيذ أي خطوات إنشاء، ويجب تقديم مسارات ملفات APK التي تريد تثبيتها.

الوسيطات (إلزامية):

  • --apks - قائمة قيم مفصولة بفاصلة تضمّ مسارات ملفات APK التي تريد تثبيتها المسار نسبي إلى الموقع الحالي في نظام الملفات.

الخيارات:

  • --activity - اسم النشاط المطلوب تشغيله بعد تثبيت ملف APK إذا كانت هناك أنشطة متعدّدة، يجب تحديد نشاط واحد لتشغيله في البداية.
  • --debug - نشر التطبيق في وضع تصحيح الأخطاء. بعد تشغيل الـ تطبيق في وضع تصحيح الأخطاء، يجب ربط مصحِّح الأخطاء من بيئة تطوير متكاملة، مثل "استوديو Android"، أو أداة سطر أوامر لبدء تصحيح الأخطاء.
  • --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 - تضمين حِزم الإصدار التجريبي 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

الوصف: تحديث Android CLI

-V, --version

الوصف: عرض الإصدار الحالي من Android CLI