ecBox CLI : sitesctl¶

Several tools are avaiable to manage the contents of ecBox site.

Either use ECMWF in-house developed command line tool called sitesctl as documented here https://sites.ecmwf.int/docs/sites/cli/ or use rclone.

This page shows how to use command line to manage the contents on the ecBox site. We will use sitesctl to manage ecBox contents

Install sitesctl¶

sitesctl tool is available https://get.ecmwf.int/service/rest/repository/browse/sites-cli/ Simply download the latest version for your operating system to start using it.

The following example shows installing the sitesctl tool on linux by downloading the binary in the ~/bin/sitesctl folder and making it executable. Make sure ~/bin/sitesctl is your $PATH.

❯ mkdir -p ~/bin
❯ curl -o ~/bin/sitesctl -L "https://get.ecmwf.int/service/rest/v1/search/assets/download?sort=name&direction=desc&q=linux&repository=sites-cli"
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0
100 13.1M  100 13.1M    0     0   115M      0 --:--:-- --:--:-- --:--:--  115M

❯ chmod +x ~/bin/sitesctl

Help¶

Pass the -H argument to sitesctl to get the list of options available with the tool.

❯ sitesctl -h
VERSION:
   20260603.1645

NAME:
   SitesCTL - Manage your sites from the command line

USAGE:
   SitesCTL [global options] command [command options]

DESCRIPTION:
   The Sites Command Line Interface (CLI) lets you create and manage sites and their content directly from the terminal

COMMANDS:
   auth         Authentication commands
   config       Manage CLI configuration
   list         List sites
   create       Create a site
   delete       Delete a site
   misc         Miscellaneous utility commands
   site         Manage a site
   upgrade-cli  Upgrade the CLI
   help, h      Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --help, -h  show help

FULL DOCUMENTATION:
    https://sites.ecmwf.int/docs/sites/

SUPPORT:
    https://support.ecmwf.int

Authentication¶

First step before working with the sitesctl tool is to authenticate to ecBox site using token provided to you by ECMWF staff.

Upon successful authentication, the sites token is stored in the sitesctl configuration file located in the user’s home directory (~/.sites-cli). This allows the user to run sitesctl commands without needing to provide authentication details each time.

Authenticate with ecBox using token with the auth sub-command as follows. The token permissions (RO/RW) will decide the operations allowed by the user.

Note

Command syntax: sitesctl auth site-token --space ecbox --name {ecbox_site_name} --token {ecbox_site_token}

❯ sitesctl auth site-token --space ecbox --name demo4cli --token 92QWuNB0Rf5P5QApVy1SMgjP.....lz6lGejQogCHlok6CoB

Successfully set Token for site 'demo4cli' with token '92QWuNB0Rf5P5QApVy1SMgjP.....lz6lGejQogCHlok6CoB'

Uploading contents¶

To upload files/folders to the ecBox site, use content upload sub-commands as follows.

In the example below, we are uploading a file (cmdbuild.log) from a local machine to the ecBox site demo4cli . Note that the --space ecbox argument is required to identify the ecBox site among all other sites created by you.

❯ sitesctl site --space ecbox --name demo4cli content upload --source /home/marp/Downloads/cmdbuild.log 

Will upload the following file:
 - /home/marp/Downloads/cmdbuild.log

Are you sure you want to proceed? y[n]: y

✓  Finished

Status  Message
OK      Path 'cmdbuild.log' created.

To upload files inside a folder, simply replace the file name by the folder name.

❯ sitesctl site --space ecbox --name demo4cli content upload --source /home/marp/Downloads/ecbox_demo

the above command uploads files from the folder ecbox_demo to the ecBox site demo4cli and not the sub-folders)

sitesctl supports wildcards: for instance, if you want to upload only pdf files from a folder, you can use:

❯ sitesctl site --space ecbox --name demo4cli content upload --source /home/marp/Downloads/ecbox_demo --match *.pdf

Warning

If a file with the same name already exists at a given path in an ecBox site, using content upload to upload another file to that path will overwrite the existing file.

More examples¶

Consider the ecbox_demo on a local machine with the contents as follows:

