Skip to content
Akedly
Command reference

Gateway screens

Akedly CLI command reference: Gateway screens.

integrations screens list

Browse the account’s screens to find a screen ID, status, or display name.

When to use

  • Use for a quick inventory or before opening a particular screen.

How it works

  1. Reads screens with optional pagination, status and search filters.

Prerequisites

  • A CLI login with permission for this account and resource.

Expected outcome

Screen rows returned by the server.

Next steps

  • Use the 24-hex _id with integrations screens get/update.

Usage

sh
akedly integrations screens list

Inspect this command offline before preparing an operation:

sh
akedly describe "integrations screens list" --output json

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--pageinteger1 to unboundedCommand-specific option; see the full command details below. Query parameter: page.
--limitinteger1 to unboundedCommand-specific option; see the full command details below. Query parameter: limit.
--statusenumactive | inactive | suspendedCommand-specific option; see the full command details below. Query parameter: status.
--searchtext—Command-specific option; see the full command details below. Query parameter: search.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: widgets:read.

Server request: GET /widgets.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

idempotent: Idempotent requests retry network errors and HTTP 429/502/503/504, at most 3 tries, waiting for cooldownSeconds, retryAfter or the Retry-After header (otherwise 1 second) between tries, up to 30 seconds; a longer requested wait is returned as the error.

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

List screens; inactive screens are hidden unless --status is supplied. Read-only logins are allowed. For a returned screen, this read may disable an expired Developer mode window and delete passkeys enrolled with its test number.

Login 429 guidance.

Worked examples

Examples are synthetic illustrations, never live account records. Replace resource IDs with your own authorized resources. Secret values are omitted here; redacted examples illustrate the shape and are not schema-validation fixtures.

Synthetic integrations screens list workflow

Browse the account’s screens to find a screen ID, status, or display name.

sh
akedly integrations screens list --page 1

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "widgets": [
      {
        "_id": "0123456789abcdef01234567",
        "name": "Example widget",
        "widgetId": "widget_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        "status": "active"
      }
    ],
    "pagination": {
      "total": 1,
      "page": 1,
      "limit": 20,
      "pages": 1
    }
  }
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

Additional command forms

sh
akedly integrations screens list

Input and file contracts

The contract below describes typed arguments, file formats, validation boundaries and API mappings. Boolean switches take no value; numeric and comma-separated values are each passed as one argument. Read prerequisites and full command details for state-dependent requirements.

Response contract

The CLI preserves the server success envelope and passes through resource-specific fields; additional data fields are server extensions, not fields this command promises to synthesize.

Common error guidance.

integrations screens list-filtered

Find screens by integration, status, name, branding or creation range, including attached screens needed for settings work.

When to use

  • Use when locating all screens attached to an integration; include inactive status because default listings omit inactive screens.

How it works

  1. Reads a paginated, sortable screen list using the requested filters.

Prerequisites

  • A CLI login with permission for this account and resource.

Expected outcome

Screen rows plus pagination metadata.

Next steps

  • Inspect a candidate using integrations screens get; for integration fan-out ensure inactive attachments are considered.

Usage

sh
akedly integrations screens list-filtered

Inspect this command offline before preparing an operation:

sh
akedly describe "integrations screens list-filtered" --output json

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--pageinteger1 to unboundedCommand-specific option; see the full command details below. Query parameter: page.
--limitinteger1 to unboundedCommand-specific option; see the full command details below. Query parameter: limit.
--statusenumactive | inactive | suspendedCommand-specific option; see the full command details below. Query parameter: status.
--nametext—Command-specific option; see the full command details below. Query parameter: name.
--integration-idid—Command-specific option; see the full command details below. Query parameter: pipelineId.
--has-brandingenumtrue | falseCommand-specific option; see the full command details below. Query parameter: hasBranding.
--start-datetext—Command-specific option; see the full command details below. Query parameter: sDate.
--end-datetext—Command-specific option; see the full command details below. Query parameter: eDate.
--sort-byenumcreatedAt | name | status | updatedAtCommand-specific option; see the full command details below. Query parameter: sortBy.
--sort-orderenumasc | descCommand-specific option; see the full command details below. Query parameter: sortOrder.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: widgets:read.

Server request: GET /widgets/user/:userID/paginated.

Owner parameters resolved from the CLI Login: userID.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

idempotent: Idempotent requests retry network errors and HTTP 429/502/503/504, at most 3 tries, waiting for cooldownSeconds, retryAfter or the Retry-After header (otherwise 1 second) between tries, up to 30 seconds; a longer requested wait is returned as the error.

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

List your screens with additional filters and owner profile fields. Read-only logins are allowed. For a returned screen, this read may disable an expired Developer mode window and delete passkeys enrolled with its test number.

Login 429 guidance.

Worked examples

Examples are synthetic illustrations, never live account records. Replace resource IDs with your own authorized resources. Secret values are omitted here; redacted examples illustrate the shape and are not schema-validation fixtures.

Synthetic integrations screens list-filtered workflow

Find screens by integration, status, name, branding or creation range, including attached screens needed for settings work.

sh
akedly integrations screens list-filtered --integration-id 89abcdef0123456789abcdef --status active

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "widgets": [
      {
        "_id": "0123456789abcdef01234567",
        "name": "Example widget",
        "widgetId": "widget_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        "pipelineId": "89abcdef0123456789abcdef",
        "status": "active",
        "createdAt": "2030-03-12T09:00:00.000Z"
      }
    ],
    "pagination": {
      "currentPage": 1,
      "totalPages": 1,
      "totalCount": 1,
      "limit": 100,
      "hasNextPage": false,
      "hasPreviousPage": false
    },
    "appliedFilters": {
      "targetUserID": null,
      "status": "active",
      "name": null,
      "pipelineId": "89abcdef0123456789abcdef",
      "hasBranding": null,
      "dateRange": null
    }
  }
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

Additional command forms

sh
akedly integrations screens list-filtered

Input and file contracts

The contract below describes typed arguments, file formats, validation boundaries and API mappings. Boolean switches take no value; numeric and comma-separated values are each passed as one argument. Read prerequisites and full command details for state-dependent requirements.

Response contract

The CLI preserves the server success envelope and passes through resource-specific fields; additional data fields are server extensions, not fields this command promises to synthesize.

Common error guidance.

integrations screens get

Inspect one screen’s current integration attachment, status, branding and security settings.

When to use

  • Use before editing or diagnosing screen behavior.

How it works

  1. Reads a screen by its Mongo _id.

Prerequisites

  • A CLI login with permission for this account and resource.

Expected outcome

Current screen resource.

Next steps

  • Use integrations screens update for changes; keep its current integration type constraints in mind.

Usage

sh
akedly integrations screens get <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "integrations screens get" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Use the 24-hex Mongo screen _id.

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: widgets:read.

Server request: GET /widgets/:id.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

idempotent: Idempotent requests retry network errors and HTTP 429/502/503/504, at most 3 tries, waiting for cooldownSeconds, retryAfter or the Retry-After header (otherwise 1 second) between tries, up to 30 seconds; a longer requested wait is returned as the error.

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Read a screen using its 24-hex Mongo _id. Developer mode returns the fake test number and code; the screen Secret is never shown. Open this screen in the dashboard studio with `akedly integrations screens studio <id>`; opening and saving it there needs the `widgets:update` permission. For a returned screen, this read may disable an expired Developer mode window and delete passkeys enrolled with its test number.

Login 429 guidance.

Worked examples

Examples are synthetic illustrations, never live account records. Replace resource IDs with your own authorized resources. Secret values are omitted here; redacted examples illustrate the shape and are not schema-validation fixtures.

Synthetic integrations screens get workflow

Inspect one screen’s current integration attachment, status, branding and security settings.

sh
akedly integrations screens get 0123456789abcdef01234567

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "_id": "0123456789abcdef01234567",
    "name": "Example widget",
    "widgetId": "widget_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "pipelineId": "89abcdef0123456789abcdef",
    "status": "active",
    "updatedAt": "2030-03-12T09:00:00.000Z"
  }
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

Additional command forms

sh
akedly integrations screens get <id>

