The ffx component copy
command can copy files to and from Fuchsia components running on a target device.
The ffx component copy
command can transfer files in the following ways:
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.)
To copy a file to and from a component running on a Fuchsia device, run the following command:
ffx component copy {{ '<var>' }}SOURCE{{ '</var>' }} {{ '<var>' }}DESTINATION{{ '</var>'}}
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:
{{ '<var>' }}MONIKER{{ '</var>' }}::{{ '<var>' }}DIR_TYPE{{ '</var>' }}::{{ '<var>' }}PATH{{ '</var>' }}
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
The ffx component copy
command supports the use of the wildcard *
to copy multiple files at once.
Note: In Zsh
{:.external} and fish
{:.external}, you may run into issues when using *
for the paths on the device. A workaround is to wrap the path with *
in single quotes (''
). For example, replace /data/*
with '/data/*'
.
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/
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 {{ '<var>' }}SOURCE{{ '</var>' }} {{ '<var>' }}DESTINATION{{ '</var>'}}
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:
{{ '<var>' }}INSTANCE_ID{{ '</var>' }}::{{ '<var>' }}PATH_IN_STORAGE{{ '</var>' }}
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
To list all directories and files in a component's isolated storage, run the following command:
ffx component storage list {{ '<var>' }}INSTANCE_ID{{ '</var>' }}::{{ '<var>' }}PATH{{ '</var>' }}
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
To create a new directory in a component's isolated storage, run the following command:
ffx component storage make-directory {{ '<var>' }}INSTANCE_ID{{ '</var>' }}::{{ '<var>' }}NEW_PATH{{ '</var>' }}
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