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 ofin
,out
, orpkg
, 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 thecore/stash_secure
component.
See example commands below:
Download the
stash_secure.store
file from thecore/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 thecore/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 thecore/stash_secure
component to thecore/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 thecore/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 thecore/stash_secure
component:$ ffx component copy ./my_example_dir/* core/stash_secure::/data/
Copy all files in the
/data
directory of thecore/stash_secure
component to thecore/feedback
component:$ ffx component copy core/stash_secure::/data/* core/feedback::/data/
Copy all files in the
data
directory of thecore/feedback/
component and theexample.txt
file on the host machine to thecore/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 theexample.txt
file is located in the default/data
directory of thecore/stash_secure
component.
See example commands below:
Upload the
example.txt
file from the host machine to thecore/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