# 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](https://fuchsia.dev/docs/concepts/components/v2/capabilities/storage) and
[directory](https://fuchsia.dev/docs/concepts/components/v2/capabilities/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](https://fuchsia.dev/docs/concepts/process/namespaces) where a component can access all of its available
capabilities. A component's [moniker](https://fuchsia.dev/docs/concepts/components/v2/identifiers#monikers) 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`](https://fuchsia.dev/fuchsia-src/development/tools/ffx/workflows/view-component-information.md#get-detailed-information-from-a-component) 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:

- <var translate="no">SOURCE</var>: 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.

- <var translate="no">DESTINATION</var>: The destination path for the file(s). The same
  options and restrictions apply here as for `SOURCE`.

  If <var translate="no">SOURCE</var> or <var translate="no">DESTINATION</var> 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.

> [!NOTE]
> **Note:** In [`Zsh`](https://zsh.sourceforge.io/) and [`fish`](https://fishshell.com/), 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/

## Appendices

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

Some Fuchsia component are allocated per-component *isolated* storage with
[storage capabilities](https://fuchsia.dev/docs/concepts/components/v2/capabilities/storage).

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](https://fuchsia.dev/docs/development/components/component_id_index) 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:

- <var translate="no">SOURCE</var>: 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.

- <var translate="no">DESTINATION</var>: 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 <var translate="no">SOURCE</var> or <var translate="no">DESTINATION</var> 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](https://fuchsia.dev/fuchsia-src/development/tools/ffx/workflows/copy-files-to-and-from-a-component#copy-a-file-to-and-from-a-components-isolated-storage),
run the following command:

    ffx component storage list INSTANCE_ID::PATH

Replace the following:

- <var translate="no">INSTANCE_ID</var>: The instance ID of the target component.
  For example, `c1a6d0aebbf7c092c53e8e696636af8ec0629ff39b7f2e548430b0034d809da4`.

- <var translate="no">PATH</var>: 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](https://fuchsia.dev/fuchsia-src/development/tools/ffx/workflows/copy-files-to-and-from-a-component#copy-a-file-to-and-from-a-components-isolated-storage),
run the following command:

    ffx component storage make-directory INSTANCE_ID::NEW_PATH

Replace the following:

- <var translate="no">INSTANCE_ID</var>: The instance ID of the target component.
  For example, `c1a6d0aebbf7c092c53e8e696636af8ec0629ff39b7f2e548430b0034d809da4`.

- <var translate="no">NEW_PATH</var>: 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

[](https://issues.fuchsia.dev/issues/new?component=1439230&template=1881640&description=Issue+on:+https://fuchsia.dev/docs/development/tools/ffx/workflows/copy-files-to-and-from-a-component.md "Report a bug or suggest improvements on this page") [](https://cs.opensource.google/fuchsia/fuchsia/+/main:docs/development/tools/ffx/workflows/copy-files-to-and-from-a-component.md "View the source code of this page") [](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/development/tools/ffx/workflows/copy-files-to-and-from-a-component.md&cloneRepo=fuchsia/fuchsia:refs/heads/main&fullPath=fuchsia/docs/development/tools/ffx/workflows/copy-files-to-and-from-a-component.md "Edit the source code of this page")