Skip to content
Akedly
Command reference

Widgets

Akedly CLI command reference: Widgets.

Build with AI agents

widgets list

Browse the account’s widgets to find a widget ID, status, or display name.

When to use

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

How it works

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

Prerequisites

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

Expected outcome

Widget rows returned by the server.

Next steps

  • Use the 24-hex _id with widgets get/update, or the public widgetId with widgets analytics.

Usage

sh
akedly widgets list

Inspect this command offline before preparing an operation:

sh
akedly describe "widgets 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 widgets; inactive widgets are hidden unless --status is supplied. Read-only logins are allowed. For a returned widget, this read may disable an expired dev-mode window and delete passkeys enrolled with its Test Pair phone.

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 widgets list workflow

Browse the account’s widgets to find a widget ID, status, or display name.

sh
akedly widgets 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 widgets 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.

widgets list-filtered

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

When to use

  • Use when locating all widgets attached to a pipeline; include inactive status because default listings omit inactive widgets.

How it works

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

Prerequisites

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

Expected outcome

Widget rows plus pagination metadata.

Next steps

  • Inspect a candidate using widgets get; for pipeline fan-out ensure inactive attachments are considered.

Usage

sh
akedly widgets list-filtered

Inspect this command offline before preparing an operation:

sh
akedly describe "widgets 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.
--pipeline-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 widgets with additional filters and owner profile fields. Read-only logins are allowed. For a returned widget, this read may disable an expired dev-mode window and delete passkeys enrolled with its Test Pair phone.

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 widgets list-filtered workflow

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

sh
akedly widgets list-filtered --pipeline-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 widgets 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.

widgets get

Inspect one widget’s current pipeline attachment, status, branding and security settings.

When to use

  • Use before editing or diagnosing widget behavior.

How it works

  1. Reads a widget by its Mongo _id.

Prerequisites

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

Expected outcome

Current widget resource.

Next steps

  • Use widgets update for changes; keep its current pipeline/API-version constraints in mind.

Usage

sh
akedly widgets get <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "widgets get" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Use the 24-hex Mongo widget _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 widget using its 24-hex Mongo _id. Dev mode returns the fake-number Test Pair; the widget Secret is never shown. Open this widget in the dashboard studio with `akedly widgets studio <id>`; opening and saving it there needs the `widgets:update` permission. For a returned widget, this read may disable an expired dev-mode window and delete passkeys enrolled with its Test Pair phone.

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 widgets get workflow

Inspect one widget’s current pipeline attachment, status, branding and security settings.

sh
akedly widgets 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 widgets 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.

widgets studio

Open the dashboard editor for a widget’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 widget; 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 widgets get.

Usage

sh
akedly widgets studio <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "widgets studio" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Use the 24-hex Mongo widget _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: widgets 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 widget'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. It does not save branding. After the owner saves, akedly widgets get <id> shows the saved branding. The lookup is a normal widget read, so, as on any widget read, the server may disable an expired dev-mode window and delete passkeys enrolled with its Test Pair phone. 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 widget id with akedly widgets list (add --status inactive for inactive widgets).

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 widgets studio workflow

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

