# SendCrypt CLI SendCrypt CLI (Command Line Interface) for SendCrypt is a wrapper around third-party libraries that allows you to send encrypted data through SFTP in the same manner as SendCrypt Desktop Application. If you want to integrate SendCrypt in your bioinformatics pipeline, it’s the perfect solution. :::info **Note:** The SendCrypt CLI is recommended for advanced users as it requires more configuration and technical knowledge. ::: :::warning SendCrypt CLI is only supported on **MacOS** and **Linux**. ::: # Pre-requisites Contrary to SendCrypt Desktop Application, SendCrypt CLI is a set of **bash** scripts which act as wrappers around different third-party libraries. Therefore, you need to make sure that those libraries are properly installed. :::warning While in theory, the CLI should work with previous versions of the libraries, we highly recommend to install the latest version of those libraries. ::: You will need to have the following libraries installed: * [Bash](https://www.gnu.org/software/bash/) * [Git](https://git-scm.com/) * [GnuPG](https://gnupg.org/) * [SSH](https://www.openssh.com/) MacOS specific pre-requisites: * [gtar](https://www.gnu.org/software/tar/) * [shasum](https://ss64.com/osx/shasum.html) Linux specific pre-requisites: * [tar](https://www.gnu.org/software/tar/) * [sha256sum](https://www.gnu.org/software/coreutils/manual/html_node/sha2-utilities.html) # Installation SendCrypt CLI is installed by running one of the following commands in your terminal. You can install this via the command-line with either curl, wget or another similar tool. | Method | Command | |--------|---------| | **curl** | `sh -c "$(curl -fsSL https://gitlab.sib.swiss/clinbio/sendcrypt/sendcrypt-cli/-/raw/main/tools/install.sh)"` | | **wget** | `sh -c "$(wget -qO- https://gitlab.sib.swiss/clinbio/sendcrypt/sendcrypt-cli/-/raw/main/tools/install.sh)"`\` | | **fetch** | `sh -c "$(fetch -o - https://gitlab.sib.swiss/clinbio/sendcrypt/sendcrypt-cli/-/raw/main/tools/install.sh)"`\` | Now that the CLI is installed, you will need to modify your `PATH` variable, so that the command `sendcrypt` will be available in your terminal. To make the sendcrypt command available in your terminal, you need to add the following line to your \~/.bashrc file: ```bash export PATH="$HOME/.sendcrypt:$PATH" ``` If you are using zsh, you need to add the following line to your \~/.zshrc file: ```bash export PATH="$HOME/.sendcrypt:$PATH" ``` Then, run the following command: ```bash source ~/.bashrc ``` or ```bash source ~/.zshrc ``` # Configuration To be able to send data, the CLI needs to have access to some configurations, such as the SFTP host, the GPG recipient etc. All those values are stored in a **profile** (similar to a project in SendCrypt Desktop Application). When installing SendCrypt, a default profile is created. To modify it, open the `default.env` file located in the `$HOME/.sendcrypt/profiles` directory and modify the following parameters: * `SENDCRYPT_SFTP_USER` is the username used to connect to the SFTP server. * `SENDCRYPT_SFTP_HOST` is the hostname of the SFTP server. * `SENDCRYPT_SFTP_PORT` is the port used to connect to the SFTP server (22 by default). * `SENDCRYPT_SFTP_REMOTE_PATH` is the path to the remote directory where the files will be uploaded. * `SENDCRYPT_SSH_KEY` is the path to the SSH key used to connect to the SFTP server. * `SENDCRYPT_GPG_SENDER` is the email address of the GPG key used to sign the metadata file. * `SENDCRYPT_GPG_RECIPIENT` is the email address of the GPG key used to encrypt the files. * `SENDCRYPT_GPG_PASSPHRASE` is the passphrase of the GPG key used to sign the metadata file. * `SENDCRYPT_PROJECT` is the name of the project. * `SENDCRYPT_API_URL` is the URL to use to send the notification upon a successful transfer (optional). :::info **Note:** If you only need one profile/project, we recommend to modify the `default.env` file and not creating a new profile as by default, the `default.env` file is used. You can specify a different profile by using `-p` or `—profile` option (see below). ::: ## Authentication The CLI provides an authentication module to send notifications to https://sendcrypt.sib.swiss upon successful transfers. It is **highly recommended** to configure it as it will allow the receiver to be notified whenever you send data. Make sure that you have an active account on https://sendcrypt.sib.swiss before proceeding further. ### Signing in with your credentials (without 2FA) :::warning **Note:** The following steps should only be used if **2FA is not active**. If 2FA is active, scroll down to follow the steps “Signing in with a token” (with 2FA) ::: Start by running the following command: ```bash sendcrypt login ``` You will be prompted with questions asking you to fill the required values (the email and password that you used to register on https://sendcrypt.sib.swiss). If everything went well you should see the message `Login successful`. If not, make sure to check the error output. ### Signing in with a token (with 2FA) :::warning **Note:** The following steps should only be used if **2FA is active**. If 2FA is not active, scroll up to follow the steps “Signing in with your credentials (without 2FA)”. ::: Start by heading to your [SendCrypt account](https://sendcrypt.sib.swiss/settings/authentication). You should see the following section: ![](https://clinbiokb.sib.swiss/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzLzEyNzQ1MDFhLWRiM2MtNDkwMS05ZGVhLTZiYzMwMmVhNTBjYy8xNGRjYWRhNi04YzE5LTRhZjUtOTRhMC05MjI4YzYzYTlhN2MvU2NyZWVuc2hvdCAyMDI0LTAzLTA2IGF0IDE2LjI0LjIyLnBuZyIsInR5cGUiOiJhdHRhY2htZW50IiwiaWF0IjoxNzkwODIwOTAwLCJleHAiOjE3OTA5MDczMDB9.8xX2K-TtGt6EwQEpYB_QblRa2fSbgePTM-Nn52_xxFo " =748x228")Click on “Generate new token”, then fill the name with something like `SendCrypt CLI`, select an expiration delay (you can select “No expiration” if you don’t want to re-authenticate when your token is expired). ![](https://clinbiokb.sib.swiss/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzLzEyNzQ1MDFhLWRiM2MtNDkwMS05ZGVhLTZiYzMwMmVhNTBjYy9mMGY2MGY1Zi1jMDlhLTQwMjEtOTY4Ny0wNmZhYzg2YjQ4ODAvU2NyZWVuc2hvdCAyMDI0LTAzLTA2IGF0IDE2LjI2LjI5LnBuZyIsInR5cGUiOiJhdHRhY2htZW50IiwiaWF0IjoxNzkwODIwOTAwLCJleHAiOjE3OTA5MDczMDB9.2s9r5qcx2u73BIRoJ1Cj2HqeOFmGBI6TOdrsJVM8txM " =814x504")Finally click on “Generate token”. You will now see your newly generated token. **Make sure to copy the token and store it** as you won’t be able to see it again. Then, run the following command: ```bash sendcrypt login ``` You will be prompted with questions asking you to fill the required values. Use the email that you used to register on https://sencrypt.sib.swiss and use the previously generated token as your password. If everything went well you should see the message `Login successful`. If not, make sure to check the error output. ### Signing out If required, you can easily sign out by using the following command: ```bash sendcrypt logout ``` ## Configuring SSH access The CLI uses the SFTP protocol to transfer data but is only configured to authenticate by using a SSH key pair. :::warning If you **have already a SSH key pair generated with no password,** you can skip the following step. ::: ### Generating a SSH key pair To generate a new SSH key pair, use the following command: ```javascript ssh-keygen -t rsa -b 4096 -C [your-email] ``` :::info **Note:** The CLI does not support using a SSH key pair protected with a passphrase. Make sure **lea****ve blank the passphrase** when creating your SSH key pair. ::: ## Register your SSH public key Once the keys have been generated you will need to share your public key directly with your recipient or register your public key on (recommended way). Start by copying your SSH public key. **For macOS:** ```javascript cat ~/.ssh/your_key.pub | pbcopy ``` **For Linux (using xclip):** ```javascript cat ~/.ssh/your_key.pub | xclip -sel clip ``` Then, head to your [SendCrypt account](https://sendcrypt.sib.swiss/settings/keys) where you should see your current SSH and GPG keys. ![](https://clinbiokb.sib.swiss/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzLzEyNzQ1MDFhLWRiM2MtNDkwMS05ZGVhLTZiYzMwMmVhNTBjYy8wNzIyZDE1NC1mYjQ3LTQ2MjYtYjY4NC1mYmQyMzIyYzYyZWEvU2NyZWVuc2hvdCAyMDI0LTAyLTE0IGF0IDE0LjA2LjI5LnBuZyIsInR5cGUiOiJhdHRhY2htZW50IiwiaWF0IjoxNzkwODIwOTAwLCJleHAiOjE3OTA5MDczMDB9.R4Uzfwap_JJM-Ed2nXTfiABD0jwnHspkwyqUr04ByEQ)Then click on the **New SSH key** button, which will prompt you with a form to add your SSH public key: ![](https://clinbiokb.sib.swiss/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzLzEyNzQ1MDFhLWRiM2MtNDkwMS05ZGVhLTZiYzMwMmVhNTBjYy9kMGUzZDUzZi1lYTNhLTQxOTctOGI5OC0zOTgwNTc4Yzk2MGQvU2NyZWVuc2hvdCAyMDI0LTAyLTE0IGF0IDE0LjA4LjAzLnBuZyIsInR5cGUiOiJhdHRhY2htZW50IiwiaWF0IjoxNzkwODIwOTAwLCJleHAiOjE3OTA5MDczMDB9.lry5SbUy8t0j1u9TcOHle_eBdS2OBlGJ9JwKA_ZI8DA) You can define a title if you want and then paste your copied SSH public key in the **Key** form. Finally, click on **Add SSH key**. If everything went well, you should see a banner confirming that you have successfully added your key and your key should now appear under **Authentication keys**. ![](https://clinbiokb.sib.swiss/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzLzEyNzQ1MDFhLWRiM2MtNDkwMS05ZGVhLTZiYzMwMmVhNTBjYy9kZTJhYmQ2ZS01MzExLTQwNzUtYjhkOC1iM2NhYTk1MTMwMzkvU2NyZWVuc2hvdCAyMDI0LTAyLTE0IGF0IDE0LjA5LjE1LnBuZyIsInR5cGUiOiJhdHRhY2htZW50IiwiaWF0IjoxNzkwODIwOTAwLCJleHAiOjE3OTA5MDczMDB9.eCzi0c-pCI7yDaMw2kM6YvoJK-BBJDNXpct6YUgL2oY)Your key will be automatically shared with any project that you are part of. ## Configuring your GPG keys The CLI uses the recpient GPG key to encrypt the data and your own GPG private key to sign the metadata file. This process ensures that your data is well protected against any malicious actor. First, you will need to import your recipient GPG public key. ### Importing the project GPG key :::info This step is not required if you already imported the project GPG public key in another context. But make sure to properly configure the **trust level** as explained below. ::: When registering a profile, it is important to also add the GPG key that will be used to encrypt the files (the key belonging to the project). If you don’t have the key, ask your project administrator to share it with you. To add the key, run the following command: ```javascript gpg --import ``` Once the key has been imported, you can check that it has been added by running the following command: ```javascript gpg --list-keys ``` For the CLI to work properly, the trust level of the key must be set to ultimate. To do so, run the following command: ```javascript gpg --edit-key trust ``` Type 5 to set the trust level to ultimate and press Enter. Then confirm by typing y and pressing Enter. Finally, exit by typing quit and pressing Enter. ### Generating a GPG key pair :::warning If you **have already a GPG key pair generated,** you can skip the following step. ::: When sending files, the CLI sign the metadata file with a GPG key on your behalf so that the recipient can verify the sender's identity. You will therefore need to generate a GPG key with your email address. To generate a GPG key, run the following command: ```javascript gpg --full-generate-key ``` * At the prompt, specify the kind of key you want (we recommend using RSA and RSA). * Then, specify the key size (we recommend using 4096). * Then, specify the length of time the key should be valid (we recommend using 0, which means that the key will never expire). * Finally, verify that your selections are correct. * At the prompt, type your email address, which will be used to identify your key. * At the prompt, type a passphrase, which will be used to encrypt your private key. Make sure to store it in a safe place. ## Register your GPG public key Once your GPG keys are set up, you will need to transmit your public key to either your recipient, if you don’t have a [SendCrypt account](https://sendcrypt.sib.swiss/register), or register it under your account. Start by copying your GPG public key. **For macOS:** ```javascript gpg --armor --export your_email@example.com | pbcopy ``` For Linux (using xclip): ```javascript gpg --armor --export your_email@example.com | xclip -sel clip ``` Then, head to your [SendCrypt account](https://sendcrypt.sib.swiss/settings/keys) where you should see your current SSH and GPG keys. ![](https://clinbiokb.sib.swiss/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzLzEyNzQ1MDFhLWRiM2MtNDkwMS05ZGVhLTZiYzMwMmVhNTBjYy8wNzIyZDE1NC1mYjQ3LTQ2MjYtYjY4NC1mYmQyMzIyYzYyZWEvU2NyZWVuc2hvdCAyMDI0LTAyLTE0IGF0IDE0LjA2LjI5LnBuZyIsInR5cGUiOiJhdHRhY2htZW50IiwiaWF0IjoxNzkwODIwOTAwLCJleHAiOjE3OTA5MDczMDB9.R4Uzfwap_JJM-Ed2nXTfiABD0jwnHspkwyqUr04ByEQ)Then click on the **New GPG key** button, which will prompt you with a form to add your GPG public key: ![](https://clinbiokb.sib.swiss/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzLzEyNzQ1MDFhLWRiM2MtNDkwMS05ZGVhLTZiYzMwMmVhNTBjYy84NWYyNDllOC0wYmFhLTQ1ZWUtOGM3Yy04MjY4NGRiMmVhZTAvU2NyZWVuc2hvdCAyMDI0LTAyLTE0IGF0IDE0LjMxLjQ4LnBuZyIsInR5cGUiOiJhdHRhY2htZW50IiwiaWF0IjoxNzkwODIwOTAwLCJleHAiOjE3OTA5MDczMDB9.5u5jT2zZGSiY71WJ46TEN8gxfOqbWObnHM7HgUT_Q9c) You can define a title if you want and then paste your copied GPG public key in the **Key** form. Finally, click on **Add GPG key**. If everything went well, you should see a banner confirming that you have successfully added your key and your key should now appear under **Authentication keys**. ![](https://clinbiokb.sib.swiss/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzLzEyNzQ1MDFhLWRiM2MtNDkwMS05ZGVhLTZiYzMwMmVhNTBjYy9jZTA3MTJiMi1hM2EyLTRmZTAtOGI2Yi0xMjBlODYwYTE5ZTYvU2NyZWVuc2hvdCAyMDI0LTAyLTE0IGF0IDE0LjM0LjM1LnBuZyIsInR5cGUiOiJhdHRhY2htZW50IiwiaWF0IjoxNzkwODIwOTAwLCJleHAiOjE3OTA5MDczMDB9.MtSy4KSG73e1ykZVHTlcg7kjwSvzb07IwcmxKaaJJvE) Your key will be automatically shared with any project that you are part of. :::warning It’s important to note that if the UserID of the GPG public key does not match your current email address (which is indicated by the tag **Unverified** next to the email address, you will need to add your additional email address by following this [guide](https://clinbiokb.sib.swiss/doc/sendcrypt). If you don’t, your GPG public key will not be shared with any project that you are part of. ::: ## Adding a new profile If you will need to send data to multiple projects (different host, different project name, or different recipient), you can use multiple profiles. To add a new profile, you can run the following command: ```javascript sendcrypt profile create ``` You will be prompted with several questions asking you to fill the required values. ## Configure the temporary directory When a batch is sent, some data preparation is required such as generating the metadata, compressing, encrypting etc. By default, the CLI will use `/tmp`. If you need to override this setting, simply set the `TMPDIR` env variable before calling the script. # Using the CLI If everything has been properly configured as explained above, you are ready to send your first batch of data. :::warning **Note:** The CLI can only send a directory. If you need to send only one file, make sure to place your file in a directory and send the directory itself. ::: To send files, run the following command: ```javascript sendcrypt send ``` If you would like to specify a different profile, use the `-p` or `--profile` option: ```javascript sendcrypt -p send ``` The CLI also provides an additional command `prepare` that allows you to prepare the data according to the SendCrypt format without sending them. This covers scenarios such as preparing correctly the data and sending them manually yourself. To prepare files, run the following command: ```javascript sendcrypt prepare ``` If you would like to specify a different profile, use the `-p` or `--profile` option: ```javascript sendcrypt -p prepare ``` :::info The generated \***.zip** archive will be stored the current directory where you ran the command. ::: # Running diagnostics To run diagnostics, run the following command: ```javascript sendcrypt doctor ``` This will check the following: * Required libraries are installed * Required commands are available * Internet connection is available * Connection to the SFTP server is possible * Profile files are correctly encoded :::info If you are only authorizing external connections to a SFTP server and nothing else, the check of the internet connection will fail. This is **normal**. ::: # Getting updates To get updates, run the following command: ```javascript sendcrypt update ``` # Uninstalling the CLI If you would like to uninstall SendCrypt, run the following command: ```javascript bash ~/.sendcrypt/tools/uninstall.sh ``` --- **Documents** - [Getting started](https://clinbiokb.sib.swiss/s/sendcrypt/doc/getting-started-7uRWXFnHx7) - [Configure SendCrypt](https://clinbiokb.sib.swiss/s/sendcrypt/doc/configure-sendcrypt-1dhTXiOj5T) - [Send your first batch of data](https://clinbiokb.sib.swiss/s/sendcrypt/doc/send-your-first-batch-of-data-DC1mIePn6f) - [SendCrypt CLI](https://clinbiokb.sib.swiss/s/sendcrypt/doc/sendcrypt-cli-MNIRTX3KqL) - [Troubleshooting](https://clinbiokb.sib.swiss/s/sendcrypt/doc/troubleshooting-chx1lUHStZ)