Input and file contracts

The contract below describes typed arguments, file formats, validation boundaries and API mappings. Boolean switches take no value; numeric and comma-separated values are each passed as one argument. Read prerequisites and full command details for state-dependent requirements.

Response contract

The CLI preserves the server success envelope and passes through resource-specific fields; additional data fields are server extensions, not fields this command promises to synthesize.

Common error guidance.

integrations screens studio

Open the dashboard editor for a screen’s visual branding and customer-facing appearance.

When to use

  • Use when a person needs the interactive Studio rather than a file-based settings update.

How it works

  1. Performs a dashboard handoff for the selected screen; no settings are changed until the user saves in the browser.

Prerequisites

  • A CLI login with permission for this account and resource.

Expected outcome

Handoff result or browser-opening instructions.

Next steps

  • Finish and save in Studio, then inspect with screens get.

Usage

sh
akedly integrations screens studio <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "integrations screens studio" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Use the 24-hex Mongo screen _id.

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--openboolean switch—Command-specific option; see the full command details below.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: widgets:read.

Dashboard path: /admin/widgets/:id/branding. Status check: integrations screens get.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

idempotent: Idempotent requests retry network errors and HTTP 429/502/503/504, at most 3 tries, waiting for cooldownSeconds, retryAfter or the Retry-After header (otherwise 1 second) between tries, up to 30 seconds; a longer requested wait is returned as the error.

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Open an owned screen's dashboard studio, regardless of its API version or status. CLI lookup needs widgets:read; entering and saving in the browser studio needs widgets:update. This command prints a link; --open also tries to open it. A screen on an integration opens at /admin/integrations/<integration id>/screens/<id>/branding; a screen attached to no integration opens at /admin/widgets/<id>/branding. It does not save branding. After the owner saves, akedly integrations screens get <id> shows the saved branding. The lookup is a normal screen read, so, as on any screen read, the server may disable an expired Developer mode window and delete passkeys enrolled with its test number. Success does not mean the browser is signed in or on the same account. If you open the link in the same browser profile, on the same dashboard deployment, while its session and active account are still valid, you will usually already be signed in. A signed-out existing account is asked to sign in and returned to the studio; registration and account verification keep their existing home-page flow. Mid-session API expiry and rejected profile checks can still lose the target. With only a path available, --open is skipped with a notice; open that path on the matching dashboard. Read-only CLI logins are supported. No --yes, --dry-run, --wait or --timeout is supported. Find the screen id with akedly integrations screens list (add --status inactive for inactive screens).

Login 429 guidance.

Worked examples

Examples are synthetic illustrations, never live account records. Replace resource IDs with your own authorized resources. Secret values are omitted here; redacted examples illustrate the shape and are not schema-validation fixtures.

Synthetic integrations screens studio workflow

Open the dashboard editor for a screen’s visual branding and customer-facing appearance.

sh
akedly integrations screens studio 0123456789abcdef01234567

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "handoff": {
      "action": "integrations screens studio",
      "path": "/admin/widgets/0123456789abcdef01234567/branding",
      "url": "https://app.example.invalid/admin/widgets/0123456789abcdef01234567/branding",
      "requested": "Edit the screen's branding in the dashboard."
    }
  }
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

Additional command forms

sh
akedly integrations screens studio <id>
sh
akedly integrations screens studio <id> --open

Input and file contracts

The contract below describes typed arguments, file formats, validation boundaries and API mappings. Boolean switches take no value; numeric and comma-separated values are each passed as one argument. Read prerequisites and full command details for state-dependent requirements.

Response contract

The handoff opens the dashboard branding editor. It does not save branding; the browser session must save the changes.

Common error guidance.

integrations screens create

Create an embeddable verification screen attached to a ready integration.

When to use

  • Use to add a customer-facing web verification surface on a ready integration. Legacy requires the account entitlement; a live gateway needs both the Return URL and the Server URL. Headless integrations cannot be attached to screens.

How it works

  1. Validates optional branding/security files; may read the linked integration and permissions for linked settings; creates the screen, writes its one-time Secret, then applies linked integration settings. If the second write fails, reports PARTIAL_UPDATE and a recovery command.

Prerequisites

  • A CLI login with widgets:create permission.
  • An owned, active ready legacy or gateway integration; legacy requires screen entitlement, and a Live gateway requires a Return URL and a Server URL (a Test gateway needs neither).
  • A new private output path for the one-time screen Secret.

Expected outcome

Created screen resource with secretFile metadata, never the Secret itself; linked integration write can be partial.

Next steps

  • Store the Secret securely and embed public widgetId/publicKey; inspect partial updates before continuing.

Usage

sh
akedly integrations screens create

Inspect this command offline before preparing an operation:

sh
akedly describe "integrations screens create" --output json

Flags

