More detailed global cvd help

[jemoreira]

Bug: b/522979240
Assisted-by: Gemini

[jemoreira]

The output looks like this:

$ cvd help
Cuttlefish Virtual Device (CVD) CLI.

Cuttlefish is a configurable virtual Android device offering high-fidelity
Android emulation for platform and app development, and automated testing.

Device Organization:
  Cuttlefish devices are organized into Instance Groups and Instances.
  - An Instance represents a single virtual Android device.
  - An Instance Group is a logical collection of one or more Instances created
    and managed together.
  - Group and Instance Naming:
    - Each group and instance has a name. Names can be user-provided or
      automatically generated by cvd.
    - Group names must be unique across the host for the current user.
    - Instance names must be unique within their containing group.

Cuttlefish devices lifecycle:
  - create:     Cuttlefish devices must be "created" (`cvd create` command)
    before they can be used. The instance group directory structure is created,
    host resources like virtual networks and instance ids are allocated and
    build artifacts are fetched during this step. Cuttlefish devices are
    automatically started at the end of the creation process unless the user
    passes the --nostart option.
  - start|stop  Turn the virtual devices ON or OFF respectively. These actions
    can be performed repeatedly just like in a physical Android device. Virtual
    device state and disks are preserved across a stop-start cycle.
  - remove:     The opposite of create, this action completely removes the
    devices from the system. Logs and virtual disks in particular are deleted
    during this step. Host resources, context ids and cuttlefish names are also
    released.

Selector Arguments:
  Many commands act on an existing instance or group. If only one group or
  instance exists, cvd will select that one as the command's target, otherwise
  it will ask you to select one from a list. Selector options can be used
  *before* the subcommand explicitly select a target and avoid the interactive
  seleccion step:
    cvd -group_name <group_name> <command>
    cvd -instance_name <instance_name> <command>

Build Fetching and Caching:

cvd can automatically download Android builds from the Android Build servers
(e.g., "@ab/aosp-android-latest-release/aosp_cf_x86_64_only_phone-userdebug").
cvd fetches the required host tools and device images, caching them locally to
accelerate future device creation.

Usage:
    cvd [selector/global options] <command> [args]
    cvd help [<command> [args]]

Global Options:
 --verbosity=VAL
    Adjust Cvd verbosity level. LEVEL is one of ERROR, WARNING, INFO, DEBUG,
    VERBOSE.
    Current value: "INFO"

Selector Options:
 --group_name=VAL
    Instance group name. If only one group exists it will default to that when
    no group name is provided.
    Current value: "[not set]"

 --instance_name=VAL
    Comma separated list of instance names. If a single group with a single
    instance exists it will default to that when not provided.
    Current value: "[not set]"

Commands (cvd help <command> for more information):

        cache - Manage the files cached by cvd

        create - Create a Cuttlefish instance group

        fetch, fetch_cvd - Retrieve build artifacts based on branch and target names

        help - Used to display help information for other commands

        lint - error checks the input virtual device json config file

        load - Creates and starts an instance group from a JSON configuration file

        login - Acquire credentials

        reset - Used to stop devices, optionally clean up instance files, and shut down the deprecated cvd server process

        setup - Configure the host for Cuttlefish

        version - Prints version of cvd client and cvd server


  Device-Specific Commands (cvd help <command> for more information):

        display - Enables hotplug/unplug of displays from running cuttlefish virtual devices

        env - Enumerate + Query APIs for all gRPC services made available by this virtual device instance

        fleet - lists active devices with relevant information

        clear - Clears the instance database, stopping any running instances first.

        bugreport, host_bugreport, cvd_host_bugreport - Run cvd bugreport --help for command description

        stop, stop_cvd - Stop all instances in a group

        powerbtn - Trigger power button event on the device

        powerwash - Reset device to first boot state

        monitor - Monitor device logs (launcher, kernel, and logcat) in real-time.

        restart - Restart device

        remove, rm - Remove devices and artifacts from the system.

        screen_recording - Record screen contents

        suspend, resume, snapshot_take - Suspend/resume the cuttlefish device, or take snapshot of the device

        start, launch_cvd - Start all Cuttlefish Instances in a group

        status, cvd_status - Query status of a single instance group.  Use `cvd fleet` for all devices

        logs - Print device logs

Typical Usage Examples:

  Create from specification (Multi-Device / Config-driven):

    1. Create a JSON configuration file (e.g., spec.json) containing:
       {
         "instances": [
           {
             "name": "phone-ins",
             "disk": {
               "default_build": "@ab/aosp-android-latest-release/aosp_cf_x86_64_only_phone-userdebug"
             }
           },
           {
             "name": "wearable-ins",
             "disk": {
               "default_build": "@ab/aosp-android-latest-release/aosp_cf_x86_64_foldable-userdebug"
             }
           }
         ]
       }

    2. Launch the group:
       $ cvd create --config_file=spec.json

    3. View the state of the running fleet:
       $ cvd fleet

    4. View the log files:
       $ cvd logs
       $ cvd logs -p launcher.log

    5. Open the web UI at https://localhost:1443

    6. Interact with the device via ADB (auto-connected on every start)

    7. Control the lifecycle:
       $ cvd stop
       $ cvd start

    8. Gather all logs for troubleshooting:
       $ cvd bugreport

    9. Clean up and delete all resources:
       $ cvd remove

  Create from local source (Platform Developer / AOSP build):

    1. Build Android in your terminal (ensuring ANDROID_HOST_OUT and
       ANDROID_PRODUCT_OUT are set in the environment).

    2. Launch the device:
       $ cvd create

    3. After making changes, rebuild and restart:
       $ cvd stop
       $ m  # Rebuild android
       $ cvd start

  Environment Cleanup (Last Resort):
    If virtual devices become unresponsive, or if 'cvd remove' fails to fully
    clean up the environment, use 'cvd reset' to forcefully terminate all
    Cuttlefish-related background processes and free up host resources:
       $ cvd reset

[Databean]

nit: a foldable is not a wearable

[Databean]

This target doesn't exist: https://ci.android.com/builds/branches/aosp-android-latest-release/grid?legacy=1

At the moment there are:

• aosp_cf_arm64_auto-userdebug
• aosp_cf_arm64_only_phone-userdebug
• aosp_cf_riscv64_phone-userdebug
• aosp_cf_x86_64_auto-userdebug
• aosp_cf_x86_64_only_auto
• aosp_cf_x86_64_only_phone

[Databean]

Should we mention this may not immediately work if the ADB server hasn't started yet? If you run cvd create first and then adb shell, the first adb shell will start the ADB server, see no devices, and fail. Then the autoconnector will run within some time, and then adb shell will work

[Databean]

"offering... and automated testing" is a bit odd. The device is especially convenient to use in an automated test, but the device isn't providing the test.

[Databean]

selection

[Databean]

You mentioned lifting the requirement of passing selector options first, was that change made?