Copy files to and from a component

The ffx component copy command can copy files to and from Fuchsia components running on a target device.

Concepts

The ffx component copy command can transfer files in the following ways:

  • From a component on the device to the host machine.
  • From the host machine to a component on the device.
  • Between components on the device.

Capabilities such as storage and directory provide persistent or ephemeral storage in a Fuchsia system where files belong to a specific component can be stored and accessed. Every Fuchsia component has a namespace where a component can access all of its available capabilities. A component's moniker indicates its position in the component topology, which also serves as an identifier of the component on the system.

Therefore, to access files in a component's namespace, you first need to identify the moniker of your target component. For example, the moniker of the stash_secure component is core/stash_secure. (To discover a component's moniker, see the ffx component show command.)

Copy a file to and from a component's namespace

To copy a file to and from a component running on a Fuchsia device, run the following command:

ffx component copy SOURCE DESTINATION

Replace the following:

  • SOURCE: The path of the file(s) to be copied. This path can refer to either a local path or a path within a directory associated with a Fuchsia component on the target device.

  • DESTINATION: The destination path for the file(s). The same options and restrictions apply here as for SOURCE.

    If SOURCE or DESTINATION is a Fuchsia component, use the syntax below to represent the component and path:

    MONIKER::DIR_TYPE::PATH

    DIR_TYPE can be one of in, out, or pkg, to indicate the namespace (the "incoming" directory), the component's outgoing directory, or the component's package directory. Optionally, DIR_TYPE can be omitted and the command will default to the component's namespace.

    For example, core/stash_secure::in::/data/examples.txt means the path /data/example.txt in the namespace of the core/stash_secure component.

See example commands below:

  • Download the stash_secure.store file from the core/stash_secure component to the host machine:

    $ ffx component copy core/stash_secure::/data/stash_secure.store ./copy_of_stash_secure.store

  • Upload the example.txt file from the host machine to the core/stash_secure component:

    $ ffx component copy ./my_example_dir/example.txt core/stash_secure::/data/copy_of_example.txt

  • Copy the stash_secure.store file from the core/stash_secure component to the core/feedback component:

    $ ffx component copy core/stash_secure::/data/stash_secure.store core/feedback::/data/copy_of_stash_secure.store

Copy multiple files to and from a component's namespace

The ffx component copy command supports the use of the wildcard * to copy multiple files at once.

See example commands below:

  • Download all files in the /data directory of the core/stash_secure component to the host machine:

    $ ffx component copy core/stash_secure::/data/* ./my_example_dir/

  • Upload all files in the ./my_example_dir directory of the host machine to the core/stash_secure component:

    $ ffx component copy ./my_example_dir/* core/stash_secure::/data/

  • Copy all files in the /data directory of the core/stash_secure component to the core/feedback component:

    $ ffx component copy core/stash_secure::/data/* core/feedback::/data/

  • Copy all files in the data directory of the core/feedback/ component and the example.txt file on the host machine to the core/stash_secure component:

    $ ffx component copy core/feedback::/data/* ./my_example_dir/example.txt core/stash_secure::/data/

Appendices

Copy a file to and from a component's isolated storage

Some Fuchsia component are allocated per-component isolated storage with storage capabilities.

Unlike ffx component copy, the ffx component storage command works exclusively with storage capabilities. Instead of an moniker, this command uses a component's instance ID as an identifier. By default, the ffx component storage command interfaces with the storage capability named data.

To copy a file to and from a component's isolated storage, run the following command:

ffx component storage copy SOURCE DESTINATION

Replace the following:

  • SOURCE: The path of the file(s) to be copied. This path can refer to either the host machine or a Fuchsia component on the target device.

  • DESTINATION: The destination path for the file(s). This path can refer to either the host machine or a Fuchsia component on the target device.

    If SOURCE or DESTINATION is a Fuchsia component, use the syntax below to represent the component and path:

    INSTANCE_ID::PATH_IN_STORAGE

    For example, c1a6d0aebbf7c092c53e8e696636af8ec0629ff39b7f2e548430b0034d809da4::/examples.txt means that the example.txt file is located in the default /data directory of the core/stash_secure component.

See example commands below:

  • Upload the example.txt file from the host machine to the core/stash_secure component:

    $ ffx component storage copy ./my_example_dir/example.txt c1a6d0aebbf7c092c53e8e696636af8ec0629ff39b7f2e548430b0034d809da4::/copy_of_example.txt

  • Download the stash_secure.store file from the target componnet to the host machine:

    $ ffx component storage copy c1a6d0aebbf7c092c53e8e696636af8ec0629ff39b7f2e548430b0034d809da4::/stash_secure.store ./my_example_dir/copy_of_example.txt

List all directories and files in a component's isolated storage

To list all directories and files in a component's isolated storage, run the following command:

ffx component storage list INSTANCE_ID::PATH

Replace the following:

  • INSTANCE_ID: The instance ID of the target component. For example, c1a6d0aebbf7c092c53e8e696636af8ec0629ff39b7f2e548430b0034d809da4.

  • PATH: A path on the target component.

The example command below shows all directories and files in the root (/) directory of the target component:

$ ffx component storage list c1a6d0aebbf7c092c53e8e696636af8ec0629ff39b7f2e548430b0034d809da4::/
copy_of_example.txt
stash_secure.store

Create a new directory in a component's isolated storage

To create a new directory in a component's isolated storage, run the following command:

ffx component storage make-directory INSTANCE_ID::NEW_PATH

Replace the following:

  • INSTANCE_ID: The instance ID of the target component. For example, c1a6d0aebbf7c092c53e8e696636af8ec0629ff39b7f2e548430b0034d809da4.

  • NEW_PATH: The name of the new directory to be created on the target component.

The example command below creates a new directory named my-new-example-dir on the target component:

$ ffx component storage make-directory c1a6d0aebbf7c092c53e8e696636af8ec0629ff39b7f2e548430b0034d809da4::/my-new-example-dir