kf tenant

Manage tenant config, locations, API keys, broadcasts, and feeds.

kf tenant acknowledge-admin-broadcast-delivery

Record recipient acknowledgement for one app feed delivery.

Record recipient acknowledgement for one app feed delivery. Version-checked and idempotent; the emitted event carries only delivery ids and status facts.

Example

kf tenant acknowledge-admin-broadcast-delivery --tenant tnt_demo --actor-type USER --actor-id usr_sam --delivery-id <value> --expected-version <value>

kf tenant cleanup-sample-data

Delete the rows the trial demo bootstrap stamped with custom_fields['karmanflow:source'] = 'trial-bootstrap' for a single tenant.

Delete the rows the trial demo bootstrap stamped with custom_fields['karmanflow:source'] = 'trial-bootstrap' for a single tenant. Lets an operator clear seeded sample data before they import their own catalog. Walks channel_availabilities, inventory_levels, product_variants, products, and locations in dependency order. Cannot touch operator-authored rows because tenant custom_fields never use the karmanflow: prefix. Idempotent on replay; a second call after a successful cleanup finds no marker rows and returns counts of 0.

Example

kf tenant cleanup-sample-data --tenant tnt_demo --actor-type USER --actor-id usr_sam

kf tenant create-api-key

Issue an environment-pinned API key for a service, agent, connector, partner, or extension.

Issue an environment-pinned API key for a service, agent, connector, partner, or extension. The key prefix is derived from the tenant environment type and the raw secret is only returned once.

Example

kf tenant create-api-key --tenant tnt_demo --actor-type USER --actor-id usr_sam --display-name <value> --subject-type <value> --subject-id <value>

kf tenant create-location

Create a Location (store, warehouse, 3PL, dropship, virtual node).

Create a Location (store, warehouse, 3PL, dropship, virtual node). Tenant-scoped uniqueness on locationRef. Idempotent by metadata.idempotencyKey; replays return the prior receipt and reject keys reused for a different locationId.

Example

kf tenant create-location --tenant tnt_demo --actor-type USER --actor-id usr_sam --location-ref <value> --name <value> --location-type <value>

kf tenant decommission-location

Terminally decommission a Location.

Terminally decommission a Location. Sets status=DECOMMISSIONED, stamps decommissionedOn and closedOn, emits location.decommissioned. Optimistic concurrency on expectedVersion. Approval required because decommissioning is irreversible and removes the site from routing eligibility.

Example

kf tenant decommission-location --tenant tnt_demo --actor-type USER --actor-id usr_sam --location-id <value> --expected-version <value>

kf tenant define-feed

Register a typed FeedDefinition catalog row.

Register a typed FeedDefinition catalog row. Tenant-scoped (or platform-shared via tenant_id '*') uniqueness on feedKey. Carries eventTypes, payload schema reference and version, requiredScopes, riskClass, default backpressure mode, and replay window. Idempotent by metadata.idempotencyKey; replays return the prior receipt and reject keys reused for a different explicit feedDefinitionId. Subscription lifecycle ships in Phase 3+.

Example

kf tenant define-feed --tenant tnt_demo --actor-type USER --actor-id usr_sam --feed-key <value> --name <value> --event-types <value> --payload-schema-ref <value> --risk-class <value> --default-backpressure-mode <value>

kf tenant delete-custom-field

Delete, tombstone, or redact a typed custom field with an auditable command receipt and CustomFieldDeleted event.

Delete, tombstone, or redact a typed custom field with an auditable command receipt and CustomFieldDeleted event. Scoped by tenant and environment.

Example

kf tenant delete-custom-field --tenant tnt_demo --actor-type USER --actor-id usr_sam --entity-type <value> --entity-id <value> --field-key <value>

kf tenant deprecate-feed-definition

Mark a FeedDefinition deprecated.

Mark a FeedDefinition deprecated. Phase 2 records deprecation through the emitted event audit trail (no schema change to feed_definitions). Optional replacementFeedKey hint. Optimistic concurrency on expectedVersion; the row's version bumps so future operations see the marker. Subscription dispatch will refuse new subs to deprecated feeds when subscription lifecycle commands land.

Example

kf tenant deprecate-feed-definition --tenant tnt_demo --actor-type USER --actor-id usr_sam --feed-definition-id <value> --expected-version <value>

kf tenant dismiss-admin-broadcast-delivery

Record recipient dismissal for one app feed delivery.

Record recipient dismissal for one app feed delivery. Version-checked and idempotent; user actors can dismiss only their own delivery unless they hold admin broadcast authority.

Example

kf tenant dismiss-admin-broadcast-delivery --tenant tnt_demo --actor-type USER --actor-id usr_sam --delivery-id <value> --expected-version <value>

kf tenant extend-trial

Self-serve trial extension.