FlagTypeEnum / rangeRequiredDescription
--ksaboolean switch—noSelect the KSA deployment.
--nametext—yesCommand-specific option; see the full command details below. Manifest body field: name.
--descriptiontext—noCommand-specific option; see the full command details below. Manifest body field: description.
--integration-idid—noCommand-specific option; see the full command details below. Manifest body field: pipelineId. Tip: Attach screens to a gateway integration. A legacy integration is still accepted but lacks gateway's security and screen features, and a headless integration is refused.
--secret-filetext—noWrite the secret to a new mode 0600 file and omit it from output; an existing path is refused.
--dry-runboolean switch—noPreview without sending the write or creating output files; planning reads may still occur. Bypass consent.
--logotext—noCommand-specific option; see the full command details below. Manifest body field: branding.logo, branding.customLogo.
--company-nametext—noCommand-specific option; see the full command details below. Manifest body field: branding.companyName, branding.customCompanyName.
--favicon-urltext—noCommand-specific option; see the full command details below. Manifest body field: branding.faviconUrl.
--screen-languageenumen | arnoCommand-specific option; see the full command details below. Manifest body field: branding.appearance.language.
--primary-colortext—noCommand-specific option; see the full command details below. Manifest body field: branding.appearance.theme.colors.primary, branding.customPrimaryColor.
--secondary-colortext—noCommand-specific option; see the full command details below. Manifest body field: branding.appearance.theme.colors.secondary, branding.customSecondaryColor.
--rate-limits-filetext—noCommand-specific option; see the full command details below. Manifest body field: rateLimiting.otpRequests.perDeviceId.perDay, rateLimiting.otpRequests.perDeviceId.perHour, rateLimiting.otpRequests.perDeviceId.perMinute, rateLimiting.otpRequests.perPhoneNumber.perDay, rateLimiting.otpRequests.perPhoneNumber.perHour, rateLimiting.otpRequests.perPhoneNumber.perMinute, rateLimiting.otpRequests.perWidget.perDay, rateLimiting.otpRequests.perWidget.perHour, rateLimiting.otpRequests.perWidget.perMinute, rateLimiting.widgetAttempts.perDeviceId.perDay, rateLimiting.widgetAttempts.perDeviceId.perHour, rateLimiting.widgetAttempts.perDeviceId.perMinute, rateLimiting.widgetAttempts.perPhoneNumber.perDay, rateLimiting.widgetAttempts.perPhoneNumber.perHour, rateLimiting.widgetAttempts.perPhoneNumber.perMinute, rateLimiting.widgetAttempts.perWidget.perDay, rateLimiting.widgetAttempts.perWidget.perHour, rateLimiting.widgetAttempts.perWidget.perMinute. Tip: Start with the default limits unless your traffic needs different ones. Use traffic recommendations when enough history is available; their calculations include a 10% growth buffer. Final screen recommendations also apply per-phone and per-device caps and may raise per-screen hour and day limits to meet the required ratios, so applied values can differ from the buffered calculation. Review the result against expected peaks before changing live limits.
--circuit-breakerenumon | offnoCommand-specific option; see the full command details below. Manifest body field: circuitBreaker.enabled. Tip: Keep the circuit breaker on; Akedly recommends it to protect verification from flood attacks and traffic spikes.
--circuit-breaker-filetext—noCommand-specific option; see the full command details below. Manifest body field: circuitBreaker.floodThresholds.per15Minutes, circuitBreaker.floodThresholds.per5Minutes, circuitBreaker.floodThresholds.perMinute, circuitBreaker.suspensionDurations.firstViolation, circuitBreaker.suspensionDurations.maxViolation, circuitBreaker.suspensionDurations.secondViolation. Tip: Keep the circuit breaker on; Akedly recommends it to protect verification from flood attacks and traffic spikes.
--powenumon | offnoCommand-specific option; see the full command details below. Manifest body field: security.pow.allowed. Tip: Keep the default proof-of-work settings unless you face sustained heavy abuse. For an expected launch or campaign surge, raise the rate limits and circuit breaker flood thresholds first instead of lowering the proof-of-work trigger, so legitimate traffic is not challenged too early.
--pow-trigger-percentinteger25 to 95noCommand-specific option; see the full command details below. Manifest body field: security.pow.triggerPercent. Tip: Keep the default proof-of-work settings unless you face sustained heavy abuse. For an expected launch or campaign surge, raise the rate limits and circuit breaker flood thresholds first instead of lowering the proof-of-work trigger, so legitimate traffic is not challenged too early.
--pow-starting-difficultyinteger3 to 6noCommand-specific option; see the full command details below. Manifest body field: security.pow.startDifficulty. Tip: Keep the default proof-of-work settings unless you face sustained heavy abuse. For an expected launch or campaign surge, raise the rate limits and circuit breaker flood thresholds first instead of lowering the proof-of-work trigger, so legitimate traffic is not challenged too early.
--pow-maximum-difficultyinteger3 to 6noCommand-specific option; see the full command details below. Manifest body field: security.pow.maxDifficulty. Tip: Keep the default proof-of-work settings unless you face sustained heavy abuse. For an expected launch or campaign surge, raise the rate limits and circuit breaker flood thresholds first instead of lowering the proof-of-work trigger, so legitimate traffic is not challenged too early.
--appearance-filetext—noCommand-specific option; see the full command details below. Manifest body field: branding.appearance, branding.appearance.language, branding.appearance.theme.colors.primary, branding.customPrimaryColor, branding.appearance.theme.colors.secondary, branding.customSecondaryColor, branding.appearance.theme.mode, branding.theme.
--yesboolean switch—noConfirm this action where consent is required.
--smart-routingenumon | offnoCommand-specific option; see the full command details below. Manifest body field: smartRouting, expectedUpdatedAt.
--passkeysenumon | offnoCommand-specific option; see the full command details below. Manifest body field: passkeyEnabled, expectedUpdatedAt. Tip: Passkeys let returning users verify with Face ID or a fingerprint, and a passkey sign-in can cost up to 40% less than an OTP at the default passkey rate; your account's rate may differ.
--cluster-gateenumon | offnoCommand-specific option; see the full command details below. Manifest body field: securityConfig.clusterGate.enabled, clusterGateIntent, expectedUpdatedAt.
--cluster-gate-positionenumcautious | balanced | assertivenoCommand-specific option; see the full command details below. Manifest body field: securityConfig.clusterGate.position, clusterGateIntent, expectedUpdatedAt. Tip: Balanced is the default position. Estimated during an attack, Cautious blocks about 65% of spam and refuses no real users, Balanced about 90% of spam and about 1% of real users, and Assertive 95% or more of spam and about 3% of real users. Assertive is outside Akedly's recommended limits: it does not check whether a request is a real user caught in the same flood. Refusals are rare outside an attack.
--cluster-gate-escalationenumon | offnoCommand-specific option; see the full command details below. Manifest body field: securityConfig.clusterGate.escalation, clusterGateIntent, expectedUpdatedAt.
--cluster-gate-home-countrieslist—noCommand-specific option; see the full command details below. Manifest body field: securityConfig.clusterGate.homeCountries, clusterGateIntent, expectedUpdatedAt. Tip: Declare the countries where you expect phone destinations and end-user IPs to help Cluster Gate understand your traffic. Home countries do not restrict sending or allow or block IP addresses, and other protections still apply. Learned countries stay included automatically; clearing declarations does not clear the learned set.
--otp-languageenumen | arnoCommand-specific option; see the full command details below. Manifest body field: locale, expectedUpdatedAt.
--channel-choiceenumon | offnoCommand-specific option; see the full command details below. Manifest body field: channelChoiceEnabled, expectedUpdatedAt.
--channel-choice-modeenumask-first | send-firstnoCommand-specific option; see the full command details below. Manifest body field: channelChoiceMode, expectedUpdatedAt.
--channel-choice-enforcementenumfallback | hard-pinnoCommand-specific option; see the full command details below. Manifest body field: channelChoiceEnforcement, expectedUpdatedAt.
--helpboolean switch—noShow offline command help.
--outputenumjson | humannoSelect JSON or human output.
--fieldsdot-paths—noSelect comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: widgets:create.

Server request: POST /widgets.

Shared server-guard guidance.

Consent

--yes when --smart-routing or --passkeys or --cluster-gate or --cluster-gate-position or --cluster-gate-escalation or --cluster-gate-home-countries or --otp-language or --channel-choice or --channel-choice-mode or --channel-choice-enforcement is given. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

write: Non-idempotent writes are not automatically retried. guarded-write: when an update carries the revision read from the server, its write is not automatically retried after network errors or HTTP 429/502/503/504. It may already be saved; inspect the resource before rerunning. A rerun reads current settings again. The explicit CLI_RATE_LIMITED refusal exception below still applies. recommendation-read: the recommendation request made while planning --recommended-limits is not automatically retried after network errors or HTTP 429/502/503/504. If planning fails, no update is sent; rerun the command to request a new recommendation. The explicit CLI_RATE_LIMITED refusal exception below still applies. This label does not change the retry policy of the standalone rate-recommendations command.

Output

Sensitive output: secret-sink. Use the supported sink; default output may contain a secret. Supported sinks: --secret-file.

Full command details

Create a screen with --name and --secret-file <new path>; --integration-id is optional. Requires Full access and widgets:create. The Secret file must not exist; it is reserved with mode 0600 before the request, filled immediately after creation succeeds, and never printed. The result includes secretFile and the stored settings. The screen Secret cannot be revealed or recovered later. After an ambiguous create failure, run akedly integrations screens list before intentionally creating another screen. Attach a gateway integration (both the Return URL and the Server URL are needed only once it is Live), or a legacy integration if entitled; headless cannot attach. An unattached screen cannot send. Omitted settings start with the dashboard values: screen attempts per phone and device are 2/minute, 6/hour and 10/day; OTP requests are 2/minute, 6/hour and 20/day; both per-screen limits are 25/minute, 125/hour and 2500/day. The circuit breaker starts on with flood thresholds 100/minute, 500/5 minutes and 1500/15 minutes, and suspension durations 300, 900 and 1800 seconds. Proof-of-work starts allowed with a 50% trigger, starting difficulty 3 and maximum difficulty 5. Explicit settings replace only the supplied starting values. --rate-limits-file <file> takes a JSON object with widgetAttempts and/or otpRequests, each containing perPhoneNumber, perDevice and/or perWidget, each with perMinute, perHour and/or perDay; for example {"widgetAttempts":{"perWidget":{"perMinute":30,"perHour":150,"perDay":3000}}}. Numbers must be whole and above zero. Per-phone and per-device limits cannot exceed 5/minute, 25/hour or 50/day; each per-screen hour limit must be at least 5 times its minute limit and its day limit at least 100 times its minute limit. The server checks the completed settings; inspect details.errors if it refuses them. --circuit-breaker on|off sets whether the breaker is enabled. --circuit-breaker-file <file> accepts floodThresholds with perMinute, per5Minutes and per15Minutes, and suspensionSeconds with firstViolation, secondViolation and maxViolation; supply only the values to change, as whole numbers above zero. Durations are in seconds. The file may be combined with --circuit-breaker. --pow on|off allows proof-of-work; --pow-trigger-percent takes 25..95, and --pow-starting-difficulty and --pow-maximum-difficulty take 3..6. Starting difficulty must not exceed maximum difficulty. These are stored settings; server policy still controls proof-of-work at runtime. Common branding flags are --company-name, --logo, --favicon-url, --screen-language en|ar, --primary-color and --secondary-color. --appearance-file <file> supplies the appearance object itself, without a branding or appearance wrapper; for example {"theme":{"mode":"dark"}}. The server validates its keys and values, including null, empty strings and numeric strings, and refuses unknown keys with APPEARANCE_FIELD_UNKNOWN. All settings files must be readable regular JSON object files of at most 64 KiB. Appearance keys cannot contain dots or be __proto__, prototype or constructor. Do not set the same appearance leaf through both a file and a scalar flag; disjoint values may be combined. Screen-only creation needs no --yes; changes to linked integration settings need --yes. Status and Developer mode are update-only; captcha requirements and cooldowns cannot be changed here. Screen-only --dry-run checks inputs locally without contacting the server; linked integration settings perform authenticated planning reads. No dry run writes a Secret file or requires --secret-file. The server validates the final request and attachment when saving. Open this screen in the dashboard studio with `akedly integrations screens studio <id>`; opening and saving it there needs the `widgets:update` permission. Integration settings --passkeys, --smart-routing, --otp-language, --cluster-gate, --cluster-gate-position, --cluster-gate-escalation, --cluster-gate-home-countries, --channel-choice, --channel-choice-mode and --channel-choice-enforcement can be supplied here with --yes. They are written to the resulting attached integration after the screen is saved; an attachment change targets the new integration. Both write permissions are checked first. Each update carries the revision read during planning. A partial update names the saved and unconfirmed resources; after create, keep the saved Secret and use the provided integration update recovery command instead of creating again. --dry-run lists every planned write and saves nothing.

