feature:detach

Detach a versioned (pinned) feature from the active product without deleting the cached copy.

Usage

splent feature:detach <namespace>/<feature_name> <version> [--force]

Example

splent feature:detach splent-io/splent_feature_auth v1.2.7

Description

This command:

Checks that no other installed feature depends on <feature_name> (dependency guard).
Checks that the feature has not had migrations applied (migration state guard).
Removes the feature_name@version reference from [tool.splent].features in pyproject.toml.
Removes the versioned symlink at <product>/features/<namespace>/<feature_name>@<version>.
Removes the feature entry from splent.manifest.json.
Uninstalls the feature via pip uninstall in the web container and triggers Flask reload.

The running application picks up the removal automatically — no restart or product:derive needed. .splent_cache is left untouched — the versioned snapshot remains available for reuse.

Safety guards

Dependency guard

If another installed feature declares <feature_name> in its [tool.splent.contract.requires].features, the command aborts:

❌ Cannot detach 'splent_feature_auth': the following installed features depend on it:
   • splent_feature_profile
   Remove those features first, or use --force to bypass.

Migration state guard

If the feature has state migrated or active in splent.manifest.json, the command aborts:

❌ Feature 'splent_feature_auth' has migrations applied (state: active).
   Roll them back first:
   splent db:rollback splent_feature_auth --steps 999
   Or use --force to skip this check.

Roll back the feature’s migrations before detaching to avoid leaving orphaned tables in the database.

Options

Option	Description
`--force`	Skip both the dependency guard and the migration state guard. Use with care.

Requirements

A product must be selected (splent product:select).
SPLENT_APP must be set.
pyproject.toml must exist in the product root.
The feature version must be currently linked in the product.