Self-serve trial extension. Single-shot per trial: bumps trial_expires_on and trial_purges_on by +7 days, sets trial_extension_used=true, emits trial.tenant.extended. Refuses on non-trial tenants and on tenants whose purge horizon has already passed. Idempotent: subsequent calls return the current horizons with alreadyExtended=true rather than granting a second extension.

Example

kf tenant extend-trial --tenant tnt_demo --actor-type USER --actor-id usr_sam

kf tenant freeze-trial

Flip a trial tenant from ACTIVE to FROZEN at day 14 (read-only state).

Flip a trial tenant from ACTIVE to FROZEN at day 14 (read-only state). SYSTEM-only; called by the scheduler-worker when trial_expires_on <= now() on a trial=true tenant. Existing auth checks already reject sessions on non-ACTIVE tenants, which gives the read-only effect for free. Idempotent on already-frozen tenants. Refuses on non-trial or DEACTIVATED tenants.

Example

kf tenant freeze-trial --tenant tnt_demo --actor-type USER --actor-id usr_sam --reason <value>

kf tenant issue-partner-widget-token

Issue a short-lived, environment-pinned signed token for a partner embed widget.

Issue a short-lived, environment-pinned signed token for a partner embed widget. The raw bearer token is returned once; command receipts and events persist only sanitized metadata. Approval-gated: the approval is bound to commandType=IssuePartnerWidgetToken and resourceId=<tenantId>:<environmentId>, with a 1h TTL. Disposition A per the internal implementation notes.

Example

kf tenant issue-partner-widget-token --tenant tnt_demo --actor-type USER --actor-id usr_sam

kf tenant mark-admin-broadcast-delivery-delivered

Mark one queued app feed delivery as delivered for the recipient app surface.

Mark one queued app feed delivery as delivered for the recipient app surface. Version-checked and idempotent; user actors can update only their own delivery unless they hold admin broadcast authority.

Example

kf tenant mark-admin-broadcast-delivery-delivered --tenant tnt_demo --actor-type USER --actor-id usr_sam --delivery-id <value> --expected-version <value>

kf tenant promote-config

Copy an approved tenant-config value from a source environment to a target environment (e.g., sandbox -> prod) with full receipt, history row, and linked audit event.

Copy an approved tenant-config value from a source environment to a target environment (e.g., sandbox -> prod) with full receipt, history row, and linked audit event. Source and target environments must differ; target must be ACTIVE.

Example

kf tenant promote-config --tenant tnt_demo --actor-type USER --actor-id usr_sam --source-environment-id <value> --target-environment-id <value>

kf tenant record-app-user-session-heartbeat

Record or refresh one active app user session for app and tenant-admin visibility.

Record or refresh one active app user session for app and tenant-admin visibility. User actors can record only their own web session unless they hold admin activity authority. Event payloads omit user agent and IP hash.

Example

kf tenant record-app-user-session-heartbeat --tenant tnt_demo --actor-type USER --actor-id usr_sam --web-session-id <value> --app-surface <value>

kf tenant revoke-api-key

Immediately revoke an active environment API key.

Immediately revoke an active environment API key. Revoked keys fail runtime authentication and leave a command receipt plus api_key.revoked event.

Example

kf tenant revoke-api-key --tenant tnt_demo --actor-type USER --actor-id usr_sam --api-key-id-stdin --expected-version <value> --reason <value>

kf tenant rollback-feed-definition

Roll a FeedDefinition's payload_version back to a prior value (target must be strictly less than current).

Roll a FeedDefinition's payload_version back to a prior value (target must be strictly less than current). Optimistic concurrency on expectedVersion. Carries a reasonCode for audit. Forward rolls are rejected; use UpdateFeedDefinition to advance.

Example

kf tenant rollback-feed-definition --tenant tnt_demo --actor-type USER --actor-id usr_sam --feed-definition-id <value> --target-payload-version <value> --expected-version <value> --reason-code <value>

kf tenant rotate-api-key

Rotate an active environment API key.

Rotate an active environment API key. Marks the previous key as ROTATED, creates a new key with the same subject and scopes, and returns the new secret once.

Example

kf tenant rotate-api-key --tenant tnt_demo --actor-type USER --actor-id usr_sam --api-key-id-stdin --expected-version <value>

kf tenant send-admin-broadcast

Send a tenant-admin app feed item to active app users by tenant, app, role, or user target.

Send a tenant-admin app feed item to active app users by tenant, app, role, or user target. Stores content, category, badge, CTA, and trigger refs on admin_broadcasts, creates delivery rows, and emits only sanitized target and feed facts.

Example

kf tenant send-admin-broadcast --tenant tnt_demo --actor-type USER --actor-id usr_sam --title <value> --body <value>

kf tenant transition-location-status

Transition a Location between ACTIVE and INACTIVE with optimistic concurrency on expectedVersion.

Transition a Location between ACTIVE and INACTIVE with optimistic concurrency on expectedVersion. Emits location.inactivated or location.reactivated.

Example