Login 429 guidance.

Worked examples

Examples are synthetic illustrations, never live account records. Replace resource IDs with your own authorized resources. Secret values are omitted here; redacted examples illustrate the shape and are not schema-validation fixtures.

Synthetic integrations screens create workflow

Create an embeddable verification screen attached to a ready integration.

sh
akedly integrations screens create --name 'Example widget' --integration-id 89abcdef0123456789abcdef --secret-file ./private/widget-secret.txt --yes

Input file: ./fixtures/appearance.json (json).

json
{
  "language": "en",
  "theme": {
    "colors": {
      "primary": "#336699",
      "secondary": null
    }
  }
}

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "_id": "0123456789abcdef01234567",
    "name": "Example widget",
    "widgetId": "widget_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "publicKey": "pk_synthetic",
    "secretFile": "./private/widget-secret.txt"
  }
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

The referenced integration must be an existing ready legacy or gateway integration; the synthetic ID does not assert that it exists.

Secret output sink: ./private/widget-secret.txt. Use a new private path when running the command; the synthetic example is documentation only.

Synthetic screen creation with limits, breaker, and appearance files

Create a customer-facing screen with explicit abuse limits and appearance settings on a ready gateway integration.

sh
akedly integrations screens create --name 'Example widget' --integration-id 89abcdef0123456789abcdef --rate-limits-file ./fixtures/widget-rate-limits.json --circuit-breaker-file ./fixtures/widget-circuit-breaker.json --appearance-file ./fixtures/widget-appearance.json --secret-file ./private/new-widget-secret.txt --yes

Input file: ./fixtures/widget-rate-limits.json (json).

json
{
  "otpRequests": {
    "perWidget": {
      "perMinute": 30
    }
  }
}

Input file: ./fixtures/widget-circuit-breaker.json (json).

json
{
  "floodThresholds": {
    "perMinute": 20,
    "per5Minutes": 60,
    "per15Minutes": 120
  },
  "suspensionSeconds": {
    "firstViolation": 60,
    "secondViolation": 300,
    "maxViolation": 1800
  }
}

Input file: ./fixtures/widget-appearance.json (json).

json
{
  "language": "en",
  "theme": {
    "colors": {
      "primary": "#336699",
      "secondary": null
    }
  }
}

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "_id": "0123456789abcdef01234567",
    "name": "Example widget",
    "widgetId": "widget_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "publicKey": "pk_synthetic",
    "secretFile": "./private/new-widget-secret.txt"
  }
}

Prerequisites: widgets:create permission and an owned, active, ready gateway integration. The synthetic integration ID must be replaced with an existing integration; headless integrations cannot be attached to screens.

The three JSON files configure screen-level OTP-request limits, circuit-breaker thresholds and durations, and appearance. The create call also writes the screen's one-time Secret to the new private output path; keep that path separate from the input fixtures and store the real secret securely.

This response exposes secretFile metadata, not a claim that the synthetic output file exists. After creation, embed the returned widgetId/publicKey and inspect screen settings. If a linked write is partial, inspect both the screen and integration before continuing.

Additional command forms

sh
akedly integrations screens create --name Example --integration-id <id> --secret-file <new path>

Input and file contracts

The contract below describes typed arguments, file formats, validation boundaries and API mappings. Boolean switches take no value; numeric and comma-separated values are each passed as one argument. Read prerequisites and full command details for state-dependent requirements.

Response contract

The CLI preserves the server success envelope and passes through resource-specific fields; additional data fields are server extensions, not fields this command promises to synthesize.

Secret bytes are delivered only to the requested local file; the JSON response contains file metadata, never the secret value.

Protected linked-resource writes can be partial; honor PARTIAL_UPDATE details and inspect each named resource before retrying.

Own recovery guidance

CodeHint
WIDGET_CHANGEDRun akedly integrations screens get <id> to inspect the current settings, then rerun the intended update. The command reads a fresh revision; do not reuse an old request body to overwrite another change.
WIDGET_POW_INVALIDUse --pow on|off, --pow-trigger-percent 25..95, and --pow-starting-difficulty and --pow-maximum-difficulty 3..6. Starting difficulty must not exceed maximum difficulty. If changing only one difficulty, inspect the other with akedly integrations screens get <id>; an unset start is compared as 3 and an unset maximum as 5.
APPEARANCE_FIELD_UNKNOWNRemove or correct the appearance key named in details.field in --appearance-file. Supply the appearance object itself without a branding or appearance wrapper; the server decides which keys and values are supported. Unknown keys are refused rather than dropped.
SCREEN_NOT_ALLOWED_ON_V12A V1.2 (headless) integration cannot have gateway screens. Pass --integration-id of a V2.0 (gateway) integration (akedly integrations list shows the type), or run akedly integrations upgrade <id> to get a V2.0 integration with its own screen.

Common error guidance.

integrations screens update

Change screen identity, appearance, rate limits, circuit breaker, PoW or linked integration settings.

When to use

  • Use after integrations screens get; supply the screen _id and only the settings intended for that screen/integration.

How it works

  1. Reads current screen/integration revisions as required; dry-run performs planning reads and previews writes. Linked integration settings are saved after screen settings, so PARTIAL_UPDATE is possible.

Prerequisites

  • A CLI login with permission for this account and resource.

Expected outcome

Updated screen resource or multi-step dry-run plan; linked writes can be partial.

Next steps

  • On PARTIAL_UPDATE inspect both screen and integration before retrying; revisions are read automatically.

Usage

