<!--
SPDX-FileCopyrightText: 2025 Helmholtz-Zentrum hereon GmbH

SPDX-License-Identifier: CC-BY-4.0
-->

(usage)=
# Usage examples

(usage-cli)=

## CLI examples

(usage-cli-single)=

### Upload a single file to a workspace
Upload a single file to a workspace on the elements machine at
`/data/snfs1/.projects/test-production/test-workspace/`:

```bash
elements-http-upload -t <api-token> -H https://<elements-host> \\
  my-test-file:/data/snfs1/.projects/test-production/test-workspace/
```

The API token can be obtained on your profile page of your elements
installation, the host is the domain of your elements installation
(e.g. hcdc-mams.hereon.de). If you omit the file name in the remote
location (such as in this case), the file name of the local file (here
`my-test-file`) will be used. Note that the trailing slash is
important in this case

(usage-cli-multiple)=

### Upload multiple files to the same directory
Upload multiple files to the same directory with the [-d]{.title-ref}
option:

```bash
elements-http-upload -t <api-token> -H https://<elements-host> \\
  -d /data/snfs1/.projects/test-production/test-workspace/ \\
  my-first-test-file my-second-test-file
```

The `-d` option (or `--target-root`) allows you to avoid repeating the
root in the remote elements installation. You can also still use
relative paths for the `REMOTE-DEST` which will then be prefixed by
the *target root*:

```bash
elements-http-upload -t <api-token> -H https://<elements-host> \\
  -d /data/snfs1/.projects/test-production/test-workspace/ \\
  my-first-test-file:target-folder-1/ \\
  my-second-test-file:target-folder-2/my-second-test-file-remote
```

(usage-cli-directory)=

### Upload an entire directory
Upload an entire directory with `-r`:

```bash
elements-http-upload -r -t <api-token> -H https://<elements-host> \\
    local-folder:/data/snfs1/.projects/test-production/test-workspace/remote-folder
```

(usage-api)=

## Python API usage example

You can also directly call the {func}`~elements_http_upload.upload.upload`
function to upload the files from within python. This function takes the
files to upload and the connection settings and performs the update.

The arguments to this functions can be strings as in the
{ref}`CLI demo above <usage-cli-single>`, or a dictionary with `source` and
`target` being set. The keyword arguments are what is suitble for the
{class}`elements_http_upload.models.UploadSettings` model (i.e. including
everything from the {class}`elements_http_upload.models.ConnectionSettings`
model). Here is an example uploading two files, one configured as a string and
one configured as a dictionary:

```python
from elements_http_upload import upload

source_target_str = "my-test-file:/data/snfs1/.projects/test-production/test-workspace/my-test-file"
source_target_dict = {
    "source": "my-test-file2",
    "target": "/data/snfs1/.projects/test-production/test-workspace/my-test-file2",
}

upload(
    source_target_str,
    source_target_dict,
    host="https://<elements-host>",
    api_token="<api-token>",
    silent=True,  # prevents the progress bar
)
```

(usage-configuration)=

## Configuration

In the examples above we set the _token_ and _host_ explicitly via
the command line/script. You can however configure these settings also using
environment variables. The {class}`~elements_http_upload.models.UploadSettings`
and {class}`elements_http_upload.models.ConnectionSettings` models are
configured as such. You just have to prefix the attribute with
`ELEMENTS_UPLOAD_`. So setting the environment variable `ELEMENTS_UPLOAD_TOKEN`
is the same as using the `-t` option, or in other words

```bash
ELEMENTS_UPLOAD_TOKEN=<api-token> ELEMENTS_UPLOAD_HOST=https://<elements-host> \\
  elements-http-upload -d /data/snfs1/.projects/test-production/test-workspace/ \\
  my-first-test-file:target-folder-1/
```

is the same as

```bash
elements-http-upload -t <api-token> -H https://<elements-host> \\
  -d /data/snfs1/.projects/test-production/test-workspace/ \\
  my-first-test-file:target-folder-1/
```