Getting started

This section describes how to set up the SPLENT development environment: create the workspace, clone the repositories, initialize Docker, and create a first product. After completing these steps, the environment is ready for development.

Table of contents

  1. System requirements
  2. Workspace
  3. Configure SSH access to GitHub (DiversoLab developers only)
  4. Clone repositories
  5. Setting up the Docker environment
  6. Create a sample product
  7. Synchronize features
  8. Generate environment variables
  9. Launch product and features
  10. Start product

System requirements

SPLENT runs natively on Linux and macOS.

If you are using Windows, you must work inside WSL (Windows Subsystem for Linux).
All commands in this guide must be executed inside the Linux terminal provided by WSL, not in PowerShell.

Before continuing, ensure that the following tools are installed:

  • Git
  • Docker
  • SSH configured with GitHub
  • GNU Make

On Windows, also ensure that:

  • WSL is installed
  • Docker Desktop is integrated with WSL
  • Git is configured

👉 See the detailed Windows setup guide: Windows development environment (WSL + Docker + Git)

Workspace

SPLENT is not a single repository, but rather an ecosystem composed of two basic components: the SPLENT Framework and the SPLENT CLI . For everything to work coherently, it is necessary to have a single root directory where all repositories are placed and where the products and functions that are created are also stored.

That root directory is the workspace.

First, create it:

mkdir splent_workspace
cd splent_workspace

Configure SSH access to GitHub (DiversoLab developers only)

This step is only required for DiversoLab developers who have write access to the SPLENT repositories and need to modify the CLI, the framework, or other core components of the ecosystem. If you are only using SPLENT to develop products, you can skip this section.

To clone the SPLENT repositories using SSH, configure an SSH key.

Generate a key:

ssh-keygen -t ed25519 -C "your_email@example.com"

Start the SSH agent and add the key:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

Copy the public key and add it to your GitHub account:

cat ~/.ssh/id_ed25519.pub

Then add the key in:

GitHub → Settings → SSH and GPG keys → New SSH key

Test the connection:

ssh -T git@github.com

If everything is configured correctly, GitHub will confirm the authentication.

Clone repositories

SPLENT is divided into two separate repositories. Each one plays a different role within the ecosystem, and all of them must be present in the workspace for the SPLENT CLI and SPLENT Framework to function correctly.

Clone them into the workspace:

git clone https://github.com/diverso-lab/splent_framework.git
git clone https://github.com/diverso-lab/splent_cli.git

If you are an authorized SPLENT developer and have SSH access to the repositories, clone them using SSH instead of HTTPS:

git clone git@github.com:diverso-lab/splent_framework.git
git clone git@github.com:diverso-lab/splent_cli.git

Once cloned, your workspace will have this minimal structure:

splent_workspace/
  splent_framework/
  splent_cli/

Setting up the Docker environment

The SPLENT ecosystem uses its own Docker environment to run the SPLENT CLI and products in an isolated and consistent manner. To activate it for the first time, enter the splent_cli repository and run:

cd splent_cli
make setup

These actions set up the entire SPLENT ecosystem in Docker and take us to the SPLENT CLI . Once inside, you will see a prompt similar to:

(detached) /workspace$

At that point, you are already working within the official SPLENT environment, with Python, Docker, and all paths configured correctly. From there, you can create products, features, and run any SPLENT command.

Create a sample product

When you first enter the SPLENT CLI , you will see that it appears in detached mode. This simply means that the SPLENT CLI is not yet associated with any product within the workspace.

To create a test product called sample_splent_app, run:

splent product:create sample_splent_app

This command generates the basic scaffolding for the product within the workspace:

  • Standard folder structure
  • Product pyproject.toml file
  • Initial templates
  • Empty feature registry
  • Minimum configuration for the product to run

Once created, you must tell the SPLENT CLI that this will be the active product:

splent product:select sample_splent_app

From that moment on, the prompt will change to reflect that you are working within the product:

(sample_splent_app) /workspace$

Everything you do with the SPLENT CLI (create features, configure the product, generate builds, etc.) will now apply to sample_splent_app. If you want to switch products in the future, you just need to use splent product:select <product_name> again.

Synchronize features 

splent product:sync

This command downloads the features declared in pyproject.toml using their namespace and stores them in .splent_cache.

Generate environment variables

Each feature can provide a .env.example.dev, and the product also has its own. For development work, SPLENT allows you to generate and unify all these variables into a single .env.

splent product:env --generate --all --dev

This creates (or updates) the .env.example.dev files generated from all features and the product.

splent product:env --merge --dev

This creates the final .env file for development by combining all variables, respecting the correct order (product > features).

Launch product and features

Both the product and features can have associated docker-compose.yml files. The following command launches everything:

splent product:up --dev

Start product

Finally, we must start the product’s Docker container.

splent product:run --dev

To find out which port our product is running on, we launch:

splent product:port

We open the browser and navigate to localhost:<port>.