Skip to content
Akedly

Integration settings from the CLI

Change the settings you name and keep the rest. The CLI routes each change to the integration or its attached gateway screens.

Read, preview and save

bash
akedly integrations get <id>
akedly integrations update <id> --status active --dry-run
akedly integrations update <id> --status active --yes

Use a Full access CLI Login with permission to read and update the affected resources. --dry-run previews without consent or writes; it can still read the current settings, method catalog, attached gateway screens and recommendations. The server checks availability and validation on the real save.

The generated integrations update reference lists every flag, allowed value, setting tip and consent rule. Flags use feature names, such as --otp-language ar and --smart-routing on.

Where settings are saved

SettingHeadlessLegacy or gateway
Identity, status, environment, Return URL and Server URL, OTP webhook choices, delivery methods, routing, OTP language/template, destination countriesIntegrationIntegration
Rate limits and circuit-breaker on/offIntegrationEvery attached gateway screen, including inactive gateway screens
Recommended limitsIntegration-wide limits, keeping phone/IP limits and breaker sensitivityGateway screen recommendations for every attached gateway screen
PoW starting difficultyIntegration: adaptive or 2–7; automatic scaling on or offAttached gateway screens: 3–6
PoW on/off, trigger, maximum difficulty and breaker fileUnavailableEvery attached gateway screen
Circuit-breaker sensitivity, Turnstile and integration passkey brandingIntegrationUnavailable
Channel Choice modeUnavailableGateway only, with an attached gateway screen

The CLI uses the resulting API version if the command also changes it. Legacy and gateway changes that need a gateway screen are refused when none is attached. To change just one gateway screen, use integrations screens update.

When a command affects several resources, it reads their current revisions, saves the integration first, then saves gateway screens in creation-time/id order. This is a sequence of guarded saves, not one atomic save; see recovering an update.

Choose the setting

These groups cover the update flags. The linked reference carries their complete values, tips, defaults and restrictions.

GroupFlagsMain rule
Identity, Return URL and Server URL--name, --description, --redirect-url, --webhook-urlOmitted fields stay unchanged; none clears the Return URL or the Server URL. --name and --description need no --yes. --redirect-url and --webhook-url need --yes, because they change where Akedly sends your users and your verification results: akedly integrations update <id> --webhook-url https://example.com/webhooks/akedly --yes.
Lifecycle--status, --environment, --api-versionUse active/inactive, live/test; only a headless-to-gateway (v1.2 to v2) version change is supported, and a Live gateway needs both the Return URL (--redirect-url) and the Server URL (--webhook-url) supplied or already saved (a Test one needs neither).
Delivery--verification-methods, --method-order, --smart-routing, --byo-sms, --otp-language, --otp-templateMethods are channel words; a list replaces the complete list. Use --otp-template default to restore the built-in template.
Optional OTP webhooks--webhook-channels-resolved, --webhook-channels-updated, --webhook-delivery-receiptsEach takes on or off and requires --yes on update. Choices stay on the OTP integration for every API version; omitted update flags preserve saved choices.
Channel Choice--channel-choice, --channel-choice-mode, --channel-choice-enforcementAccount eligibility and billing rules still apply. The mode needs a gateway screen attached to Gateway.
Cluster Gate--cluster-gate, --cluster-gate-position, --cluster-gate-escalation, --cluster-gate-home-countriesAvailability is checked by the server. Home countries guide attack detection; they do not restrict destinations.
Destination countries--destination-countries-mode, --destination-countriesonly-selected and all-except-selected use the complete country list you supply. all alone clears it.
Rate limits--rate-limits-file, --recommended-limits, --periodFile shape depends on where the limits live. Explicit limits and recommendations cannot be combined.
Circuit breaker--circuit-breaker, --circuit-breaker-sensitivity, --circuit-breaker-fileSensitivity is headless-only; the file is screen-only.
Proof-of-work--pow, --pow-trigger-percent, --pow-starting-difficulty, --pow-maximum-difficulty, --pow-auto-scalingHeadless exposes starting difficulty and --pow-auto-scaling on|off (off holds one fixed level, even under attack). Gateway screens require start no higher than maximum.
Passkeys and bans--passkeys, --zero-verify-bansThese change verification behavior and require --yes.
Passkey branding--passkey-company-name, --passkey-logo-url, --passkey-primary-color, --passkey-secondary-color, --passkey-themeheadless-only; use HTTPS logos, #RRGGBB colors and light/dark/system. none clears a name, logo or color override.
Turnstile--turnstile, --turnstile-platform, --turnstile-site-key, --turnstile-secret-key-file, --turnstile-test-token, --turnstile-allowed-domainsheadless-only. A new custom Web integration needs a private secret file and a fresh setup token.

Return URL, Server URL, behavior, security, version, branding and template changes require --yes; this includes turning protection off, loosening a limit, or supplying the current value. --period selects a recommendation window and does not itself change a setting. Creation uses the smaller integrations create flag set; configure the remaining settings after creation.

Choose optional OTP webhooks

CLI 0.1.3 or newer can select the three optional OTP notifications independently:

bash
akedly integrations update <id> --webhook-channels-resolved on --webhook-channels-updated on --webhook-delivery-receipts off --dry-run
akedly integrations update <id> --webhook-channels-resolved on --webhook-channels-updated on --webhook-delivery-receipts off --yes

The flags select otp.channels.resolved, otp.channels.updated and otp.message.status, respectively. Verification results remain enabled. Turning a choice off stops new events; already queued retries can still arrive.

integrations create does not take these flags: a new OTP integration starts with each choice on, and you change them with integrations update. On update, an omitted flag preserves the saved choice, including an unset choice that follows its API-version default. These flags accept only on or off; there is no reset control. One-way messaging (Utilities) integrations reject them.

Events need a configured --webhook-url and an eligible live request. Test transactions produce no optional OTP events. Read the version and channel restrictions for channel events and delivery receipts. These choices do not change the channels used to send an OTP.

Lists replace; files merge

  • --verification-methods whatsapp,sms,email replaces every saved method. Each word appears once; email goes last. Use --method-order custom to use your listed phone-channel order. Automatic order starts with WhatsApp by default and uses eligible listed fallbacks; Channel Choice and Smart Routing can alter the first send.
  • --cluster-gate-home-countries EG,SA replaces all declarations; omit it to preserve them or use none alone to clear them. Learned countries remain separate.
  • --destination-countries EG,SA replaces the complete restriction list. Send the intended mode too; a changed list under all is refused.
  • A rate-limit JSON file changes only its named limits. Omitted sibling values remain saved. Files must be regular JSON object files, at most 64 KiB.

V1.2 rate-limits.json

{
  "perPipeline": { "perMinute": 30, "perHour": 150, "perDay": 3000 }
}

Headless files accept perPhoneNumber, perIpAddress and perPipeline, each with perMinute, perHour and perDay. Use whole numbers above zero. For legacy and gateway integrations, use the gateway screen file shape, even when running integrations update.

Recovering an update

PIPELINE_CHANGED or WIDGET_CHANGED means another save won the race for that resource. Read the current settings and rerun the command so it plans from the new revision.

PARTIAL_UPDATE means some resources may already be saved. Inspect details.applied, details.notApplied and the underlying error, read the affected resources, then rerun the same update to finish the remaining work. An unconfirmed destination can have saved before the connection failed. Do not assume the whole command rolled back.

Revision-protected writes do not retry an uncertain network/server outcome automatically. The explicit CLI_RATE_LIMITED refusal can still be retried because it saved nothing. See settings errors for each refusal and its exit code.

Next: setup recipes, gateway screen settings, or the complete integration reference.