kf tenant transition-location-status --tenant tnt_demo --actor-type USER --actor-id usr_sam --location-id <value> --target-status <value> --expected-version <value>

kf tenant update-config

Update mutable tenant configuration: shallow-merge feature flags, write policy overrides and channel defaults through tenant_configs sidecars.

Update mutable tenant configuration: shallow-merge feature flags, write policy overrides and channel defaults through tenant_configs sidecars. Version-CAS on the tenants row.

Example

kf tenant update-config --tenant tnt_demo --actor-type USER --actor-id usr_sam --expected-version <value>

kf tenant update-feed-definition

Update a FeedDefinition's mutable fields (name, description, domainScope, eventTypes, payloadSchemaRef, payloadVersion, requiredScopes, riskClass, defaultBackpressureMode, replayWindowSeconds).

Update a FeedDefinition's mutable fields (name, description, domainScope, eventTypes, payloadSchemaRef, payloadVersion, requiredScopes, riskClass, defaultBackpressureMode, replayWindowSeconds). Optimistic concurrency on expectedVersion. Records the changed-field set and the old/new payloadVersion in the emitted event so subscribers can negotiate schema changes.

Example

kf tenant update-feed-definition --tenant tnt_demo --actor-type USER --actor-id usr_sam

kf tenant update-location

Update a Location's mutable fields (locationRef, name, type, fulfillment capability flags, trust level, address).

Update a Location's mutable fields (locationRef, name, type, fulfillment capability flags, trust level, address). Optimistic concurrency on expectedVersion. Status transitions belong to TransitionLocationStatus.

Example

kf tenant update-location --tenant tnt_demo --actor-type USER --actor-id usr_sam --location-id <value> --expected-version <value>

kf tenant upsert-bundle-allocation-policy

Create or update a per-tenant per-environment BundleAllocationPolicy controlling substitution mode (NEVER/ON_FAILURE_WITH_APPROVAL/AUTO_IF_PREDICATE_MATCHES), partial-fulfillment mode, reservation timeout, and overbooking policy.

Create or update a per-tenant per-environment BundleAllocationPolicy controlling substitution mode (NEVER/ON_FAILURE_WITH_APPROVAL/AUTO_IF_PREDICATE_MATCHES), partial-fulfillment mode, reservation timeout, and overbooking policy. Default policy denies substitution and partial fulfillment until tenants opt in.

Example

kf tenant upsert-bundle-allocation-policy --tenant tnt_demo --actor-type USER --actor-id usr_sam --policy-key <value> --substitution-mode <value> --partial-fulfillment-mode <value>

kf tenant upsert-config

Create or update a tenant-scoped configuration entry.

Create or update a tenant-scoped configuration entry. Skills, policy, and UI read from this for per-tenant behavior.

Example

kf tenant upsert-config --tenant tnt_demo --actor-type USER --actor-id usr_sam --config-key <value> --value <value> --expected-version <value>

kf tenant upsert-custom-field

Create or update a typed custom field against a canonical entity (ProductVariant, InventoryLevel, Location, and peers).

Create or update a typed custom field against a canonical entity (ProductVariant, InventoryLevel, Location, and peers). Validates namespace authority before writing and rejects unknown namespaces. Idempotent per metadata.idempotencyKey.

Example

kf tenant upsert-custom-field --tenant tnt_demo --actor-type USER --actor-id usr_sam --entity-type <value> --entity-id <value> --namespace <value> --key <value> --value-type <value>

kf tenant upsert-environment

Create or update a tenant environment and its deployment routing profile.

Create or update a tenant environment and its deployment routing profile. This is the command-backed control-plane seam for tenant, lifecycle environment, and physical deployment isolation.

Example

kf tenant upsert-environment --tenant tnt_demo --actor-type USER --actor-id usr_sam --environment-type <value> --expected-environment-version <value>

kf tenant upsert-location-operating-exception

Create or update a single calendar-date operating-hours override for a Location (holiday closure or special hours).

Create or update a single calendar-date operating-hours override for a Location (holiday closure or special hours). Idempotent by metadata.idempotencyKey. Emits location.operating_exception_upserted.

Example

kf tenant upsert-location-operating-exception --tenant tnt_demo --actor-type USER --actor-id usr_sam --location-id <value> --exception-date <value>

kf tenant upsert-location-operating-hours

Replace the weekly recurring operating-hours schedule for a Location atomically.

Replace the weekly recurring operating-hours schedule for a Location atomically. Accepts up to 21 (day_of_week, opens_at, closes_at, isClosed, shiftLabel?, effectiveFrom?, effectiveTo?) entries; the existing schedule is deleted and the new one inserted in one transaction. Idempotent by metadata.idempotencyKey. Emits location.operating_hours_upserted.

Example

kf tenant upsert-location-operating-hours --tenant tnt_demo --actor-type USER --actor-id usr_sam --location-id <value> --expected-version <value> --hours <value>