saasframe configs cache

yarn saasframe configs cache is the operator-facing cache tool for Open Saasframe. It exposes the same CRUD/widget segment view as the Backend → Configuration → Cache admin page and adds lower-level purge modes for tags, exact keys, identifier tokens, and key patterns.

The command is discovered through the generated CLI registry rather than being hard-coded into the root binary. For the full pipeline, see Generator architecture.

Usage

# Show tenant-scoped CRUD/widget cache statistics
yarn saasframe configs cache stats --tenant <tenantId>

# Purge everything in one scope
yarn saasframe configs cache purge --all --tenant <tenantId>

# Purge one CRUD/widget segment
yarn saasframe configs cache purge --segment admin-nav --tenant <tenantId>

# Purge by cache tag, exact key, identifier token, or glob pattern
yarn saasframe configs cache purge --tag nav:sidebar:user:<userId> --tenant <tenantId>
yarn saasframe configs cache purge --key nav:sidebar:en:<userId>:<tenantId>:<orgId> --tenant <tenantId>
yarn saasframe configs cache purge --id <userId> --tenant <tenantId>
yarn saasframe configs cache purge --pattern 'nav:*' --all-tenants

# Recommended structural cleanup after module/page/sidebar changes
yarn saasframe configs cache structural --all-tenants

Commands

Command	What it does	Typical use
stats	Shows CRUD/widget cache segments for the selected scope.	Verify what is cached before deleting anything.
purge --all	Clears every cache key in the selected scope.	Emergency cleanup or cold-reset of one tenant/global scope.
purge --segment <segment>	Deletes only one CRUD/widget cache segment.	Match the admin page's "Purge segment" behavior.
purge --tag <tag1,tag2>	Deletes keys attached to one or more cache tags.	Clear RBAC, sidebar, or module-level tag groups.
purge --key <key1,key2>	Deletes exact cache keys.	Surgical cleanup when you already know the key names.
purge --id <token1,token2>	Deletes every key whose name contains one of the supplied tokens.	Clean user/entity-specific nav cache without knowing full keys.
purge --pattern <glob>	Deletes every key matching a glob.	Purge a family such as nav:* or `crud
structural	Alias for purging nav:* across the chosen scopes.	Run after enabling/disabling modules or changing pages/sidebar navigation.

Scope Flags

Flag	Meaning	Notes
--tenant <tenantId>	Operate inside one tenant cache scope.	Best for tenant-local navigation or CRUD caches.
--global	Operate only on the global cache scope.	Useful for global metadata/config caches.
--all-tenants	Iterate the global scope and every active tenant.	Recommended for structural navigation changes in development.

If you omit a scope flag, the command uses the global cache scope only.

Dry Runs and JSON Output

• Add --dry-run to preview what would be removed without deleting anything.
• Add --json to get machine-readable output for automation or CI logs.

Example:

yarn saasframe configs cache purge --pattern 'nav:*' --all-tenants --dry-run --json

Structural Change Workflow

Use the structural shortcut any time the generated app chrome can become stale:

• enabling or disabling modules in src/modules.ts
• adding or removing backend/* or frontend/* page files
• changing sidebar or settings/profile menu injection
• adjusting navigation-related ACL exposure that affects sidebar composition

Recommended sequence:

yarn generate

yarn generate already performs a best-effort structural purge after successful generation. Run the explicit cache command again when you want to repeat the purge manually, target a fresh environment, or verify the command output directly:

yarn saasframe configs cache structural --all-tenants

Notes

• stats and purge --segment operate on the same CRUD/widget segment model exposed by the admin cache page.
• purge --tag reports deleted counts, but it cannot list matched keys first because the cache interface does not expose a reverse tag index.
• purge --id is intentionally fuzzy. It is useful for navigation keys such as nav:sidebar:...:<userId>:..., but it can match multiple keys if the token appears in several names.

For internals, see the cache CLI architecture page.