1. Silverfin access

Remote template development on Silverfin relies on the API capabilities of the platform. That means you'll need the necessary access rights to send and receive template information between the remote Silverfin platform and your local machine.

For Silverfin employees, you can find the credentials in our shared 1Password vault. (BSO Team CLI)

If your firm doesn't have API credentials yet:

1. Contact your Customer Success Manager and let them know you want to start using Silverfin's API.
2. We will draft an API agreement for your organisation to sign
3. Once signed, our integration engineers will contact you to ask what you want to use the API for.
4. You'll need the following scopes:
   1. administration:read
   2. administration:write
   3. financials:read
   4. financials:write
   5. workflows:read

If you already have API credentials but forgot to save them, or when you don't have the necessary scopes:

• You can contact [email protected] for an adjustment to the scopes

2. Tools to install

You will need to install or configure the following on your machine to use the liquid toolchain to the fullest. A link to the official installation instructions has been provided for each item below.

📘

Good to know

Commands in this guide are provided for Mac. The steps on Windows or Linux should be the same, but the installation process might look a bit different. Apart from our own CLI, the tools listed here are commonly used and you should be able to find help online if you need it.

1. Git

If you are already using Git, skip this step.

git --version

• Create an account on GitHub
  • Once you have an account, the admin in your organisation can add you to the relevant repositories.

2. GitHub CLI

We use the GitHub CLI to upload our SSH keys (see GIT config below) to GitHub.

• First, install the Homebrew package manager; you will need Homebrew to install the other packages (Mac/Linux only)
• The installer will ask for the admin password of your machine; press Enter once you have entered it to confirm the installation
• Note that the installation can take a little while
  • During installation, you may receive the following warning: ... is not in your PATH
    • Resolve by running the following commands:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> /Users/changethistoyourusername/.zprofile

eval "$(/opt/homebrew/bin/brew shellenv)"

• Next, test if Homebrew was installed correctly, then use the Homebrew CLI to install the GitHub CLI:

brew -v

brew install gh

• To update the GitHub CLI, run the following Homebrew command:

brew upgrade gh

2. Node.js

Check if already installed by running the command below, otherwise install Node.js from the official website.

node --version

4. Silverfin CLI

Once Node.js is installed, install the Silverfin CLI. The Silverfin command line tool will be essential when developing Silverfin templates.

npm install -g https://github.com/silverfin/silverfin-cli.git

5. VSCode

This is our recommended code editor. Make sure the app is installed in the "Applications" folder if you are using a Mac.

• Install code command
• Open the command palette in VSCode by pressing CMD + SHIFT + P
• Type install codeor shell command
• Choose the option Shell Command: install ‘code’ command in PATH

If you receive an error message, first try running uninstall codeand then reinstalling code

6. Recommended extensions (non-exhaustive)

• The best extension is, naturally, the Silverfin Development Toolkit
• Auto Close Tag
• ESLint
• Github Pull Requests
• Git Graph
• GitLens
• indent-rainbow
• YAML
• HTML CSS Support

While the use of regular extensions already adds great value to your template development, if you wish, you can also explore AI tools to take it to the next level. A note of caution: The Silverfin Templating Language (our take on Liquid) is not as common as other languages. As such, most AI tools are not trained specifically for our coding language. Nevertheless, we have found that there is value in trying out the following:

• GitHub Copilot & GitHub Copilot Chat (subscription needed)
• Cody AI (free limited version available)

3. GIT configuration

If this is your first time using Git, please follow the setup process below:

1. Link Git on your local machine to your remote Github account

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

• Set VSCode as your default editor (recommended)

git config --global core.editor code

• Verify your config is setup correctly. Additionally, you can also check where your local Git configurations are stored (optional)

git config --list
git config --list --show-origin

3.2 Set up SSH Keys

SSH Keys is the preferred method to authenticate your local machine with the remote repositories on GitHub. When pushing updates from your local repository to a remote repository, or when fetching code from a remote branch etc. you'll use the SSH Key to authenticate the transfer.

SSH Keys on Mac

• Navigate to the ssh keys folder

cd ~/.ssh

OR create the folder if it does not exist yet

mkdir ~/.ssh && cd ~/.ssh

• Generate the SSH key with the command below, adding the email address associated with your GitHub account (-t ed22519 is the algorithm used to generated the key):

ssh-keygen -t ed25519 -C "[email protected]"

• After entering the command:
  • The system will ask you for a file name, but you can leave this blank and press Enter
    • By default the system will use id_rsaor id_ed25519
  • Now you need to set a password. Be aware that:
    • You cannot recover this password. If you lose it, you will need to generate a new SSH Key
    • You will need to enter this password a lot.
    • The terminal does not give visual feedback when you're typing a password. Type the password blindly and press Enter when you're done.

SSH Keys on Windows

• Generate the SSH key with the following command:

ssh-keygen -t ed25519 -C "[email protected]"

Same remarks apply as when setting up the password on a Mac. (see above)

• Add the SSH Key to the SSH-Agent

Use Windows Powershell (run as admin) to start the SSH-Agent.

Get-Service ssh-agent | Set-Service -StartupType Automatic 

Start-Service ssh-agent

To check if the service started correctly, you can run the following:

Get-Service ssh-agent

• Configure Git to use the windows SSH-Agent

git config --global core.sshCommand C:/Windows/System32/OpenSSH/ssh.exe

3.3 Add SSH Key to GitHub account

Authenticate your GitHub account with the terminal (or command prompt etc) and upload the SSH Key you just created.

gh auth login

📘

Help

You can run the gh helpcommand to see a list of possible commands for the Github CLI.

The same works for the Silverfin CLI: silverfin --helpwill return a list of commands to run.

Next, you need to answer a few prompts.

What account do you want to log into?
 GitHub.com

What is your preferred protocol for Git operations?
 SSH

Upload your SSH public key to your GitHub account?
 (You should automatically have a proposed path to your generated SSH key)
	/Users/username/.ssh/id_rsa.pub

How would you like to authenticate GitHub CLI?
 Login with a web browser

Copy the one time code that is shown in your terminal first.
Now you can press any key inside the terminal and a browser window will open for you to login to your GitHub account.
Once you have logged in, you will receive a success message in the terminal. It should resemble the below:

✓ Authentication complete.
- gh config set -h github.com git_protocol ssh
✓ Configured git protocol
✓ Uploaded the SSH key to your GitHub account: /Users/usersname/.ssh/id_rsa.pub
✓ Logged in as GitHubUsername

To verify you are logged in to Github, run the following command:

gh auth status

4. Silverfin API configuration

You can configure the API credentials you received from Silverfin either with the codecommand or open the config file directly and add them there.

sudo code ~/.zshrc

OR

sudo nano ~/.zshrc

Making and saving changes to the file with nano requires specific key combinations.
Save changes with control(^) + X
Confirm changes with y
Finally, hit enter

• When asked for a password, provide the password you use to login to your machine.
• You will receive a text document where you can enter the client ID and the client secret.
  Enter the credentials you received from Silverfin.

export SF_API_CLIENT_ID="..."
export SF_API_SECRET="..."

• You can always test if the ID and SECRET have been stored correctly using the echo command.

echo $SF_API_CLIENT_ID
echo $SF_API_SECRET

These commands should return the strings you had saved.
If that does not work, try opening the file directly:

source ~/.zshrc