Gateway screen settings from the CLI
Manage a gateway screen and its attached integration in one command, with a preview of every planned save.
Formerly Widget settings
CLI 0.2.0 renamed widgets to integrations screens. This page was at /cli/widget-settings; old links still work. See Renamed in 0.2.0.
Create or update
akedly integrations screens create --name Example --integration-id <integration-id> --secret-file <new-private-path>
akedly integrations screens get <screen-id>
akedly integrations screens update <screen-id> --company-name Example --screen-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 integrations screens list before creating again.
Attach a gateway integration (it needs both the Return URL and the Server URL only once it is Live), or a legacy integration if your account is entitled. Headless cannot attach; an unattached gateway screen cannot send. Use --integration-id none --yes on update to detach. Gateway screen ids are the Mongo _id from integrations screens list.
The generated integrations screens create and integrations screens update sections contain every flag, allowed value, setting tip, default and consent rule.
Where settings are saved
| Group | Flags | Saved on |
|---|---|---|
| Identity and attachment | --name, --description, --integration-id, --status | Gateway screen; status is update-only. |
| Branding | --company-name, --logo, --favicon-url, --screen-language, --primary-color, --secondary-color, --appearance-file | Gateway screen. Gateway screen language is separate from OTP-message language. |
| Rate limits | --rate-limits-file, --recommended-limits, --period | Gateway screen; recommendations are update-only. |
| Circuit breaker | --circuit-breaker, --circuit-breaker-file | Gateway screen. |
| Proof-of-work | --pow, --pow-trigger-percent, --pow-starting-difficulty, --pow-maximum-difficulty | Gateway screen. |
| Developer mode | --dev-mode, --dev-mode-digits | Gateway screen; update-only. Digits need --dev-mode on in the same command. |
| Delivery | --smart-routing, --passkeys, --otp-language | Attached integration. |
| Cluster Gate | --cluster-gate, --cluster-gate-position, --cluster-gate-escalation, --cluster-gate-home-countries | Attached integration, subject to availability. |
| Channel Choice | --channel-choice, --channel-choice-mode, --channel-choice-enforcement | Attached integration, subject to eligibility; the mode requires Gateway. |
Integration settings target the resulting attachment, including a new --integration-id in the same command. The CLI checks both write permissions and reads the current revisions before saving. The gateway screen saves first; the integration follows. A missing attachment is refused instead of silently dropping an integration setting.
Creation with only gateway screen settings needs no --yes. On update, status, attachment, Developer mode, rate limits, breaker and PoW changes require --yes; identity and branding do not. Integration settings need --yes on create and update. --dry-run previews without consent or writes. Screen-only creation is checked locally; create commands that also change integration 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. Gateway screen 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.
Gateway screen recommendations use account-wide gateway screen 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 integrations screens 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 integrations update command supplied in details.recovery to finish the integration settings. Creating again would make a second gateway screen. An uncertain response is not proof that a write failed.
Next: Gateway setup recipe, integration settings, or settings errors.
