docs/development/sdk/ffx/copy-files-to-and-from-a-component.md

# 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][storage-capabilities] and
[directory][directory-capabilities] 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][namespace] where a component can access all of its available
capabilities. A component's [moniker][component-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`][ffx-component-show] command.)

## Copy a file to and from a component's namespace {:#copy-a-file-to-and-from-a-components-namespace}

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

```posix-terminal
ffx component copy {{ '<var>' }}SOURCE{{ '</var>' }} {{ '<var>' }}DESTINATION{{ '</var>'}}
```

Replace the following:

*  <var>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>DESTINATION</var>: The destination path for the file(s). The same
   options and restrictions apply here as for `SOURCE`.

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

   ```none {:.devsite-disable-click-to-copy}
   {{ '<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:

   ```none {:.devsite-disable-click-to-copy}
   $ 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:

   ```none {:.devsite-disable-click-to-copy}
   $ 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:

   ```none {:.devsite-disable-click-to-copy}
   $ 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 {:#copy-multiple-files-to-and-from-a-components-namespace}

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

Note: In [`Zsh`][zsh]{:.external} and [`fish`][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:

   ```none {:.devsite-disable-click-to-copy}
   $ 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:

   ```none {:.devsite-disable-click-to-copy}
   $ 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:

   ```none {:.devsite-disable-click-to-copy}
   $ 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:

   ``` none {:.devsite-disable-click-to-copy}
   $ 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 {:#copy-a-file-to-and-from-a-components-isolated-storage}

Some Fuchsia component are allocated per-component *isolated* storage with
[storage capabilities][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][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:

```posix-terminal
ffx component storage copy {{ '<var>' }}SOURCE{{ '</var>' }} {{ '<var>' }}DESTINATION{{ '</var>'}}
```

Replace the following:

*  <var>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>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>SOURCE</var> or <var>DESTINATION</var> is a Fuchsia component,
   use the syntax below to represent the component and path:

   ```none {:.devsite-disable-click-to-copy}
   {{ '<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:

   ```none {:.devsite-disable-click-to-copy}
   $ 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:

   ```none {:.devsite-disable-click-to-copy}
   $ 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 {:#list-all-directories-and-files-in-a-components-isolated-storage}

To list all directories and files in a component's
[isolated storage](#copy-a-file-to-and-from-a-components-isolated-storage),
run the following command:

```posix-terminal
ffx component storage list {{ '<var>' }}INSTANCE_ID{{ '</var>' }}::{{ '<var>' }}PATH{{ '</var>' }}
```

Replace the following:

*  <var>INSTANCE_ID</var>: The instance ID of the target component.
   For example, `c1a6d0aebbf7c092c53e8e696636af8ec0629ff39b7f2e548430b0034d809da4`.

*  <var>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:

```none {:.devsite-disable-click-to-copy}
$ ffx component storage list c1a6d0aebbf7c092c53e8e696636af8ec0629ff39b7f2e548430b0034d809da4::/
copy_of_example.txt
stash_secure.store
```

### Create a new directory in a component's isolated storage {:#create-a-new-directory-in-a-components-isolated-storage}

To create a new directory in a component's
[isolated storage](#copy-a-file-to-and-from-a-components-isolated-storage),
run the following command:

```posix-terminal
ffx component storage make-directory {{ '<var>' }}INSTANCE_ID{{ '</var>' }}::{{ '<var>' }}NEW_PATH{{ '</var>' }}
```

Replace the following:

*  <var>INSTANCE_ID</var>: The instance ID  of the target component.
   For example, `c1a6d0aebbf7c092c53e8e696636af8ec0629ff39b7f2e548430b0034d809da4`.

*  <var>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:

```none {:.devsite-disable-click-to-copy}
$ ffx component storage make-directory c1a6d0aebbf7c092c53e8e696636af8ec0629ff39b7f2e548430b0034d809da4::/my-new-example-dir
```

<!-- Reference links -->

[storage-capabilities]: /docs/concepts/components/v2/capabilities/storage.md
[directory-capabilities]: /docs/concepts/components/v2/capabilities/directory.md
[component-moniker]: /docs/concepts/components/v2/identifiers.md#monikers
[ffx-component-storage]: https://fuchsia.dev/reference/tools/sdk/ffx#storage
[ffx-component-show]: ./view-component-information.md#get-detailed-information-from-a-component
[component-id-index]: /docs/development/components/component_id_index.md
[namespace]: /docs/concepts/process/namespaces.md
[zsh]: https://zsh.sourceforge.io/
[fish]: https://fishshell.com/