sh
akedly integrations screens update <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "integrations screens update" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Use the 24-hex Mongo screen _id.

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--nametext—Command-specific option; see the full command details below. Manifest body field: name.
--descriptiontext—Command-specific option; see the full command details below. Manifest body field: description.
--integration-idid—Command-specific option; see the full command details below. Manifest body field: pipelineId. The literal none clears this value. Tip: Attach screens to a gateway integration. A legacy integration is still accepted but lacks gateway's security and screen features, and a headless integration is refused.
--statusenumactive | inactiveCommand-specific option; see the full command details below. Manifest body field: status.
--logotext—Command-specific option; see the full command details below. Manifest body field: branding.logo, branding.customLogo.
--company-nametext—Command-specific option; see the full command details below. Manifest body field: branding.companyName, branding.customCompanyName.
--favicon-urltext—Command-specific option; see the full command details below. Manifest body field: branding.faviconUrl.
--screen-languageenumen | arCommand-specific option; see the full command details below. Manifest body field: branding.appearance.language.
--primary-colortext—Command-specific option; see the full command details below. Manifest body field: branding.appearance.theme.colors.primary, branding.customPrimaryColor.
--secondary-colortext—Command-specific option; see the full command details below. Manifest body field: branding.appearance.theme.colors.secondary, branding.customSecondaryColor.
--dev-modeenumon | offCommand-specific option; see the full command details below. Manifest body field: devMode.enabled. Tip: Do not leave Developer mode on for production traffic: while the window is open, anyone who knows the test number and code can complete a verification for that number.
--dev-mode-digitsinteger4 to 6Command-specific option; see the full command details below. Manifest body field: devMode.digits.
--dry-runboolean switch—Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
--yesboolean switch—Confirm this action where consent is required.
--rate-limits-filetext—Command-specific option; see the full command details below. Manifest body field: rateLimiting.otpRequests.perDeviceId.perDay, rateLimiting.otpRequests.perDeviceId.perHour, rateLimiting.otpRequests.perDeviceId.perMinute, rateLimiting.otpRequests.perPhoneNumber.perDay, rateLimiting.otpRequests.perPhoneNumber.perHour, rateLimiting.otpRequests.perPhoneNumber.perMinute, rateLimiting.otpRequests.perWidget.perDay, rateLimiting.otpRequests.perWidget.perHour, rateLimiting.otpRequests.perWidget.perMinute, rateLimiting.widgetAttempts.perDeviceId.perDay, rateLimiting.widgetAttempts.perDeviceId.perHour, rateLimiting.widgetAttempts.perDeviceId.perMinute, rateLimiting.widgetAttempts.perPhoneNumber.perDay, rateLimiting.widgetAttempts.perPhoneNumber.perHour, rateLimiting.widgetAttempts.perPhoneNumber.perMinute, rateLimiting.widgetAttempts.perWidget.perDay, rateLimiting.widgetAttempts.perWidget.perHour, rateLimiting.widgetAttempts.perWidget.perMinute, expectedUpdatedAt. Tip: Start with the default limits unless your traffic needs different ones. Use traffic recommendations when enough history is available; their calculations include a 10% growth buffer. Final screen recommendations also apply per-phone and per-device caps and may raise per-screen hour and day limits to meet the required ratios, so applied values can differ from the buffered calculation. Review the result against expected peaks before changing live limits.
--circuit-breakerenumon | offCommand-specific option; see the full command details below. Manifest body field: circuitBreaker.enabled, expectedUpdatedAt. Tip: Keep the circuit breaker on; Akedly recommends it to protect verification from flood attacks and traffic spikes.
--circuit-breaker-filetext—Command-specific option; see the full command details below. Manifest body field: circuitBreaker.floodThresholds.per15Minutes, circuitBreaker.floodThresholds.per5Minutes, circuitBreaker.floodThresholds.perMinute, circuitBreaker.suspensionDurations.firstViolation, circuitBreaker.suspensionDurations.maxViolation, circuitBreaker.suspensionDurations.secondViolation, expectedUpdatedAt. Tip: Keep the circuit breaker on; Akedly recommends it to protect verification from flood attacks and traffic spikes.
--powenumon | offCommand-specific option; see the full command details below. Manifest body field: security.pow.allowed. Tip: Keep the default proof-of-work settings unless you face sustained heavy abuse. For an expected launch or campaign surge, raise the rate limits and circuit breaker flood thresholds first instead of lowering the proof-of-work trigger, so legitimate traffic is not challenged too early.
--pow-trigger-percentinteger25 to 95Command-specific option; see the full command details below. Manifest body field: security.pow.triggerPercent. Tip: Keep the default proof-of-work settings unless you face sustained heavy abuse. For an expected launch or campaign surge, raise the rate limits and circuit breaker flood thresholds first instead of lowering the proof-of-work trigger, so legitimate traffic is not challenged too early.
--pow-starting-difficultyinteger3 to 6Command-specific option; see the full command details below. Manifest body field: security.pow.startDifficulty. Tip: Keep the default proof-of-work settings unless you face sustained heavy abuse. For an expected launch or campaign surge, raise the rate limits and circuit breaker flood thresholds first instead of lowering the proof-of-work trigger, so legitimate traffic is not challenged too early.
--pow-maximum-difficultyinteger3 to 6Command-specific option; see the full command details below. Manifest body field: security.pow.maxDifficulty. Tip: Keep the default proof-of-work settings unless you face sustained heavy abuse. For an expected launch or campaign surge, raise the rate limits and circuit breaker flood thresholds first instead of lowering the proof-of-work trigger, so legitimate traffic is not challenged too early.
--appearance-filetext—Command-specific option; see the full command details below. Manifest body field: branding.appearance, branding.appearance.language, branding.appearance.theme.colors.primary, branding.customPrimaryColor, branding.appearance.theme.colors.secondary, branding.customSecondaryColor, branding.appearance.theme.mode, branding.theme.
--recommended-limitsboolean switch—Command-specific option; see the full command details below. Manifest body field: rateLimiting.otpRequests.perDeviceId.perDay, rateLimiting.otpRequests.perDeviceId.perHour, rateLimiting.otpRequests.perDeviceId.perMinute, rateLimiting.otpRequests.perPhoneNumber.perDay, rateLimiting.otpRequests.perPhoneNumber.perHour, rateLimiting.otpRequests.perPhoneNumber.perMinute, rateLimiting.otpRequests.perWidget.perDay, rateLimiting.otpRequests.perWidget.perHour, rateLimiting.otpRequests.perWidget.perMinute, rateLimiting.widgetAttempts.perDeviceId.perDay, rateLimiting.widgetAttempts.perDeviceId.perHour, rateLimiting.widgetAttempts.perDeviceId.perMinute, rateLimiting.widgetAttempts.perPhoneNumber.perDay, rateLimiting.widgetAttempts.perPhoneNumber.perHour, rateLimiting.widgetAttempts.perPhoneNumber.perMinute, rateLimiting.widgetAttempts.perWidget.perDay, rateLimiting.widgetAttempts.perWidget.perHour, rateLimiting.widgetAttempts.perWidget.perMinute, circuitBreaker.floodThresholds.per15Minutes, circuitBreaker.floodThresholds.per5Minutes, circuitBreaker.floodThresholds.perMinute, circuitBreaker.suspensionDurations.firstViolation, circuitBreaker.suspensionDurations.maxViolation, circuitBreaker.suspensionDurations.secondViolation, circuitBreaker.enabled, expectedUpdatedAt. Tip: Start with the default limits unless your traffic needs different ones. Use traffic recommendations when enough history is available; their calculations include a 10% growth buffer. Final screen recommendations also apply per-phone and per-device caps and may raise per-screen hour and day limits to meet the required ratios, so applied values can differ from the buffered calculation. Review the result against expected peaks before changing live limits.
--periodenumlast-month | last-quarter | last-6-monthsCommand-specific option; see the full command details below.
--smart-routingenumon | offCommand-specific option; see the full command details below. Manifest body field: smartRouting, expectedUpdatedAt.
--passkeysenumon | offCommand-specific option; see the full command details below. Manifest body field: passkeyEnabled, expectedUpdatedAt. Tip: Passkeys let returning users verify with Face ID or a fingerprint, and a passkey sign-in can cost up to 40% less than an OTP at the default passkey rate; your account's rate may differ.
--cluster-gateenumon | offCommand-specific option; see the full command details below. Manifest body field: securityConfig.clusterGate.enabled, clusterGateIntent, expectedUpdatedAt.
--cluster-gate-positionenumcautious | balanced | assertiveCommand-specific option; see the full command details below. Manifest body field: securityConfig.clusterGate.position, clusterGateIntent, expectedUpdatedAt. Tip: Balanced is the default position. Estimated during an attack, Cautious blocks about 65% of spam and refuses no real users, Balanced about 90% of spam and about 1% of real users, and Assertive 95% or more of spam and about 3% of real users. Assertive is outside Akedly's recommended limits: it does not check whether a request is a real user caught in the same flood. Refusals are rare outside an attack.
--cluster-gate-escalationenumon | offCommand-specific option; see the full command details below. Manifest body field: securityConfig.clusterGate.escalation, clusterGateIntent, expectedUpdatedAt.
--cluster-gate-home-countrieslist—Command-specific option; see the full command details below. Manifest body field: securityConfig.clusterGate.homeCountries, clusterGateIntent, expectedUpdatedAt. Tip: Declare the countries where you expect phone destinations and end-user IPs to help Cluster Gate understand your traffic. Home countries do not restrict sending or allow or block IP addresses, and other protections still apply. Learned countries stay included automatically; clearing declarations does not clear the learned set.
--otp-languageenumen | arCommand-specific option; see the full command details below. Manifest body field: locale, expectedUpdatedAt.
--channel-choiceenumon | offCommand-specific option; see the full command details below. Manifest body field: channelChoiceEnabled, expectedUpdatedAt.
--channel-choice-modeenumask-first | send-firstCommand-specific option; see the full command details below. Manifest body field: channelChoiceMode, expectedUpdatedAt.
--channel-choice-enforcementenumfallback | hard-pinCommand-specific option; see the full command details below. Manifest body field: channelChoiceEnforcement, expectedUpdatedAt.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: widgets:update.

