Widget settings from the CLI

Create or update

akedly widgets create --name Example --pipeline-id <pipeline-id> --secret-file <new-private-path>
akedly widgets get <widget-id>
akedly widgets update <widget-id> --company-name Example --widget-language en

Creation needs Full access, widgets:create, a name and a new Secret-file path. The CLI reserves the file privately before creating, writes the Secret there and never prints it. There is no Secret reveal or recovery command. An uncertain create must be checked with widgets list before creating again.

Attach a V2 pipeline with both callbacks, or a V1 pipeline if your account is entitled. V1.2 cannot attach; an unattached widget cannot send. Use --pipeline-id none --yes on update to detach. Widget ids are the Mongo _id from widgets list.

The generated widgets create and widgets update sections contain every flag, allowed value, setting tip, default and consent rule.

Where settings are saved

Pipeline settings target the resulting attachment, including a new --pipeline-id in the same command. The CLI checks both write permissions and reads the current revisions before saving. The widget saves first; the pipeline follows. A missing attachment is refused instead of silently dropping a pipeline setting.

Creation with only widget settings needs no --yes. On update, status, attachment, dev mode, rate limits, breaker and PoW changes require --yes; identity and branding do not. Pipeline settings need --yes on create and update. --dry-run previews without consent or writes. Widget-only creation is checked locally; create commands that also change pipeline settings perform authenticated planning reads. Update planning can read resources and recommendations. No create dry run opens a Secret file.

Rate limits and the circuit breaker

{
  "widgetAttempts": {
    "perWidget": { "perMinute": 30, "perHour": 150, "perDay": 3000 }
  },
  "otpRequests": {
    "perPhoneNumber": { "perMinute": 2, "perHour": 6, "perDay": 20 }
  }
}

Both widgetAttempts and otpRequests accept perPhoneNumber, perDevice and perWidget, each with perMinute, perHour and perDay. Only supplied limits change. Values are whole numbers above zero; phone/device limits cannot exceed 5/minute, 25/hour or 50/day. Per-widget hour/day limits must be at least 5/100 times the minute limit. Explicit files do not recalculate the other windows for you.

{
  "floodThresholds": { "perMinute": 100, "per5Minutes": 500, "per15Minutes": 1500 },
  "suspensionSeconds": { "firstViolation": 300, "secondViolation": 900, "maxViolation": 1800 }
}

--circuit-breaker-file merges the values you supply; durations are whole seconds above zero. Combine it with --circuit-breaker on or off when needed. Widget PoW takes a trigger of 25–95% and difficulties 3–6, with starting difficulty no higher than maximum. Stored PoW settings remain subject to server policy.

Widget recommendations use account-wide widget traffic. They replace all 18 limits and enable/configure the breaker, while keeping PoW, appearance and the breaker's current trip state. They cannot be combined with explicit limit or breaker flags. See fit rate limits to your traffic.

Appearance

Use scalar branding flags for common changes, or pass the appearance object itself to --appearance-file without a branding or appearance wrapper:

{ "theme": { "mode": "dark" } }

Files must be readable regular JSON objects at most 64 KiB. Unknown appearance keys are refused, as are keys containing dots or named __proto__, prototype or constructor. Do not set the same appearance leaf through a file and a scalar flag. Disjoint fields can be combined. On update, none clears an optional scalar branding value or description.

For the full visual editor, run akedly widgets studio <id>; opening and saving the Studio needs widgets:update.

Recovering a partial save

WIDGET_CHANGED or PIPELINE_CHANGED protects a resource changed since the CLI read it. Read the current state, then rerun so the CLI uses its new revision.

For PARTIAL_UPDATE, inspect the saved and unconfirmed resources. After an update, rerun the same update once you have checked the underlying error. After a create, preserve the saved Secret file and widgetId, then run the exact pipelines update command supplied in details.recovery to finish the pipeline settings. Creating again would make a second widget. An uncertain response is not proof that a write failed.

Next: V2 setup recipe, pipeline settings, or settings errors.