نظرة عامة على واجهة سطر الأوامر في 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

أنشِئ ملف .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