❯ tree /home/marp/Downloads/ecbox_demo
/home/marp/Downloads/ecbox_demo
├── assessment-of-the-arctic-weather-satellite-in-nwp.pdf
├── delete.gif
├── ifs
│   └── 81623-ifs-documentation-cy49r1-part-i-observations.pdf
├── newsletter
│   ├── 2024
│   │   └── 81618-ifs-upgrade-improves-near-surface-wind-and-temperature-forecasts.pdf
│   ├── 81666-newsletter-no-184-summer-2025.pdf
│   └── http_redirects.yml
├── splunk-download-links.txt
└── upload.gif

3 directories, 8 files

For brevity, first part of the upload command sitesctl site --space ecbox --name demo4cli content upload is referred as $UPLOAD_COMMAND in the following examples.

Command:
$UPLOAD_COMMAND --source /home/marp/Downloads/ecbox_demo --destination ecbox_demo
Effect:
A directory ecbox_demo will be created in ecBox site (if needed) and the following files will be uploaded
```
ecbox_demo/assessment-of-the-arctic-weather-satellite-in-nwp.pdf
ecbox_demo/delete.gif
ecbox_demo/splunk-download-links.txt
ecbox_demo/upload.gif
```
Command:
$UPLOAD_COMMAND --source /home/marp/Downloads/ecbox_demo --recursive --destination my_targets
Effect:
A directory my_targets will be created in ecBox site which is a copy/clone of ecbox_demo on the local machine

Command:
$UPLOAD_COMMAND --source /home/marp/Downloads/ecbox_demo --match *.gif
Effect:

Will upload the following files (2):
   - /home/marp/Downloads/ecbox_demo/delete.gif
   - /home/marp/Downloads/ecbox_demo/upload.gif

Command:
$UPLOAD_COMMAND --source /home/marp/Downloads/ecbox_demo --match *.pdf --recursive
Effect:

    Will upload the following files (4):
    - /home/marp/Downloads/ecbox_demo/assessment-of-the-arctic-weather-satellite-in-nwp.pdf
    - /home/marp/Downloads/ecbox_demo/ifs/81623-ifs-documentation-cy49r1-part-i-observations.pdf
    - /home/marp/Downloads/ecbox_demo/newsletter/81666-newsletter-no-184-summer-2025.pdf
    - /home/marp/Downloads/ecbox_demo/newsletter/2024/81618-ifs-upgrade-improves-near-surface-wind-and-temperature-forecasts.pdf

Listing contents¶

To list the contents of the ecBox site, use content list sub-commands as follows. Replace the ecBox site name demo4cli with yours.
For brevity, first part of the upload command sitesctl site --space ecbox --name demo4cli content list is referred as $LIST_COMMAND in the following examples.

# List all the contents of the ecBox site
$LIST_COMMAND --match "*" --recursive

# List everything under the folder my_targets
$LIST_COMMAND --path my_targets

# List only the top level directories
$LIST_COMMAND --type d

Downloading contents¶

To download a file from the ecBox site, use content download sub-commands as follows. Replace the ecBox site name demo4cli with yours.
For brevity, first part of the upload command sitesctl site --space ecbox --name demo4cli content download is referred as $DOWNLOAD_COMMAND in the following examples.

# Download a single file
$DOWNLOAD_COMMAND --path /path/to/file/on/ecbox/site/filename.pdf

# Download several file matching a given pattern
$DOWNLOAD_COMMAND --path /path/to/folder/on/ecbox/site --match=*.pdf --recursive

# Download a single folder
$DOWNLOAD_COMMAND --path /path/to/folder/on/ecbox/site/foldername

# Download a single folder and all its sub-folders
$DOWNLOAD_COMMAND --path /path/to/folder/on/ecbox/site/foldername --recursive

Deleting contents¶

To delete the contents of the ecBox site, use content delete sub-commands as follows. Replace the ecBox site name demo4cli with yours.
For brevity, first part of the upload command sitesctl site --space ecbox --name demo4cli content delete is referred as $DELETE_COMMAND in the following examples.

# Delete all the gif files under the folder my_targets
$DELETE_COMMAND --match *.gif  --path my_targets

# Delete the folder my_targets/newsletter/2024/
$DELETE_COMMAND --path my_targets/newsletter/2024

Tip

Also check rclone if you do not want to use sitesctl https://sites.ecmwf.int/docs/public/services/ecbox/overview/