Manage the CLI environment

Everything in the SPLENT CLI Makefile — the host-side targets that prepare your .env, start the Docker container, and drop you into the CLI shell.

Table of contents

What “Manage” covers
The Makefile layout
The environment model
Pre-flight: validation that always runs
Targets at a glance
1. Lifecycle
2. .env management
Common workflows
Troubleshooting

What “Manage” covers

These commands run on the host machine, before you are inside the container. They are plain make targets — not splent subcommands — and they exist to make the environment correct and reproducible:

Generate & repair the workspace .env.
Validate it (no duplicate, malformed, or stale entries).
Start / rebuild the Docker container.
Enter the running CLI shell.

Inside the container you use splent … commands (features, products, database, …). Out here you use make …. This page is only about the latter.

The Makefile layout

The CLI repo ships a small root Makefile that includes two files:

File	Responsibility
`makefiles/Makefile.setup`	`.env` generation/repair/validation + Docker lifecycle
`makefiles/Makefile.cli`	shortcuts to enter the running container

Run make with no arguments (or make help) to list every target:

make help

The environment model

Almost everything make does revolves around one file: the workspace .env.

Where the `.env` lives

splent_workspace/
├── .env              ← the real file (git-ignored, host-specific)
├── splent_cli/
│   ├── .env.example  ← the committed template ("the egg")
│   ├── Makefile
│   └── scripts/
├── splent_framework/
└── <your products>/

The .env sits at the workspace root, one level above splent_cli/. It is created by copying the committed splent_cli/.env.example template, so there is no chicken-and-egg problem — generating it never depends on anything that needs the container or the .env itself.

The variables

Variable	Set by	Purpose
`WORKING_DIR`	template	Workspace path inside the container — always `/workspace`.
`SPLENT_HOST_PROJECT_DIR`	`fix-workdir`	Real host path of the workspace. Used so product containers (docker-in-docker) bind-mount the correct host folder.
`SPLENT_APP`	`splent product:select`	The active product. Absent = detached mode.
`SPLENT_ENV`	`splent env:set`	Target environment (`dev` / `prod`). Optional, defaults to `dev`.
`GITHUB_USER` / `GITHUB_TOKEN`	you	Credentials for cloning/releasing features over HTTPS.
`TWINE_USERNAME` / `TWINE_PASSWORD`	you	PyPI credentials for publishing.

WORKING_DIR is the path inside the container; SPLENT_HOST_PROJECT_DIR is the host path that gets mounted there. They describe the same folder from two sides — keeping them consistent is what fix-workdir guarantees.

The shell prompt reflects the `.env`

Once inside the container, the prompt tells you the product state at a glance:

Prompt	Meaning
`(detached)` `/workspace$`	No `SPLENT_APP` — no product selected.
`(my_product)` `/workspace$`	`SPLENT_APP=my_product` and the folder exists.
`(my_product?)` `/workspace$`	`SPLENT_APP` is set but the folder is missing — a dangling product. Run `make fix-app`.

Pre-flight: validation that always runs

Every lifecycle target runs scripts/preflight_cli.sh first. It checks, in order:

Docker is installed.
The Docker daemon is reachable without sudo.
Docker Compose v2 is available.
~/.gitconfig and ~/.ssh are sane for bind-mounting.
The workspace .env — duplicate/overlapping/malformed keys, a stale SPLENT_HOST_PROJECT_DIR, a dangling SPLENT_APP, and drift from the template. (This is the same logic as make env-check, embedded into the pre-flight — single source of truth.)
The container exists, is running, and has the Docker socket mounted (only when checking a specific container).

A hard problem (duplicate/malformed keys, missing .env) stops the run; a recoverable one (stale host path, dangling product) only warns and points you at the repair command.

The pre-flight runs twice during make setup: once before starting the container (full output) and once after, to verify the container itself. The second pass runs in quiet mode — it re-validates everything but only prints problems, so you never see the same green checks twice.

Targets at a glance

Lifecycle

Target	What it does
`make setup`	Full setup: ensure+validate `.env`, start Docker, enter the CLI.
`make setup-rebuild`	Tear down, rebuild images from scratch, re-enter.
`make docker-up`	Ensure `.env`, then start the container.
`make cli`	Enter the running container (day-to-day shortcut).
`make help`	List every target.

Only one target is destructive: make setup-rebuild deletes volumes and prunes Docker images. It asks for confirmation first and refuses to run unattended without FORCE=1. Every other target is safe — the .env repairs preserve all your other keys, and nothing else removes data.

`.env` management

Target	What it does
`make env-prepare`	Create `.env` from the template and repair it.
`make env-check`	Validate `.env` (duplicates, paths, dangling product).
`make fix-workdir`	Repair `SPLENT_HOST_PROJECT_DIR` / `WORKING_DIR`.
`make fix-app`	Clear a dangling `SPLENT_APP` (back to detached).
`make fix-env`	Repair workdir + app, then re-validate.
`make preflight`	Run host pre-flight checks only.

Common workflows

First time:

make setup

Day-to-day (container already built):

make cli

You moved or renamed the workspace folder:

make fix-workdir      # re-points SPLENT_HOST_PROJECT_DIR at the new path

Your prompt shows (something?) in yellow:

make fix-app          # clears the dangling product → detached

Something feels off with the .env:

make env-check        # tells you exactly what; then fix-workdir / fix-app / fix-env

After major Docker or dependency changes:

make setup-rebuild

Troubleshooting

Symptom	Cause	Fix
`Container is bound to another workspace`	`.env` host path is stale	`make fix-workdir`
Prompt shows `(name?)` in yellow	`SPLENT_APP` points to a missing folder	`make fix-app`
`Duplicate variable …`	a key is defined twice in `.env`	edit `.env`, keep one line, re-run `make env-check`
`.env not found`	the workspace `.env` was never created	`make env-prepare`
`Docker daemon is not responding`	Docker isn’t running	start Docker, re-run `make preflight`