Server request: PUT /widgets/:id.

Shared server-guard guidance.

Consent

--yes when --status or --integration-id or --dev-mode or --dev-mode-digits or --rate-limits-file or --circuit-breaker or --circuit-breaker-file or --pow or --pow-trigger-percent or --pow-starting-difficulty or --pow-maximum-difficulty or --recommended-limits or --smart-routing or --passkeys or --cluster-gate or --cluster-gate-position or --cluster-gate-escalation or --cluster-gate-home-countries or --otp-language or --channel-choice or --channel-choice-mode or --channel-choice-enforcement is given. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

idempotent: Idempotent requests retry network errors and HTTP 429/502/503/504, at most 3 tries, waiting for cooldownSeconds, retryAfter or the Retry-After header (otherwise 1 second) between tries, up to 30 seconds; a longer requested wait is returned as the error.

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Edit an owned screen using its 24-hex Mongo _id from akedly integrations screens list. Requires Full access and widgets:update. Supply at least one editable field; omitted settings are preserved. Use none to clear description or optional scalar branding values, and --integration-id none to detach. --status takes active|inactive. Attach a gateway integration (both the Return URL and the Server URL are needed only once it is Live), or a legacy integration if entitled; headless cannot attach. --rate-limits-file <file> takes a JSON object with widgetAttempts and/or otpRequests, each containing perPhoneNumber, perDevice and/or perWidget, each with perMinute, perHour and/or perDay; for example {"widgetAttempts":{"perWidget":{"perMinute":30,"perHour":150,"perDay":3000}}}. It changes only the named limits. Numbers must be whole and above zero. Per-phone and per-device limits cannot exceed 5/minute, 25/hour or 50/day; each per-screen hour limit must be at least 5 times its minute limit and its day limit at least 100 times its minute limit. Explicit file changes do not automatically recalculate other windows; include every adjustment needed to satisfy the ratios. Inspect details.errors for server validation failures. --circuit-breaker on|off sets whether the breaker is enabled. --circuit-breaker-file <file> accepts floodThresholds with perMinute, per5Minutes and per15Minutes, and suspensionSeconds with firstViolation, secondViolation and maxViolation. Supply only the values to change, as whole numbers above zero; durations are in seconds. The file may be combined with --circuit-breaker, and omitted thresholds and durations are preserved. --pow on|off allows proof-of-work; --pow-trigger-percent takes 25..95, and --pow-starting-difficulty and --pow-maximum-difficulty take 3..6. Starting difficulty must not exceed maximum difficulty. When one difficulty changes, the server compares it with the other supplied or stored value, using 3 for an unset start and 5 for an unset maximum. Unset values are not filled into storage by that comparison; server policy still controls proof-of-work at runtime. Use --company-name, --logo, --favicon-url, --screen-language en|ar, --primary-color and --secondary-color for common branding, or --appearance-file <file> for the appearance object itself, without a branding or appearance wrapper; for example {"theme":{"mode":"dark"}}. The server validates keys and values, including null, empty strings and numeric strings, and refuses unknown keys with APPEARANCE_FIELD_UNKNOWN. Files must be readable regular JSON object files of at most 64 KiB. Appearance keys cannot contain dots or be __proto__, prototype or constructor. Do not supply the same appearance leaf through both a file and a scalar flag; disjoint values may be combined. --recommended-limits applies recommendations based on account-wide screen traffic over --period last-month|last-quarter|last-6-months (default last-month). It replaces all 18 rate limits and enables the circuit breaker with recommended thresholds and suspension durations. The server caps per-phone and per-device limits at 5/minute, 25/hour and 50/day, raises per-screen hour and day limits when needed to at least 5 and 100 times the minute limit, and keeps the breaker minute threshold at least twice the larger per-screen minute limit. It leaves proof-of-work, appearance and breaker state unchanged. NOT_ENOUGH_TRAFFIC means no update was sent; details.confidence and details.analysedRequests explain the result. Recommendations cannot be combined with --rate-limits-file, --circuit-breaker or --circuit-breaker-file. --period works only with --recommended-limits. For rate-limit, breaker or recommendation changes, the CLI first reads the screen and sends the revision it read; this also needs widgets:read. If the screen changes before the save, WIDGET_CHANGED refuses the request; run the command again to read its current settings. A write carrying that revision and the recommendation request made while planning are not automatically retried after network or server errors; the explicit CLI_RATE_LIMITED refusal exception still applies. After an uncertain write result, inspect akedly integrations screens get <id> before rerunning. Enable Developer mode with --dev-mode on --dev-mode-digits 4 --yes; digits require --dev-mode on in the same command. Captcha requirements and cooldowns cannot be changed here. Supplying status, integration-id (including none), dev-mode, dev-mode-digits, any rate-limit, breaker or proof-of-work flag, or recommended-limits requires --yes because it can stop, reroute or loosen live verification, even when disabling a protection. Identity and branding changes need no --yes. --dry-run previews without --yes or a write; rate-limit, breaker and recommendation changes still make their planning reads and need the same permissions as a real run. Server validation runs only on the real update. Integration settings --passkeys, --smart-routing, --otp-language, --cluster-gate, --cluster-gate-position, --cluster-gate-escalation, --cluster-gate-home-countries, --channel-choice, --channel-choice-mode and --channel-choice-enforcement can be supplied here with --yes. They are written to the resulting attached integration after the screen is saved; an attachment change targets the new integration. Both write permissions are checked first. Each update carries the revision read during planning. A partial update names the saved and unconfirmed resources; after create, keep the saved Secret and use the provided integration update recovery command instead of creating again. --dry-run lists every planned write and saves nothing.

Login 429 guidance.

Worked examples

Examples are synthetic illustrations, never live account records. Replace resource IDs with your own authorized resources. Secret values are omitted here; redacted examples illustrate the shape and are not schema-validation fixtures.

Synthetic integrations screens update workflow

Change screen identity, appearance, rate limits, circuit breaker, PoW or linked integration settings.

sh
akedly integrations screens update 0123456789abcdef01234567 --name 'Example widget' --yes

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "_id": "0123456789abcdef01234567",
    "name": "Example widget",
    "status": "active",
    "updatedAt": "2030-03-12T09:00:00.000Z"
  }
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

Synthetic screen settings update from three JSON files

Update one existing screen's request ceilings, flood suspension policy, and appearance together.

sh
akedly integrations screens update 0123456789abcdef01234567 --rate-limits-file ./fixtures/widget-rate-limits.json --circuit-breaker-file ./fixtures/widget-circuit-breaker.json --appearance-file ./fixtures/widget-appearance.json --yes

Input file: ./fixtures/widget-rate-limits.json (json).

json
{
  "otpRequests": {
    "perWidget": {
      "perMinute": 30
    }
  }
}

Input file: ./fixtures/widget-circuit-breaker.json (json).

json
{
  "floodThresholds": {
    "perMinute": 20,
    "per5Minutes": 60,
    "per15Minutes": 120
  },
  "suspensionSeconds": {
    "firstViolation": 60,
    "secondViolation": 300,
    "maxViolation": 1800
  }
}

