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 often functions as an identifier for the component and its namespace.
Therefore, to access files in a component's namespace, you first need to identify the
absolute moniker of your target component. For example, the absolute
moniker of the stash_secure
component is /core/stash_secure
. (To discover a component's
absolute 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 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:
MONIKER::PATH_IN_NAMESPACE
For example,
/core/stash_secure::/data/examples.txt
means that theexample.txt
file is located in the/data
directory 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.
When the wildcard is used, the paths on the host machine are interpreted by the terminal while the
paths on the Fuchsia device are interpreted by the ffx component copy
command.
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 theexample.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
A Fuchsia component can allocate per-component isolated storage on a device using storage capabilities. This type of storage is isolated within the component, preventing other components from accessing files in the storage.
Unlike ffx component copy
, the ffx component storage
command works exclusively with
storage capabilities. Instead of an absolute moniker, this command uses a component's
instance ID as an identifier. By default, the ffx component storage
command connects to the component's data
storage.
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 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