Skip to content
Akedly

Gateway screen settings from the CLI

Manage a gateway screen and its attached integration in one command, with a preview of every planned save.

Create or update

bash
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

GroupFlagsSaved on
Identity and attachment--name, --description, --integration-id, --statusGateway screen; status is update-only.
Branding--company-name, --logo, --favicon-url, --screen-language, --primary-color, --secondary-color, --appearance-fileGateway screen. Gateway screen language is separate from OTP-message language.
Rate limits--rate-limits-file, --recommended-limits, --periodGateway screen; recommendations are update-only.
Circuit breaker--circuit-breaker, --circuit-breaker-fileGateway screen.
Proof-of-work--pow, --pow-trigger-percent, --pow-starting-difficulty, --pow-maximum-difficultyGateway screen.
Developer mode--dev-mode, --dev-mode-digitsGateway screen; update-only. Digits need --dev-mode on in the same command.
Delivery--smart-routing, --passkeys, --otp-languageAttached integration.
Cluster Gate--cluster-gate, --cluster-gate-position, --cluster-gate-escalation, --cluster-gate-home-countriesAttached integration, subject to availability.
Channel Choice--channel-choice, --channel-choice-mode, --channel-choice-enforcementAttached 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

widget-limits.json

{
  "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.

breaker.json

{
  "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:

appearance.json

{ "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.