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 does the following.

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.