sh
akedly widgets studio 0123456789abcdef01234567

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "handoff": {
      "action": "widgets studio",
      "path": "/admin/widgets/0123456789abcdef01234567/branding",
      "url": "https://app.example.invalid/admin/widgets/0123456789abcdef01234567/branding",
      "requested": "Edit the widget'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 widgets studio <id>
sh
akedly widgets 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.

widgets create

Create an embeddable verification widget attached to a ready pipeline.

When to use

  • Use to add a customer-facing web verification surface on a ready pipeline. V1 requires the account entitlement; V2 needs both callback URLs. V1.2 pipelines cannot be attached to widgets.

How it works

  1. Validates optional branding/security files; may read the linked pipeline and permissions for linked settings; creates the widget, writes its one-time Secret, then applies linked pipeline 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 V1 or V2 pipeline; V1 requires widget entitlement and V2 requires frontend and backend callback URLs.
  • A new private output path for the one-time widget Secret.

Expected outcome

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

Next steps

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

Usage

sh
akedly widgets create

Inspect this command offline before preparing an operation:

sh
akedly describe "widgets 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.
--pipeline-idid—noCommand-specific option; see the full command details below. Manifest body field: pipelineId. Tip: Attach widgets to a V2 pipeline. A legacy V1 pipeline is still accepted but lacks V2's security and widget features, and a V1.2 pipeline 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.
--widget-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 widget recommendations also apply per-phone and per-device caps and may raise per-widget 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 widget with --name and --secret-file <new path>; --pipeline-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 widget Secret cannot be revealed or recovered later. After an ambiguous create failure, run akedly widgets list before intentionally creating another widget. Attach a V2 pipeline with both callback URLs, or a V1 pipeline if entitled; V1.2 cannot attach. An unattached widget cannot send. Omitted settings start with the dashboard values: widget 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-widget 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-widget 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, --widget-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. Widget-only creation needs no --yes; changes to linked pipeline settings need --yes. Status and dev mode are update-only; captcha requirements and cooldowns cannot be changed here. Widget-only --dry-run checks inputs locally without contacting the server; linked pipeline 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 widget in the dashboard studio with `akedly widgets studio <id>`; opening and saving it there needs the `widgets:update` permission. Pipeline 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 pipeline after the widget is saved; an attachment change targets the new pipeline. 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 pipeline 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 widgets create workflow

Create an embeddable verification widget attached to a ready pipeline.

sh
akedly widgets create --name 'Example widget' --pipeline-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 pipeline must be an existing ready V1 or V2 pipeline; 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 widget creation with limits, breaker, and appearance files

Create a customer-facing widget with explicit abuse limits and appearance settings on a ready V2 pipeline.

sh
akedly widgets create --name 'Example widget' --pipeline-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 V2 pipeline. The synthetic pipeline ID must be replaced with an existing pipeline; V1.2 pipelines cannot be attached to widgets.

The three JSON files configure widget-level OTP-request limits, circuit-breaker thresholds and durations, and appearance. The create call also writes the widget'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 widget settings. If a linked write is partial, inspect both the widget and pipeline before continuing.

Additional command forms

sh
akedly widgets create --name Example --pipeline-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 widgets 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 widgets 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.

Common error guidance.

widgets update

Change widget identity, appearance, rate limits, circuit breaker, PoW or linked pipeline settings.

When to use

  • Use after widgets get; supply the widget _id and only the settings intended for that widget/pipeline.

How it works

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

Prerequisites

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

Expected outcome

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

Next steps

  • On PARTIAL_UPDATE inspect both widget and pipeline before retrying; revisions are read automatically.

Usage

sh
akedly widgets update <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "widgets update" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Use the 24-hex Mongo widget _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.
--pipeline-idid—Command-specific option; see the full command details below. Manifest body field: pipelineId. The literal none clears this value. Tip: Attach widgets to a V2 pipeline. A legacy V1 pipeline is still accepted but lacks V2's security and widget features, and a V1.2 pipeline 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.
--widget-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 dev 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 widget recommendations also apply per-phone and per-device caps and may raise per-widget 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 widget recommendations also apply per-phone and per-device caps and may raise per-widget 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 --pipeline-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 widget using its 24-hex Mongo _id from akedly widgets 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 --pipeline-id none to detach. --status takes active|inactive. Attach a V2 pipeline with both callback URLs, or a V1 pipeline if entitled; V1.2 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-widget 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, --widget-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 widget 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-widget 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-widget 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 widget and sends the revision it read; this also needs widgets:read. If the widget 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 widgets get <id> before rerunning. Enable dev 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, pipeline-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. Pipeline 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 pipeline after the widget is saved; an attachment change targets the new pipeline. 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 pipeline 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 widgets update workflow

Change widget identity, appearance, rate limits, circuit breaker, PoW or linked pipeline settings.

sh
akedly widgets 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 widget settings update from three JSON files

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

sh
akedly widgets 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 widget owned by the account. The example ID is synthetic; confirm the actual widget with widgets get first.

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

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

Additional command forms

sh
akedly widgets update <id> --company-name Example --widget-language en
sh
akedly widgets 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 widgets 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 widgets 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.

Common error guidance.

widgets delete

Deactivate an embedded widget 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 widget record remains and status becomes inactive; the response data contains widgetId and status.

Next steps

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

Usage

sh
akedly widgets delete <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "widgets delete" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Use the 24-hex Mongo widget _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 widget using its 24-hex Mongo _id; --yes required. Restore with widgets 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 widgets delete workflow

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

sh
akedly widgets 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 widgets 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.

widgets pow-meta

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

When to use

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

How it works

  1. Reads the widget 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 widgets pow-meta

Inspect this command offline before preparing an operation:

sh
akedly describe "widgets 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 widgets pow-meta workflow

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

sh
akedly widgets 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 widgets 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 widget logo image and obtain a hosted URL for widget 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 widget.

Next steps

  • Pass the returned URL to widgets update to save the branding change.

Usage

sh
akedly widgets upload-logo

Inspect this command offline before preparing an operation:

sh
akedly describe "widgets 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 widgets 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 widgets upload-logo workflow

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

sh
akedly widgets 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 widgets upload-logo --file <image>
sh
akedly widgets 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.

widgets rate-recommendations

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

When to use

  • Use before applying widget 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 widget 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 widgets update; do not apply when traffic confidence is low.

Usage

sh
akedly widgets rate-recommendations

Inspect this command offline before preparing an operation:

sh
akedly describe "widgets 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 widget 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 widgets rate-recommendations workflow

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

sh
akedly widgets 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 widgets 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.

widgets analytics

Inspect verification and usage analytics for one public widget identifier.

When to use

  • Use to understand traffic and outcomes for a widget over a bounded date range.

How it works

  1. Reads analytics by public widgetId (widget_<32 lowercase hex>); date bounds are optional but must be supplied together.

Prerequisites

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

Expected outcome

Analytics summary and time-series fields returned by the API.

Next steps

  • Use the Mongo _id for resource edits; analytics requires the public widgetId.

Usage

sh
akedly widgets analytics <widgetId>

Inspect this command offline before preparing an operation:

sh
akedly describe "widgets analytics" --output json
PositionalGrammarUsage guidance
<widgetId>^widget_[a-f0-9]{32}$Use the public widget_<32 hex> widgetId for analytics.

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--start-datetext—Command-specific option; see the full command details below. Query parameter: startDate.
--end-datetext—Command-specific option; see the full command details below. Query parameter: endDate.
--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/:widgetId/analytics.

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 analytics using public widget_<32 hex> widgetId, not Mongo _id. Supply both date bounds or neither (neither date = last 24 hours); maximum 30 elapsed days. Read-only 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 widgets analytics workflow

Inspect verification and usage analytics for one public widget identifier.

sh
akedly widgets analytics widget_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "widget": {
      "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,
      "last1Minute": 0,
      "last5Minutes": 0,
      "last15Minutes": 0,
      "last1Hour": 0,
      "last24Hours": 0
    },
    "activityMetrics": {
      "totalAttempts": {
        "last24Hours": 0
      },
      "successRates": {
        "overallVerificationRate": 100
      },
      "statusBreakdown": {},
      "avgVerificationTime": 0,
      "hourlySuccessRates": []
    },
    "failureAnalysis": {
      "topFailureReasons": [],
      "failureTypeBreakdown": []
    },
    "channelBreakdown": [],
    "resendMetrics": {},
    "peakConcurrentUsers": 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 widgets analytics <widgetId>

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.

widgets overview

Review account-wide widget analytics at a glance.

When to use

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

How it works

  1. Reads the widget 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 widgets analytics for a specific public widgetId.

Usage

sh
akedly widgets overview

Inspect this command offline before preparing an operation:

sh
akedly describe "widgets 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 widgets; 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 widgets overview workflow

Review account-wide widget analytics at a glance.

sh
akedly widgets 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 widgets 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.