Working with files

Your IBM® Cloud Shell workspace includes a home directory where you can temporarily work with files in your Cloud Shell sessions. You can upload or download files one at a time to your workspace through the UI, or use command-line tools to work with many files at once.

Before you begin

Enable File upload and download in the IBM Cloud console. For more information about how to enable file upload and download, see Enabling or disabling Cloud Shell features for an account.

Temporary workspace storage

Your Cloud Shell workspace includes 500 MB of temporary secure storage, which you can access through your personal home directory, /home/<user-name>. Only you can access your workspace storage, and your storage is separate for each account that you access or region where you work in IBM Cloud Shell.

Your workspace storage is shared across all of your sessions, so you can work with the same files in different session tabs. The storage persists only while your workspace is active. If you're idle in Cloud Shell for over an hour, your files and data are removed. Similarly, if you reach the usage quota or you restart Cloud Shell, Cloud Shell closes and removes your data. If you make any changes to files that you want to keep, be sure to download the files at the end of your session.

There is a known issue where your connection to Cloud Shell is lost if your reach the temporary storage limit. If this happens, the only way to fix the connection is to restart Cloud Shell, which removes all of your files. While you work in IBM Cloud Shell, avoid uploading large files and remove any unused files by using standard Linux™ commands, such as rm.

Backing up your data

Your workspace storage is temporary, and it's not intended to be used as the primary storage location for your files. Don't store business-critical or sensitive data in your workspace, and create a backup of your files outside of IBM Cloud Shell. You're responsible for your data, and your backup can help you recover in case an outage or data loss occurs for any reason. For more information about how to transfer files to create a backup, see Transferring multiple files.

Uploading files

You can upload a file to the root level of your home directory. Only a single file can be uploaded at a time.

In the IBM Cloud Shell menu bar, click the Upload icon .
Select the file that you want to upload, and click Open.

Your file is uploaded in your home directory, for example /home/<user-name>/myFile.txt. You can move or otherwise work with your files by running standard Linux™ commands. For example, you can move a myFile.txt file that you uploaded to a myFolder subdirectory by running the following command.

mv myFile.txt ./myFolder/

Although you can move files, be sure to keep all files in your workspace under your home directory, /home/<user-name>. If you move files outside of this directory, it can cause Cloud Shell to close, which removes your data.

Downloading files

You can download a file from your workspace to your local system. Only a single file can be downloaded at a time.

Find the path to the file from the command line by using standard Linux commands.

For example, you can list all files and subdirectories within your current directory.
```
ls -R
```
Or, you can search for a file name. The following command searches for files with myFile in the name.
```
find -iname *myFile*
```
In the IBM Cloud Shell menu bar, click the Download icon .
Enter the path to the file in your home directory, such as /myFolder/myFile.txt. Click Continue.

Don't include the home directory root /home/<user-name> in the file path. File paths are case-sensitive.
Follow your browser prompt to open or save the file to your computer.

Transferring multiple files

Using the Cloud Shell UI, you can upload or download only a single file at a time. If you need to transfer many files, it might take a long time to move all of them individually. Instead, use these strategies to efficiently move files between your workspace and another file system.

Create archives to move files

Before you move files, combine the files into an archive file such as a .tar, .tar.gz, or .zip so that you can move them all at once.

For example, to upload a folder of IBM Cloud administration scripts, you might compress them into a myScripts.zip file and upload them to Cloud Shell. In your Cloud Shell session, you can then run unzip myScripts.zip to extract the files.

You can do the same thing in reverse when you want to download files. For example, say you want to back up your entire Cloud Shell workspace. From your home directory, run tar -cvf myTar.tar * to create a .tar file (Mac or Linux) or run zip -r myZip.zip * to create a .zip file (Mac or Windows). Then, download the archive file from Cloud Shell and extract it on your local system.

Work from a Git repo

For projects in Git repositories, use the Cloud Shell UI to upload an SSH key so that you can connect to your Git repo. Keep a local copy of your SSH key as a backup. Then, run git clone to clone all of the repo's files to your Cloud Shell workspace. As a bonus, when you commit and push your changes to your Git repo, your changes are automatically backed up to a file system that's outside of Cloud Shell.