Input file: ./fixtures/widget-appearance.json (json).

json
{
  "language": "en",
  "theme": {
    "colors": {
      "primary": "#336699",
      "secondary": null
    }
  }
}

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "_id": "0123456789abcdef01234567",
    "name": "Example widget",
    "status": "active",
    "updatedAt": "2030-03-12T09:00:00.000Z"
  }
}

Prerequisites: an authorized CLI login and an existing screen owned by the account. The example ID is synthetic; confirm the actual screen with integrations screens get first.

The input files set screen OTP-request limits, circuit-breaker thresholds and suspension seconds, and appearance. The CLI reads the current screen revision before saving. Do not combine these explicit limits with --recommended-limits.

After success, inspect screens get. If the command reports PARTIAL_UPDATE, inspect the screen and each linked resource listed in applied/notApplied before retrying.

Additional command forms

sh
akedly integrations screens update <id> --company-name Example --screen-language en
sh
akedly integrations screens update <id> --dev-mode on --dev-mode-digits 4 --yes

Input and file contracts

The contract below describes typed arguments, file formats, validation boundaries and API mappings. Boolean switches take no value; numeric and comma-separated values are each passed as one argument. Read prerequisites and full command details for state-dependent requirements.

Response contract

The CLI preserves the server success envelope and passes through resource-specific fields; additional data fields are server extensions, not fields this command promises to synthesize.

Protected linked-resource writes can be partial; honor PARTIAL_UPDATE details and inspect each named resource before retrying.

Own recovery guidance

CodeHint
WIDGET_CHANGEDRun akedly integrations screens get <id> to inspect the current settings, then rerun the intended update. The command reads a fresh revision; do not reuse an old request body to overwrite another change.
WIDGET_POW_INVALIDUse --pow on|off, --pow-trigger-percent 25..95, and --pow-starting-difficulty and --pow-maximum-difficulty 3..6. Starting difficulty must not exceed maximum difficulty. If changing only one difficulty, inspect the other with akedly integrations screens get <id>; an unset start is compared as 3 and an unset maximum as 5.
APPEARANCE_FIELD_UNKNOWNRemove or correct the appearance key named in details.field in --appearance-file. Supply the appearance object itself without a branding or appearance wrapper; the server decides which keys and values are supported. Unknown keys are refused rather than dropped.
SCREEN_NOT_ALLOWED_ON_V12A V1.2 (headless) integration cannot have gateway screens. Pass --integration-id of a V2.0 (gateway) integration instead; akedly integrations list shows each type.

Common error guidance.

integrations screens delete

Deactivate an embedded screen while preserving its stored identity and historical record.

When to use

  • Use after removing its embed from applications and checking whether its one-time Secret is still needed.

How it works

  1. Requires confirmation and requests deletion; dry-run only previews.

Prerequisites

  • A CLI login with permission for this account and resource.

Expected outcome

The screen record remains and status becomes inactive; the response data contains widgetId and status.

Next steps

  • Remove the inactive screen from the host application; retain the ID for audit and historical reference.

Usage

sh
akedly integrations screens delete <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "integrations screens delete" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Use the 24-hex Mongo screen _id.

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--yesboolean switch—Confirm this action where consent is required.
--dry-runboolean switch—Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: widgets:delete.

Server request: DELETE /widgets/:id.

Shared server-guard guidance.

Consent

--yes. --dry-run bypasses confirmation where supported. Destructive: true. Spends money: false. Real send: false.

Retry

write: Non-idempotent writes are not automatically retried. guarded-write: when an update carries the revision read from the server, its write is not automatically retried after network errors or HTTP 429/502/503/504. It may already be saved; inspect the resource before rerunning. A rerun reads current settings again. The explicit CLI_RATE_LIMITED refusal exception below still applies. recommendation-read: the recommendation request made while planning --recommended-limits is not automatically retried after network errors or HTTP 429/502/503/504. If planning fails, no update is sent; rerun the command to request a new recommendation. The explicit CLI_RATE_LIMITED refusal exception below still applies. This label does not change the retry policy of the standalone rate-recommendations command.

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Soft-delete a screen using its 24-hex Mongo _id; --yes required. Restore with integrations screens update <id> --status active --yes.

Login 429 guidance.

Worked examples

Examples are synthetic illustrations, never live account records. Replace resource IDs with your own authorized resources. Secret values are omitted here; redacted examples illustrate the shape and are not schema-validation fixtures.

Synthetic integrations screens delete workflow

Remove a screen that should no longer be embedded or accept verification attempts.

sh
akedly integrations screens delete 0123456789abcdef01234567 --yes

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "message": "Widget deleted successfully (soft delete)",
  "data": {
    "widgetId": "widget_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "status": "inactive"
  }
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

Additional command forms

sh
akedly integrations screens delete <id> --yes

Input and file contracts

The contract below describes typed arguments, file formats, validation boundaries and API mappings. Boolean switches take no value; numeric and comma-separated values are each passed as one argument. Read prerequisites and full command details for state-dependent requirements.

Response contract

The CLI preserves the server success envelope and passes through resource-specific fields; additional data fields are server extensions, not fields this command promises to synthesize.

Common error guidance.

integrations screens pow-meta

Read the server’s allowed proof-of-work parameters for screens before tuning screen PoW.

When to use

  • Use when configuring a screen’s PoW difficulty or validating a policy refusal.

How it works

  1. Reads the screen PoW policy metadata.

Prerequisites

  • A CLI login with permission for this account and resource.

Expected outcome

Policy settings returned by the server.

Next steps

  • Select values within the returned policy bounds.

Usage

sh
akedly integrations screens pow-meta

Inspect this command offline before preparing an operation:

sh
akedly describe "integrations screens pow-meta" --output json

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: widgets:read.

Server request: GET /widgets/pow-meta.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

idempotent: Idempotent requests retry network errors and HTTP 429/502/503/504, at most 3 tries, waiting for cooldownSeconds, retryAfter or the Retry-After header (otherwise 1 second) between tries, up to 30 seconds; a longer requested wait is returned as the error.

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Read proof-of-work policy metadata. Read-only logins are allowed.

Login 429 guidance.

Worked examples

Examples are synthetic illustrations, never live account records. Replace resource IDs with your own authorized resources. Secret values are omitted here; redacted examples illustrate the shape and are not schema-validation fixtures.

Synthetic integrations screens pow-meta workflow

Read the server’s allowed proof-of-work parameters for screens before tuning screen PoW.

sh
akedly integrations screens pow-meta

Illustrative response (sensitive values omitted):

