# Getting started with ffx

This doc will guide you through some of the features of `ffx`. For an overview
of the design and components of `ffx`, see [the ffx overview](/docs/development/tools/ffx/overview.md).

## Contacting the ffx team

If you discover possible bugs or have questions or suggestions,
[file a bug](https://issues.fuchsia.dev/issues/new?component=1378294&template=1838957).

## Prerequisites

To follow the examples in this doc, you'll need a Fuchsia device running. If you
don't have a physical device connected, you can use an emulator.

To start an emulator with networking enabled but without graphical user
interface support, run `ffx emu start --headless`.

For more information on configuring the emulator
see, [Start the Fuchsia emulator](/docs/get-started/set_up_femu.md).

Your device must be running a `core`
[product configuration](/docs/development/build/build_system/boards_and_products.md)
or a product configuration that extends `core` (such as `workstation_eng`).

Optionally, you can run `ffx log`, which will provide some additional information
about the interactions between `ffx` and your Fuchsia target device.

## Introduction

After following all the prerequisites, run the following in a terminal:

```posix-terminal
fx ffx help
```

This will list all of the available `ffx` subcommands. You'll see something
like:

```none
Usage: ffx [-c <config>] [-e <env>] [-t <target>] [<command>] [<args>]

Fuchsia's developer tool

Options:
  -c, --config      override default configuration
  -e, --env         override default environment settings
  -t, --target      apply operations across single or multiple targets
  --help            display usage information

Commands:
  component         Discover and manage components
  config            View and switch default and user configurations
  daemon            Interact with/control the ffx daemon
  diagnostic        Run diagnostic tests on Fuchsia targets
  docs              View suite of docs for ffx and for Fuchsia
  doctor            Run common checks for the ffx tool and host environment
  emulator          Start and manage Fuchsia emulators
  overnet           Interact with the Overnet mesh
  package           Create and publish Fuchsia packages
  sdk               Modify or query the installed SDKs
  target            Interact with a target device or emulator
  vendor            Run partner plugins
  version           Print out ffx tool and daemon versions
```

You can use `fx ffx help <subcommand>` or `fx ffx <subcommand> --help` to see
more about any subcommand.

## Interacting with target devices

In a terminal, run the following:

```posix-terminal
fx ffx target list
```

You'll see a list of devices that `ffx` has discovered. For example, with a
single emulator running, output looks like:

```none
NAME                    SERIAL       TYPE       STATE      ADDRS/IP                       RCS
fuchsia-emulator  <unknown>    Unknown    Product    [fe80::5054:ff:fe63:5e7a%4]    N
```

`RCS`: Indicates whether there is a reachable instance of the Remote Control
Service (RCS) running on the device.

In order to get `ffx` to automatically connect to a device, you must either have
set the target's nodename to be the default target, or attempt to interact with the
device.

To set the target to be the default, run:

```posix-terminal
fx ffx target default set $NODENAME
```

If the default target has been set prior to starting the daemon, waiting a few seconds
should yield a change to the `RCS` status to show `Y`.

If the default target has been set after starting the daemon, attempting to interact
with the target should be sufficient to kick off a connection, like the following

```posix-terminal
fx ffx component list
```

Note: If the default target has been set, and you are unable to run that command
against the target, [reach out](#contacting_the_ffx_team) to the `ffx` team.

Then the next time you list targets you should see that an `RCS` connection
is active.

```none
$ fx ffx target list
NAME                    SERIAL       TYPE       STATE      ADDRS/IP                       RCS
fuchsia-emulator  <unknown>    Unknown    Product    [fe80::5054:ff:fe63:5e7a%4]    Y
```

If a target has been set as default there will be a `*` next to it.

If you had `ffx log` running, you should also see something like the following in
the logs:

```none
[00009.776170][28540][28542][remote-control, remote_control_bin] INFO: published remote control service to overnet
```

NOTE: if the `RCS` column remains `N` for an extended amount of time and you have
already set this target's nodename to `target.default` _before_ initially starting
ffx, [reach out](#contacting_the_ffx_team) to the `ffx` team.

### On Default Targets

Above we covered setting the default target using the command

```posix-terminal
fx ffx target default set
```

It is also possible to set the default target on a per-command basis using the
`--target` flag like so.

```posix-terminal
fx ffx --target $NODENAME component list
```

### Interacting with multiple devices

TODO: fill this out.

### Controlling the state of target devices

You can use the `target off` and `target reboot` subcommands to power-off or
reboot a device, respectively.

## Configuration

See documentation for the [config command](/docs/development/tools/ffx/commands/config.md).

## Interacting with Components

### Monikers

Many `ffx` commands that use components take monikers as a parameter. You can read more about
monikers and their syntax in [component moniker documentation](/docs/reference/components/moniker.md).

### Finding components

The `component list` command will output monikers of all components that currently exist
in the component topology.

```none
$ fx ffx component list
/
/bootstrap
/bootstrap/archivist
/bootstrap/base_resolver
/bootstrap/console
/bootstrap/console-launcher
/bootstrap/cr50_agent
/bootstrap/device_name_provider
/bootstrap/driver_index
/bootstrap/driver_manager
/bootstrap/flashmap
/bootstrap/fshost
/bootstrap/fshost/blobfs
/bootstrap/fshost/blobfs/decompressor
...
```

You can use the `component select capability` command to search for components that use/expose
a capability with a given name.

The following command will display all components that use/expose the `diagnostics` capability:

```none
$ fx ffx component capability diagnostics
Exposed:
  /bootstrap/archivist
  /bootstrap/base_resolver
  /bootstrap/driver_manager
  /bootstrap/fshost
  /bootstrap/fshost/blobfs
  /bootstrap/fshost/blobfs/decompressor
  /bootstrap/fshost/minfs
  /bootstrap/pkg-cache
  /bootstrap/power_manager
  ...
```

### Inspecting a component

You can use the `component show` command to get detailed information about a specific
component.

`component show` allows partial matching on URL, moniker and component instance ID.

The following command will display information about the `/core/network/dhcpd` component:

```none
$ fx ffx component show dhcpd
               Moniker:  /core/network/dhcpd
                   URL:  #meta/dhcpv4_server.cm
           Instance ID:  20b2c7aba6793929c252d4e933b8a1537f7bfe8e208ad228c50a896a18b2c4b5
                  Type:  CML Component
       Component State:  Resolved
 Incoming Capabilities:  /svc/fuchsia.net.name.Lookup
                         /svc/fuchsia.posix.socket.packet.Provider
                         /svc/fuchsia.posix.socket.Provider
                         /svc/fuchsia.stash.SecureStore
                         /svc/fuchsia.logger.LogSink
  Exposed Capabilities:  fuchsia.net.dhcp.Server
           Merkle root:  521109a2059e15acc93bf77cd20546d106dfb625f2d1a1105bb71a5e5ea6b3ca
       Execution State:  Running
          Start reason:  '/core/network/netcfg' requested capability 'fuchsia.net.dhcp.Server'
         Running since:  2022-09-15 16:07:48.469094140 UTC
                Job ID:  28641
            Process ID:  28690
 Outgoing Capabilities:  fuchsia.net.dhcp.Server
```

### Verifying capability routes

You can use the `component doctor` command to verify that all capabilities
exposed and used by a component are successfully routed.

For example:

```none
$ fx ffx component doctor /bootstrap/archivist
Querying component manager for /bootstrap/archivist
URL: fuchsia-boot:///#meta/archivist.cm
Instance ID: None

      Used Capability                      Error
 [✓]  fuchsia.boot.ReadOnlyLog             N/A
 [✓]  fuchsia.boot.WriteOnlyLog            N/A
 [✓]  fuchsia.component.DetectBinder       N/A
 [✓]  fuchsia.component.KcounterBinder     N/A
 [✓]  fuchsia.component.PersistenceBinder  N/A
 [✓]  fuchsia.component.SamplerBinder      N/A
 [✓]  fuchsia.sys.internal.ComponentEvent  N/A
      Provider
 [✓]  fuchsia.sys.internal.LogConnector    N/A
 [✓]  config-data                          N/A

      Exposed Capability                   Error
 [✓]  fuchsia.diagnostics.FeedbackArchive  N/A
      Accessor
 [✓]  fuchsia.diagnostics.LegacyMetricsAr  N/A
      chiveAccessor
 [✓]  fuchsia.diagnostics.LoWPANArchiveAc  N/A
      cessor
 [✓]  diagnostics                          N/A
 [✓]  fuchsia.diagnostics.ArchiveAccessor  N/A
 [✓]  fuchsia.diagnostics.LogSettings      N/A
 [✓]  fuchsia.logger.Log                   N/A
 [✓]  fuchsia.logger.LogSink               N/A
```

```none
$ fx ffx component doctor /core/feedback
Querying component manager for /core/feedback
URL: fuchsia-pkg://fuchsia.com/forensics#meta/feedback.cm
Instance ID: eb345fb7dcaa4260ee0c65bb73ef0ec5341b15a4f603f358d6631c4be6bf7080

      Used Capability                      Error
 [✓]  fuchsia.boot.ReadOnlyLog             N/A
 [✓]  fuchsia.boot.WriteOnlyLog            N/A
 [✓]  fuchsia.diagnostics.FeedbackArchive  N/A
      Accessor
 [✓]  fuchsia.hardware.power.statecontrol  N/A
      .RebootMethodsWatcherRegister
 [✓]  fuchsia.hwinfo.Board                 N/A
 [✓]  fuchsia.hwinfo.Product               N/A
 [✓]  fuchsia.metrics.MetricEventLoggerFa  N/A
      ctory
 [✓]  fuchsia.net.http.Loader              N/A
 [✓]  fuchsia.process.Launcher             N/A
 [✓]  fuchsia.sysinfo.SysInfo              N/A
 [✓]  fuchsia.ui.activity.Provider         N/A
 [✗]  fuchsia.feedback.DeviceIdProvider    `/core/feedback` tried to use `fuchsia.feedback.DeviceIdProvider` from its parent,
                                           but the parent does not offer that capability. Note, use clauses in CML default to
                                           using from parent.
 ...
```

### Running a component

The `component run` command can create and launch components in a given isolated collection.

Note: `fx serve` must be running in order to run a package that is not
[in base or cached](/docs/development/build/build_system/boards_and_products.md#dependency_sets).

Here's an example of running the Rust `hello-world` component in the `/core/ffx-laboratory`
collection. First, you'll need the hello-world package in your universe:

```none
$ fx set <product>.<board> --with //examples/hello_world/rust:hello-world-rust && fx build
...
```

Then use the `component run` command to create and launch a component instance from the URL
`fuchsia-pkg://fuchsia.com/hello-world-rust#meta/hello-world-rust.cm` with the moniker
`/core/ffx-laboratory:hello-world-rust`:

```none
$ fx ffx component run /core/ffx-laboratory:hello-world-rust fuchsia-pkg://fuchsia.com/hello-world-rust#meta/hello-world-rust.cm
URL: fuchsia-pkg://fuchsia.com/hello-world-rust#meta/hello-world-rust.cm
Moniker: /core/ffx-laboratory:hello-world-rust
Creating component instance...
...
$ fx ffx component show hello-world-rust
               Moniker: /core/ffx-laboratory:hello-world-rust
                   URL: fuchsia-pkg://fuchsia.com/hello-world-rust#meta/hello-world-rust.cm
                  Type: v2 dynamic component
       Execution State: Running
                Job ID: 50775
            Process ID: 50819
...
```

## Resolving connectivity issues

If you're experiencing problems communicating with a target device using `ffx`,
you can use the `doctor` command to diagnose and attempt to resolve them. If you
file a bug that involves a target device, we'll typically ask for the output
from `ffx doctor` to provide information about where the problem is.

`doctor` will attempt to communicate with the ffx daemon, killing
and restarting it if needed. If this is successful, it will attempt to SSH into
a target device and start the Remote Control Service.

If you try running `ffx doctor` under normal circumstances, you should see:

```none
$ fx ffx doctor
Checking for a running daemon...none running.
Attempting to kill any zombie daemons...killed at least one daemon.
Starting a new daemon instance...success
Attempting to connect to the daemon. This may take a couple seconds...success
Attempting to communicate with the daemon...success
Attempting to list targets...success
Attempting to get an RCS connection...success
Attempting to communicate with RCS...success


SUCCESS. You should be able to run ffx commands now.
```

If `doctor` fails, it will try to suggest a resolution to the problem. You can [file a bug](https://issues.fuchsia.dev/issues/new?component=1378294&template=1838957) for the ffx team if you
persistently have problems. For example, if `doctor` is unable to start the RCS,
you would see the following:

```none
$ fx ffx doctor
Checking for a running daemon...found
Attempting to connect to the daemon. This may take a couple seconds...success
Attempting to communicate with the daemon...success
Attempting to list targets...success
Attempting to get an RCS connection...success
Attempting to communicate with RCS...FAILED. Timed out.


Attempt 2 of 3
Attempting to list targets...success
Attempting to get an RCS connection...success
Attempting to communicate with RCS...FAILED. Timed out.


Attempt 3 of 3
Attempting to list targets...success
Attempting to get an RCS connection...success
Attempting to communicate with RCS...FAILED. Timed out.


Connecting to RCS failed after maximum attempts. To resolve this issue, try
rebooting your device. If this persists, please file a bug at the link below
and include 1) all output
above and 2) device syslog if available.Bug link: ...
```

## Testing with ffx

The `ffx` command is useful when writing integration tests which need to interact
with the Fuchsia environment. However, since `ffx` is primarily designed for
developers, it inspects the current environment for configuration and also starts
a daemon in the background to coordinate communication with Fuchsia devices. This
makes it more complex to write automated tests that use `ffx` since the configuration
and daemon should be isolated in order to avoid side effects, or interference from
the global environment.

To achieve this isolation, test authors need to use [isolate directories][isolate-dir]
when running tests which use `ffx`.

## Next steps

- Please provide feedback on this doc by [reaching out to the ffx team](#contacting_the_ffx_team)!
- Learn how to [extend `ffx`](/docs/development/tools/ffx/development/plugins.md).


<!-- Reference links -->

[isolate-dir]: development/integration_testing/README.md