KI 3743 New SAFE tool: import/export with NORTRE CLI
(updated )
What is NORTRE CLI?
NORTRE CLI is a specialized command-line tool developed by SAFE at the University of Bergen (UiB) for import/export of files through in the SAFE servers. The tool interacts with SAFE File API: KI 3742 New feature: data transfer via SAFE File API. The packaged is published at Python Package Index (PyPi) under the name nortre-cli.
Requirements for using NORTRE CLI
- You must be an existing SAFE user with access to import and/or export.
- You must have specific access to the SAFE File API. If you do not have this access, please request it via a ticket to UiB Help, including your username and server name.
- You must have access to and be connected to the UiB SAFE VPN. Further details on this can be found here: KI 0407 Connecting to a SAFE server.
- You need a terminal where you can enter commands. All operating systems come with a default version. For example "PowerShell" on Windows or "Terminal" on Mac, among others.
- Python must be installed on your computer. You can install it for your specific operating system by downloading it from the official Python website.
Guide to using NORTRE CLI
An instruction manual for the various commands is available on the website for the PyPi package, but we will also cover them here.
Installation
Open a terminal on your computer. It is a good idea to verify that Python has been installed correctly before proceeding.
Install the NORTRE CLI tool from Python Package Index (PyPI) by entering the following command: pip install nortre-cli
An installation process should then begin, which will download the necessary package.
To verify that the installation was successful, type safe-cli into your terminal. It should display a menu with various options.
Get access token
First we need a key to show that we have the necessary permissions to send requests.
Enter safe-cli get-token in your terminal. This will automatically open your web browser, and you will be prompted to authenticate.
After authentication you will receive a access token in your web browser.
In the image the key has been masked with a black box, but typically it consists of a long string of letters and numbers. You need to copy this text and press the Enter key to input it into NORTE-CLI.
The terminal will wait for you to do this, displaying the message "Paste your JWT token here: ...".
Important: This key will only be valid for 1 hour. After that, you must repeat this step to obtain a new access token.
Importing
Once you have obtained an access token as described above, you can import files to the SAFE server using the commands shown below. Remember to keep the UiB SAFE VPN active during the process.
- Interactive importing:
Enter safe-cli import-file to run an interactive import session. You can also run safe-cli interactive and then select the import option.
You will then be asked for the server name, which you enter directly into the terminal. A file explorer will open automatically, allowing you to select the file(s) you wish to import to the SAFE server. You will then be presented with a overview of the imports before confirming the process. You will also be shown a summary of which files got imported and not.
Once you confirm by typing "yes", the import process will begin. The process may take some time depending on file sizes. You will receive feedback regarding which files were imported and any error messages.
After importing, the file(s) will appear in the import folder on the selected SAFE server.
Specifically, it is the folder named safe_file_api_import, provided you have import access.
- Non-interactive importing:
There is also an option for non-interactive importing of files into the SAFE machine, which initiates the import process immediately.
To do this, enter the full command on a single line: safe-cli import-file --server <servername> --filename <file-path>
Full example with multiple import files: safe-cli import-file --server myserver --filename "C:\Users\myusersname\Documents\blabla.txt" --filename "C:\Users\myusername\Documents\Hi.txt"
This will work as long as you enter the server name and file path correctly.
File path formats vary by operating system (the example above uses the Windows format), but the command handles different formats without issues.
Remember to ensure you have a valid token and that the SAFE VPN is active, otherwise the operation will fail.
- More on importing:
The import will fail if the file is not found or is empty. You will also receive an error message if the filename already exists in the import folder on the SAFE server.
Exporting
As with importing, once you have obtained a token, you can export files from the SAFE server to your local PC using the commands specified in the tool. Remember to keep the UiB SAFE VPN enabled throughout the process.
The export process requires that you have placed the files you wish to retrieve into the safe_file_api_export folder on your SAFE server.
- Interactive exporting:
Enter safe-cli export-file to run an interactive export session. Alternatively, you can run safe-cli interactive and then select the export option.
You will then be prompted to enter the server name directly into the terminal. Once validated, you will see a list of the files contained in the folder on the SAFE machine. Enter the filename or the number corresponding to the file you wish to retrieve. A file explorer window will open automatically, allowing you to choose the destination on your local machine where the file should be saved. Finally, you will be presented with a summary of the export operation before confirming the process.
Once you have provided approval by typing "yes", the export process will begin. Depending on the file size, this process may take some time. Once the export is complete, the file will appear at the specified file path on your local machine.
- Non-interactive export:
There is also an option to export a file from the SAFE machine in a non-interactive manner, which initiates the export process immediately.
To do this, enter the entire command on a single line: safe-cli export-file --server <servername> --filename <file name> --output-dir <output directory path>
Full example: safe-cli export-file --server myserver --filename "New Text Document.txt" --output-dir "C:\Users\myusername\Downloads"
This will work as long as you correctly provide the server name, file name, and the destination file path. File path formats vary between operating systems (the example above uses the Windows format), but the command should handle different formats without any issues.
Also, ensure that you have a valid token and that the SAFE VPN is enabled, otherwise the operation will fail.
- More on exporting:
Additional information
- Although a token is valid for 1 hour, file transfers will not be cancelled if the data transfer has already begun. This restriction applies only to new requests.
- You can import or export files up to 950 GB at a time. However, please note that larger files will take longer to process.
- There is a 1-day timeout, meaning that if a file transfer takes longer than 24 hours, it will be cancelled.
- The screenshots may differ slightly from the final interface following future updates, but the commands should remain the same.