json
{
  "levels": [
    {
      "difficulty": 3,
      "label": "Easy",
      "estimateMobile": "instant (<0.2s)",
      "estimateDesktop": "<0.1s"
    },
    {
      "difficulty": 4,
      "label": "Light",
      "estimateMobile": "~0.5–3s",
      "estimateDesktop": "~0.2–1s"
    },
    {
      "difficulty": 5,
      "label": "Medium",
      "estimateMobile": "~7s (up to ~45s on slower phones)",
      "estimateDesktop": "~2–10s"
    },
    {
      "difficulty": 6,
      "label": "Heavy",
      "estimateMobile": "~40s–4min",
      "estimateDesktop": "~30–90s",
      "warn": "Not recommended — may exceed the verification window on mobile."
    }
  ],
  "hardMaxDifficulty": 5
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

Additional command forms

sh
akedly integrations screens pow-meta

Input and file contracts

The contract below describes typed arguments, file formats, validation boundaries and API mappings. Boolean switches take no value; numeric and comma-separated values are each passed as one argument. Read prerequisites and full command details for state-dependent requirements.

Response contract

The CLI preserves the server success envelope and passes through resource-specific fields; additional data fields are server extensions, not fields this command promises to synthesize.

Common error guidance.

Upload a local screen logo image and obtain a hosted URL for screen branding.

When to use

  • Use when branding needs a logo URL and the source image is available locally.

How it works

  1. Reads and validates the local image then uploads it to the configured image service; this is an external write and dry-run does not upload.

Prerequisites

  • A CLI login with permission for this account and resource.

Expected outcome

An image-provider-hosted URL and upload dimensions; the command does not itself save the URL to a screen.

Next steps

  • Pass the returned URL to integrations screens update to save the branding change.

Usage

sh
akedly integrations screens upload-logo

Inspect this command offline before preparing an operation:

sh
akedly describe "integrations screens upload-logo" --output json

Flags

FlagTypeEnum / rangeRequiredDescription
--ksaboolean switch—noSelect the KSA deployment.
--filetext—yesCommand-specific option; see the full command details below. Manifest body field: fileURL.
--dry-runboolean switch—noPreview without sending the write or creating output files; planning reads may still occur. Bypass consent.
--helpboolean switch—noShow offline command help.
--outputenumjson | humannoSelect JSON or human output.
--fieldsdot-paths—noSelect comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: widgets:update.

Server request: POST /cloudinary/uploadWidgetLogo.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

write: Non-idempotent writes are not automatically retried. guarded-write: when an update carries the revision read from the server, its write is not automatically retried after network errors or HTTP 429/502/503/504. It may already be saved; inspect the resource before rerunning. A rerun reads current settings again. The explicit CLI_RATE_LIMITED refusal exception below still applies. recommendation-read: the recommendation request made while planning --recommended-limits is not automatically retried after network errors or HTTP 429/502/503/504. If planning fails, no update is sent; rerun the command to request a new recommendation. The explicit CLI_RATE_LIMITED refusal exception below still applies. This label does not change the retry policy of the standalone rate-recommendations command.

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Upload one local PNG, JPEG, GIF or WebP regular file, at most 3 MiB (no SVG). Requires Full access. Then store the returned URL with akedly integrations screens update <id> --logo <url>.

Login 429 guidance.

Worked examples

Examples are synthetic illustrations, never live account records. Replace resource IDs with your own authorized resources. Secret values are omitted here; redacted examples illustrate the shape and are not schema-validation fixtures.

Synthetic integrations screens upload-logo workflow

Upload a local screen logo image and obtain a hosted URL for screen branding.

sh
akedly integrations screens upload-logo --file ./logo.png

Input file: ./logo.png (base64).

text
iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAIAAABLbSncAAAAEUlEQVR4nGPQyNuCFTEMLQkAGahSgZLbNF8AAAAASUVORK5CYII=

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "url": "https://images.example.invalid/widget-logo.png"
  },
  "message": "Logo uploaded successfully"
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

The synthetic PNG is 8×8 pixels, meeting the logo-upload minimum dimension. Uploading it contacts the image provider; this example is documentation only.

Additional command forms

sh
akedly integrations screens upload-logo --file <image>
sh
akedly integrations screens update <id> --logo <returned-url>

Input and file contracts

The contract below describes typed arguments, file formats, validation boundaries and API mappings. Boolean switches take no value; numeric and comma-separated values are each passed as one argument. Read prerequisites and full command details for state-dependent requirements.

Response contract

The CLI preserves the server success envelope and passes through resource-specific fields; additional data fields are server extensions, not fields this command promises to synthesize.

Common error guidance.

integrations screens rate-recommendations

Estimate screen rate limits and circuit-breaker values from observed traffic.

When to use

  • Use before applying screen protections; enough traffic is required for ready recommendations.

How it works

  1. Requests account-level recommendation analysis for the selected period or date range; no screen settings are changed.

Prerequisites

  • A CLI login with permission for this account and resource.

Expected outcome

Analysis readiness/confidence and recommended setting fields.

Next steps

  • Apply reviewed values with integrations screens update; do not apply when traffic confidence is low.

Usage

sh
akedly integrations screens rate-recommendations

Inspect this command offline before preparing an operation:

sh
akedly describe "integrations screens rate-recommendations" --output json

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--periodenumlast-month | last-quarter | last-6-monthsCommand-specific option; see the full command details below. Manifest body field: period.
--start-datetext—Command-specific option; see the full command details below. Manifest body field: customDateRange.sDate.
--end-datetext—Command-specific option; see the full command details below. Manifest body field: customDateRange.eDate.
--dry-runboolean switch—Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: widgets:update.

Server request: POST /widget-rate-recommendations.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

idempotent: Idempotent requests retry network errors and HTTP 429/502/503/504, at most 3 tries, waiting for cooldownSeconds, retryAfter or the Retry-After header (otherwise 1 second) between tries, up to 30 seconds; a longer requested wait is returned as the error.

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Read your screen rate recommendations. Requires Full access; dates use server-local-day semantics; default period last-month.

Login 429 guidance.

Worked examples

Examples are synthetic illustrations, never live account records. Replace resource IDs with your own authorized resources. Secret values are omitted here; redacted examples illustrate the shape and are not schema-validation fixtures.

Synthetic integrations screens rate-recommendations workflow

Estimate screen rate limits and circuit-breaker values from observed traffic.

sh
akedly integrations screens rate-recommendations --period last-month

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "applyReady": {
      "enoughTraffic": true,
      "confidence": "high",
      "analysedRequests": 250,
      "settings": {
        "rateLimiting": {
          "otpRequests": {
            "perWidget": {
              "perMinute": 30,
              "perHour": 600,
              "perDay": 3000
            }
          }
        }
      }
    }
  }
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

Additional command forms

sh
akedly integrations screens rate-recommendations

Input and file contracts

The contract below describes typed arguments, file formats, validation boundaries and API mappings. Boolean switches take no value; numeric and comma-separated values are each passed as one argument. Read prerequisites and full command details for state-dependent requirements.

Response contract

The CLI preserves the server success envelope and passes through resource-specific fields; additional data fields are server extensions, not fields this command promises to synthesize.

Common error guidance.

integrations screens overview

Review account-wide screen analytics at a glance.

When to use

  • Use for a high-level screen usage snapshot before drilling into an individual screen.

How it works

  1. Reads the screen analytics overview without changing configuration.

Prerequisites

  • A CLI login with permission for this account and resource.

Expected outcome

Overview metrics returned by the server.

Next steps

  • Open integrations screens get for a specific screen.

Usage

sh
akedly integrations screens overview

Inspect this command offline before preparing an operation:

sh
akedly describe "integrations screens overview" --output json

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--helpboolean switch—Show offline command help.
--outputenumjson | humanSelect JSON or human output.
--fieldsdot-paths—Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: widgets:read.

Server request: GET /widget-analytics/overview.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

idempotent: Idempotent requests retry network errors and HTTP 429/502/503/504, at most 3 tries, waiting for cooldownSeconds, retryAfter or the Retry-After header (otherwise 1 second) between tries, up to 30 seconds; a longer requested wait is returned as the error.

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Read a last-24-hours overview of your active and inactive screens; the window is fixed. Read-only logins are allowed.

Login 429 guidance.

Worked examples

Examples are synthetic illustrations, never live account records. Replace resource IDs with your own authorized resources. Secret values are omitted here; redacted examples illustrate the shape and are not schema-validation fixtures.

Synthetic integrations screens overview workflow

Review account-wide screen analytics at a glance.

sh
akedly integrations screens overview

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": [
    {
      "widgetId": "widget_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "name": "Example widget",
      "status": "active",
      "currentStatus": {
        "online": "idle",
        "lastAttemptAt": null
      },
      "health": {
        "status": "healthy",
        "message": "No recent failures",
        "captchaSuccessRate": 100
      },
      "concurrentUsers": {
        "current": 0,
        "last24Hours": 0
      },
      "last24HourMetrics": {
        "totalAttempts": 0,
        "verificationRate": 100,
        "statusBreakdown": {},
        "avgVerificationTime": 0
      }
    }
  ]
}

Assumes an authorized account and the referenced resource exists where required. All values and IDs are synthetic; this example is documentation only.

Additional command forms

sh
akedly integrations screens overview

Input and file contracts

The contract below describes typed arguments, file formats, validation boundaries and API mappings. Boolean switches take no value; numeric and comma-separated values are each passed as one argument. Read prerequisites and full command details for state-dependent requirements.

Response contract

The CLI preserves the server success envelope and passes through resource-specific fields; additional data fields are server extensions, not fields this command promises to synthesize.

Common error guidance.