Skip to content
Akedly
Command reference

Pipelines, bans and webhook verification

Akedly CLI command reference: Pipelines, bans and webhook verification.

Build with AI agents

pipelines list

Compare the OTP and utility pipelines available to your account before choosing a pipeline for a flow.

When to use

  • Use this when setting up an integration or checking which API versions and statuses are already available.

How it works

  1. Reads the account-owned pipeline collection; it does not change pipeline settings.

Prerequisites

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

Expected outcome

A list of your pipelines with their server-returned configuration.

Next steps

  • Use the intended pipeline ID with the matching OTP command; V1, V1.2, and V2 have different integration flows.

Usage

sh
akedly pipelines list

Inspect this command offline before preparing an operation:

sh
akedly describe "pipelines list" --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: pipelines:read.

Server request: GET /pipelines/user/:userID.

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 pipelines for your account.

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

Compare the OTP and utility pipelines available to your account before choosing a pipeline for a flow.

sh
akedly pipelines list

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": [
    {
      "_id": "0123456789abcdef01234567",
      "name": "Example OTP",
      "auths24h": 0,
      "successRate7d": 100,
      "lastActivityAt": null,
      "lastSuccessAt": null,
      "hasSucceededEver": false,
      "version": "V1.2"
    }
  ]
}

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 pipelines 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.

pipelines get

Inspect one pipeline’s current API version, callbacks, verification methods, billing and security settings before changing or integrating it.

When to use

  • Use before updating settings or diagnosing a pipeline-specific rejection.

How it works

  1. Reads the pipeline by its Mongo ID and returns the server resource.

Prerequisites

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

Expected outcome

The current pipeline resource.

Next steps

  • Use the current settings as the basis for an update; the CLI reads revisions automatically when settings require conflict protection.

Usage

sh
akedly pipelines get <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "pipelines get" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Required positional argument.

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: pipelines:read.

Server request: GET /pipelines/id/: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 pipeline, including its callback URLs.

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

Inspect one pipeline’s current API version, callbacks, verification methods, billing and security settings before changing or integrating it.

sh
akedly pipelines get 0123456789abcdef01234567

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "_id": "0123456789abcdef01234567",
    "name": "Example OTP",
    "active": false,
    "type": "Test",
    "securityConfig": {
      "apiVersion": "v1.2"
    },
    "hasAttachedWidget": false,
    "clusterGateHomeCountries": [],
    "channelChoice": {
      "enabled": false
    },
    "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 pipelines get <id>
sh
akedly pipelines get <id> --fields data.frontendCallbackURL,data.backendCallbackURL

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.

pipelines create

Create an OTP or utility verification pipeline so an application can use Akedly’s corresponding verification flow.

When to use

  • Use when an account needs a new integration endpoint; choose V1, V1.2 or V2 deliberately for OTP, while utility pipelines use their supported utility contract.

How it works

  1. Builds the create request and defaults OTP pipelines to V1.2 when --api-version is omitted; utility pipelines use utility settings. The backend creates the pipeline inactive, and secret delivery writes to a private file only when --secret-file is given. Without a file, webhookSigningSecret remains in the JSON response.

Prerequisites

  • A CLI login with permission for this account and resource.
  • For secret-safe machine output, choose a new private --secret-file path; omitting it places webhookSigningSecret in the JSON response.

Expected outcome

A pipeline resource with active:false by default and a generated webhook signing secret. With --secret-file, JSON gets secretFile and omits the secret; without it, webhookSigningSecret is in JSON.

Next steps

  • Review the pipeline API version and callbacks, configure verification methods as needed, and activate deliberately with pipelines update <id> --status active --yes before sending.

Usage

sh
akedly pipelines create

Inspect this command offline before preparing an operation:

sh
akedly describe "pipelines 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.
--api-versionenumv1 | v1.2 | v2noCommand-specific option; see the full command details below. Manifest body field: securityConfig.apiVersion. Tip: Use V2 if you will embed Akedly's hosted widget, and V1.2 if you will build the verification screens yourself or cannot embed an iframe or open a system browser. V1.0 is legacy and sunsets on December 30, 2026.
--redirect-urltext—noCommand-specific option; see the full command details below. Manifest body field: frontendCallbackURL. Tip: For a web page, use an https:// redirect URL; http:// is sent unencrypted, so keep it for a local test server. An app deep link such as yourapp://callback keeps its own scheme, which your app must handle.
--webhook-urltext—noCommand-specific option; see the full command details below. Manifest body field: backendCallbackURL. Tip: Use an https:// webhook URL; http:// is sent unencrypted, so keep it for a local test server. Test the endpoint before it receives production traffic.
--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.
--productenumotp | utilitynoCommand-specific option; see the full command details below. Manifest body field: product.
--byo-smsenuminherit | on | offnoCommand-specific option; see the full command details below. Manifest body field: byoSms.
--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: pipelines:create.

Server request: POST /pipelines.

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

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

Full command details

Create an OTP or utility pipeline with --product otp|utility (default otp). OTP API version defaults to v1.2; V2 requires both callback URLs. Utility creation omits OTP defaults. --api-version is only for OTP pipelines; omit it with --product utility. --byo-sms inherit|on|off uses the account setting, enables BYO-SMS or disables it for this pipeline; enabling it does not prove routing eligibility. New pipelines start inactive; run akedly pipelines update <id> --status active --yes before sending. Save its webhook secret with --secret-file. For --product utility, --webhook-url receives signed utility event webhooks (delivery status, inbound messages, button actions), using this pipeline's webhook secret; --redirect-url is not used for utility messages. Utility creation enables WhatsApp for an admin account or an active WABA; otherwise it enables SMS when BYO-SMS is usable, or leaves both off. Adjust with akedly utilities pipelines channels set <id> --file <path>.

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 pipelines create workflow

Create an OTP or utility verification pipeline so an application can use Akedly’s corresponding verification flow.

sh
akedly pipelines create --name 'Example OTP' --secret-file ./private/webhook-secret.txt

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "_id": "0123456789abcdef01234567",
    "name": "Example OTP",
    "securityConfig": {
      "apiVersion": "v1.2"
    },
    "secretFile": "./private/webhook-secret.txt",
    "active": false,
    "type": "Test"
  },
  "message": "Pipeline created successfully"
}

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

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

Additional command forms

sh
akedly pipelines create --name Example --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 returned resource uses active:boolean and type (there is no status field). Newly created pipelines default to active:false.

Without --secret-file, webhookSigningSecret remains in JSON; with the file sink, the secret field is removed and secretFile is added.

Common error guidance.

pipelines update

Change a pipeline’s customer-facing verification, routing, country, branding, or security behavior while preserving concurrent edits.

When to use

  • Use to adjust an existing pipeline after checking its API version and attached widgets.

How it works

  1. For revision-protected settings, reads the current pipeline revision and includes it in the write to reject stale edits. On V1 and V2, widget-only controls fan out to every active and inactive attached widget after a paginated attachment read; on V1.2 they are refused. Dry-run performs planning reads and returns either a raw single-request preview or an ordered multi-resource steps plan.

Prerequisites

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

Expected outcome

Updated pipeline resource, or a dry-run plan; an ordered fan-out can fail with PARTIAL_UPDATE after some resources were saved.

Next steps

  • Inspect every resource named by PARTIAL_UPDATE before retrying; use pipelines get and widgets list-filtered including inactive widgets.

Usage

sh
akedly pipelines update <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "pipelines update" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Required positional argument.

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.
--statusenumactive | inactiveCommand-specific option; see the full command details below. Manifest body field: active.
--environmentenumlive | testCommand-specific option; see the full command details below. Manifest body field: type.
--otp-languageenumen | arCommand-specific option; see the full command details below. Manifest body field: locale.
--redirect-urltext—Command-specific option; see the full command details below. Manifest body field: frontendCallbackURL. Tip: For a web page, use an https:// redirect URL; http:// is sent unencrypted, so keep it for a local test server. An app deep link such as yourapp://callback keeps its own scheme, which your app must handle.
--webhook-urltext—Command-specific option; see the full command details below. Manifest body field: backendCallbackURL. Tip: Use an https:// webhook URL; http:// is sent unencrypted, so keep it for a local test server. Test the endpoint before it receives production traffic.
--smart-routingenumon | offCommand-specific option; see the full command details below. Manifest body field: smartRouting.
--passkeysenumon | offCommand-specific option; see the full command details below. Manifest body field: passkeyEnabled. 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.
--zero-verify-bansenumon | offCommand-specific option; see the full command details below. Manifest body field: zeroVerifyBansEnabled. Tip: Keep zero-verify bans on, as they are by default; when they are off, account-level zero-verify bans no longer stop requests to this pipeline.
--dry-runboolean switch—Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
--byo-smsenuminherit | on | offCommand-specific option; see the full command details below. Manifest body field: byoSms.
--yesboolean switch—Confirm this action where consent is required.
--cluster-gateenumon | offCommand-specific option; see the full command details below. Manifest body field: securityConfig.clusterGate.enabled, clusterGateIntent.
--cluster-gate-positionenumcautious | balanced | assertiveCommand-specific option; see the full command details below. Manifest body field: securityConfig.clusterGate.position, clusterGateIntent. 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.
--cluster-gate-home-countrieslist—Command-specific option; see the full command details below. Manifest body field: securityConfig.clusterGate.homeCountries, clusterGateIntent. The literal none clears this value. 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.
--verification-methodslist—Command-specific option; see the full command details below. Manifest body field: verificationMethods. Tip: Akedly recommends WhatsApp first, for the most reliable delivery and a lower price than SMS. With automatic order, WhatsApp is already the default first channel, even when your list leaves it out, and your list decides the fallbacks; to keep WhatsApp out or to send in your own order, pass --method-order custom and list the methods in that order, because a list alone keeps the pipeline's current order setting.
--method-orderenumcustom | automaticCommand-specific option; see the full command details below. Manifest body field: useMethodOrder. Tip: Akedly recommends WhatsApp first, for the most reliable delivery and a lower price than SMS. With automatic order, WhatsApp is already the default first channel, even when your list leaves it out, and your list decides the fallbacks; to keep WhatsApp out or to send in your own order, pass --method-order custom and list the methods in that order, because a list alone keeps the pipeline's current order setting.
--channel-choiceenumon | offCommand-specific option; see the full command details below. Manifest body field: channelChoiceEnabled.
--channel-choice-modeenumask-first | send-firstCommand-specific option; see the full command details below. Manifest body field: channelChoiceMode.
--channel-choice-enforcementenumfallback | hard-pinCommand-specific option; see the full command details below. Manifest body field: channelChoiceEnforcement.
--rate-limits-filetext—Command-specific option; see the full command details below. Manifest body field: rateLimiting.perEndUserIP.perDay, rateLimiting.perEndUserIP.perHour, rateLimiting.perEndUserIP.perMinute, rateLimiting.perPhoneNumber.perDay, rateLimiting.perPhoneNumber.perHour, rateLimiting.perPhoneNumber.perMinute, rateLimiting.perPipeline.perDay, rateLimiting.perPipeline.perHour, rateLimiting.perPipeline.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. Tip: Keep the circuit breaker on; Akedly recommends it to protect verification from flood attacks and traffic spikes.
--circuit-breaker-sensitivityenumstrict | balanced | lenientCommand-specific option; see the full command details below. Manifest body field: circuitBreakerMultiplier.
--destination-countries-modeenumall | only-selected | all-except-selectedCommand-specific option; see the full command details below. Manifest body field: countryPolicy.mode, expectedUpdatedAt.
--destination-countrieslist—Command-specific option; see the full command details below. Manifest body field: countryPolicy.countries, expectedUpdatedAt.
--recommended-limitsboolean switch—Command-specific option; see the full command details below. Manifest body field: rateLimiting.perPipeline.perMinute, rateLimiting.perPipeline.perHour, rateLimiting.perPipeline.perDay, 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.
--otp-templatetext—Command-specific option; see the full command details below. Manifest body field: defaultOtpTemplateId.
--api-versionenumv1 | v1.2 | v2Command-specific option; see the full command details below. Manifest body field: securityConfig.apiVersion, expectedUpdatedAt. Tip: Use V2 if you will embed Akedly's hosted widget, and V1.2 if you will build the verification screens yourself or cannot embed an iframe or open a system browser. V1.0 is legacy and sunsets on December 30, 2026.
--pow-starting-difficultytext—Command-specific option; see the full command details below. Manifest body field: securityConfig.pow.difficulty, expectedUpdatedAt.
--passkey-company-nametext—Command-specific option; see the full command details below. Manifest body field: passkeyBranding.customCompanyName, expectedUpdatedAt.
--passkey-logo-urltext—Command-specific option; see the full command details below. Manifest body field: passkeyBranding.customLogo, expectedUpdatedAt.
--passkey-primary-colortext—Command-specific option; see the full command details below. Manifest body field: passkeyBranding.customPrimaryColor, expectedUpdatedAt.
--passkey-secondary-colortext—Command-specific option; see the full command details below. Manifest body field: passkeyBranding.customSecondaryColor, expectedUpdatedAt.
--passkey-themeenumlight | dark | systemCommand-specific option; see the full command details below. Manifest body field: passkeyBranding.theme, expectedUpdatedAt.
--turnstileenumon | offCommand-specific option; see the full command details below. Manifest body field: securityConfig.turnstile.enabled, expectedUpdatedAt.
--turnstile-allowed-domainslist—Command-specific option; see the full command details below. Manifest body field: securityConfig.turnstile.domains, expectedUpdatedAt.
--turnstile-platformenumweb | mobileCommand-specific option; see the full command details below. Manifest body field: securityConfig.turnstile.platform, expectedUpdatedAt.
--turnstile-site-keytext—Command-specific option; see the full command details below. Manifest body field: securityConfig.turnstile.siteKey, expectedUpdatedAt.
--turnstile-test-tokentext—Command-specific option; see the full command details below. Manifest body field: securityConfig.turnstile.testToken, expectedUpdatedAt.
--turnstile-secret-key-filetext—Command-specific option; see the full command details below. Manifest body field: securityConfig.turnstile.secretKey, expectedUpdatedAt.
--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, expectedUpdatedAt. 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, expectedUpdatedAt. 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, expectedUpdatedAt. 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.
--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: pipelines:update.

Server request: PUT /pipelines/id/:id.

Shared server-guard guidance.

Consent

--yes when --status or --environment or --otp-language or --smart-routing or --passkeys or --zero-verify-bans or --byo-sms or --cluster-gate or --cluster-gate-position or --cluster-gate-escalation or --cluster-gate-home-countries or --verification-methods or --method-order or --channel-choice or --channel-choice-mode or --channel-choice-enforcement or --rate-limits-file or --circuit-breaker or --circuit-breaker-sensitivity or --destination-countries-mode or --destination-countries or --recommended-limits or --otp-template or --api-version or --pow-starting-difficulty or --passkey-company-name or --passkey-logo-url or --passkey-primary-color or --passkey-secondary-color or --passkey-theme or --turnstile or --turnstile-allowed-domains or --turnstile-platform or --turnstile-site-key or --turnstile-test-token or --turnstile-secret-key-file or --circuit-breaker-file or --pow or --pow-trigger-percent or --pow-maximum-difficulty or --redirect-url or --webhook-url 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

Retry exception: a pipelines update that changes rate limits or destination countries is not retried automatically after a timeout or server error, because it may already be saved; check with akedly pipelines get <id>, and running the same command again is safe. Update only the flags you supply: --name, --description, --status active|inactive, --environment live|test, --otp-language en|ar, --redirect-url, --webhook-url, --smart-routing on|off, --passkeys on|off, --zero-verify-bans on|off, --byo-sms inherit|on|off, --cluster-gate on|off, --cluster-gate-position cautious|balanced|assertive, --cluster-gate-escalation on|off, --cluster-gate-home-countries EG,SA (or none), --verification-methods, --method-order custom|automatic, --channel-choice on|off, --channel-choice-enforcement fallback|hard-pin and --channel-choice-mode ask-first|send-first. Results show status as the active field (true or false) and environment as the type field (Live or Test). Use none to clear a callback URL. Cluster Gate is Akedly's AI protection that refuses code requests that look like part of an attack: --cluster-gate turns it on or off for this pipeline, --cluster-gate-position chooses how much it refuses during an attack, and --cluster-gate-escalation on|off controls a stricter window that lasts 15 minutes after Cluster Gate last detects an attack; while that window is open, Cluster Gate can refuse every request to this pipeline, or only requests to unusual destinations when the attack targets numbers outside your usual countries. --cluster-gate-home-countries EG,SA replaces the complete declared home-country list for this pipeline, so include every country you want to keep. Omit the flag to preserve the saved declarations. Use the exact lowercase value none on its own to clear them; do not combine none with country codes. Use comma-separated two-letter country codes. Codes are normalized to uppercase, duplicates are removed, and the server saves a sorted list; an unknown code is refused rather than dropped. These declarations guide Cluster Gate for expected phone destinations and end-user IP countries. They do not restrict sending or allow or block IP addresses; destination-country restrictions and other protections still apply. Learned countries are managed separately by the engine; replacing or clearing declarations does not edit or erase learned countries or their history. This flag needs --yes whenever supplied, including none or the current list. A home-country-only --dry-run previews the declaration without --yes or requests; the server checks country membership and Cluster Gate availability on the real update. Read saved declarations with akedly pipelines get <id> in data.securityConfig.clusterGate.homeCountries; data.clusterGateHomeCountries contains separate learned-country metadata. This flag also works on widgets create and update, changing the linked pipeline. The CLI sends only the Cluster Gate settings you supply, plus the intent marker the server requires, so the others keep their values. If Cluster Gate cannot be changed on this pipeline, the command fails with CLUSTER_GATE_NOT_AVAILABLE, details.reason says why, and nothing in that request is saved; --dry-run cannot check this. --verification-methods takes a comma list of whatsapp, telegram, sms and email, each at most once; it replaces the whole list, so include every method you want to keep, it cannot be empty, and email always goes last. The order you type is used whenever the pipeline uses custom order, because you pass --method-order custom or the pipeline already has it. The CLI reads Akedly's public list of verification methods, which needs no login, to find each one; even a dry run makes this one read, though it changes nothing. A word with no available method is refused as VERIFICATION_METHOD_UNAVAILABLE before anything is saved. On legacy pricing, SMS cannot be the only phone method; add whatsapp or telegram. --method-order custom sends through your methods in the listed order. With automatic order, WhatsApp is the default first channel even when your list leaves it out, sent from Akedly's shared number unless you connected your own; two things can start a send elsewhere: a channel the user picked through Channel Choice, and Smart Routing, which sends someone's next code on the next channel when an earlier WhatsApp code to that number has not been confirmed as delivered. Your list then decides the fallbacks, Telegram and then SMS, only those you listed, whatever order you typed them in. To keep WhatsApp out or to send in the order you typed, use --method-order custom; email is unaffected. --method-order is sent only when you pass it, so a list alone does not change the order setting and the pipeline keeps the one it has, except that a list with exactly one phone method (email not counted) is always saved with custom order, even with --method-order automatic; pass --method-order whenever the order matters. akedly pipelines get <id> shows the current methods as ids in data.verificationMethods, the order setting in data.useMethodOrder (true means custom), data.hasAttachedWidget and the Channel Choice summary in data.channelChoice, including blockers, eligibleChannels and fallbackOrder. --channel-choice on|off lets users choose where to get their code. If their channel fails later, --channel-choice-enforcement fallback tries another channel and hard-pin uses only their choice; with custom order, fallback tries the next listed channel, and with automatic order it follows WhatsApp, then Telegram, then SMS among the methods in your list, so an unlisted WhatsApp is never a Channel Choice fallback. --channel-choice-mode sets the widget experience: ask-first lets users choose before a code is sent, and send-first sends a code, then offers a choice on resend; it applies only to V2 pipelines with a widget attached, so changing it on any other pipeline fails with SETTING_NOT_FOR_THIS_PIPELINE, while setting the mode the pipeline already has (ask-first when none is stored) skips that check, though another Channel Choice flag that changes in the same command can still be refused. Channel Choice needs it enabled on your account, granular pricing and pay-per-message billing, and it is also blocked on a utility pipeline, for an excluded account or while Akedly has it switched off for everyone. A command that changes a Channel Choice value is then refused with CHANNEL_CHOICE_NOT_AVAILABLE and details.blockers names the reason, while a value the pipeline already has, such as off when it is already off or was never set, is accepted. --rate-limits-file <file> reads a JSON object of the limits to change, for example {"perPipeline":{"perMinute":30}}: perPhoneNumber, perIpAddress and perPipeline each take perMinute, perHour and perDay as whole numbers above zero, only the limits you name change, and every other limit is kept. --circuit-breaker on|off turns the circuit breaker on or off, and --circuit-breaker-sensitivity strict|balanced|lenient sets how much traffic above your rate limits it tolerates before it suspends the pipeline; strict tolerates the least. On V1.2 these change the pipeline. On V1 or V2 the CLI applies rate limits, the circuit breaker and recommended limits to every attached widget, including inactive widgets; use the widget rate-limit file shape, with widgetAttempts and otpRequests containing perPhoneNumber, perDevice and perWidget. --circuit-breaker-file, --pow, --pow-trigger-percent and --pow-maximum-difficulty are widget settings and are refused on V1.2. --pow-starting-difficulty accepts adaptive or 2..7 on V1.2, and 3..6 on V1/V2 widgets. Sensitivity, Turnstile and pipeline passkey branding stay V1.2-only. If a V1/V2 pipeline has no widgets the command refuses with SETTING_NOT_FOR_THIS_PIPELINE and reason no-widget. The CLI checks the resulting API version when --api-version is supplied, reads both active and inactive listings through every page, checks permissions and reads every resource revision before writing. The pipeline saves first, then widgets in creation-time/id order. If a later write fails, PARTIAL_UPDATE lists confirmed resources and unconfirmed destinations; inspect them and run the same update again. --dry-run shows every planned guarded write without saving. --recommended-limits applies Akedly's recommended pipeline-wide limits from your real traffic over --period last-month|last-quarter|last-6-months (default last-month), with a 10% buffer for growth; it never changes the per-phone-number or per-IP-address limits or the circuit breaker sensitivity, cannot be combined with --rate-limits-file, and is refused with NOT_ENOUGH_TRAFFIC when the analysis has low confidence or fewer than 100 requests, so a quiet pipeline keeps its limits. --destination-countries-mode all|only-selected|all-except-selected with --destination-countries EG,SA chooses which countries can receive codes, on every pipeline version. --destination-countries replaces the saved list, so include every country you want to keep; --destination-countries-mode only-selected or all-except-selected on its own keeps the saved list, so switching between them inverts it; after the list was cleared with mode all it is empty, so switching to only-selected also needs --destination-countries. To clear the list, pass --destination-countries-mode all on its own; a list sent with mode all that matches the saved list is simply cleared, and a changed list with mode all is refused with DESTINATION_COUNTRIES_MODE_REQUIRED instead of being dropped. For rate-limit and destination-country changes the CLI first reads the pipeline and sends the revision it read, so if someone changes the pipeline in between, the command fails with PIPELINE_CHANGED instead of undoing their change; run it again to read the pipeline again. --dry-run makes the same reads and sends no change; the pipeline read needs permission to read pipelines, and the recommendation read for --recommended-limits needs permission to update them. Cooldowns cannot be set because they have no effect. For V1.2 pipelines, --pow-starting-difficulty adaptive|2..7 chooses the starting difficulty; Akedly can clamp it to the current policy ceiling. It does not change whether PoW is enabled. --passkey-company-name, --passkey-logo-url (HTTPS), --passkey-primary-color and --passkey-secondary-color (#RRGGBB), and --passkey-theme light|dark|system override the passkey look; none clears a name, logo or colour override. --api-version changes a V1.2 pipeline to V2 only; supply both callbacks before upgrading. --turnstile on|off and --turnstile-platform web|mobile manage protection. A new Web integration needs --turnstile-site-key, --turnstile-secret-key-file <path|-> and --turnstile-test-token; - reads a piped secret from stdin, never pass the secret as an argument. Obtain a fresh setup token on the docs Turnstile token page; it is single-use, so obtain another after a refused or uncertain save. Mobile uses the managed shared integration. --turnstile-allowed-domains edits an enabled existing legacy Web integration only. Security, version and branding flags require --yes, read the current revision first, never repeat an uncertain write automatically, and mask credentials in --dry-run. Changing --otp-language provisions the matching WhatsApp template on your connected WABA. --byo-sms inherit|on|off uses the account setting, enables BYO-SMS or disables it for this pipeline; enabling it does not prove routing eligibility. Product is chosen at creation and cannot be changed here. Changing status, environment, OTP language, smart routing, passkeys, zero-verify bans, BYO-SMS, any Cluster Gate setting, the verification methods, the method order, any Channel Choice setting, the rate limits, the circuit breaker, the destination countries, the recommended limits or a callback URL (--redirect-url or --webhook-url, including none) can stop, reroute or loosen live verification, so it needs --yes, also when it turns a protection off or loosens a limit; names, descriptions and --period do not, and --dry-run previews any change without --yes. Use --otp-template <id> to attach an OTP template approved for the pipeline language, or --otp-template default to restore the built-in template. A custom template needs an active WhatsApp method and your own connected WhatsApp Business Account. Both attachment and restoring the default require --yes. Find template ids and per-language approval status with akedly whatsapp otp-templates list.

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 pipelines update workflow

Change a pipeline’s customer-facing verification, routing, country, branding, or security behavior while preserving concurrent edits.

sh
akedly pipelines update 0123456789abcdef01234567 --name 'Example OTP' --yes

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "_id": "0123456789abcdef01234567",
    "name": "Example OTP",
    "active": false,
    "type": "Test",
    "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 V1.2 pipeline limits and Turnstile setup

Set a per-pipeline request ceiling and enable the Turnstile web check for a V1.2 pipeline during initial protection setup.

sh
akedly pipelines update 0123456789abcdef01234567 --rate-limits-file ./fixtures/pipeline-limits.json --turnstile on --turnstile-platform web --turnstile-site-key 0x4AAAAAAAsyntheticSiteKey --turnstile-secret-key-file ./fixtures/turnstile-secret.txt --turnstile-test-token synthetic-test-token --yes

Input file: ./fixtures/pipeline-limits.json (json).

json
{
  "perPipeline": {
    "perMinute": 30
  }
}

Input file: ./fixtures/turnstile-secret.txt (text).

text
[REDACTED — use your privately saved secret file]

Illustrative response (sensitive values omitted):

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

Prerequisites: an authorized CLI login and an existing V1.2 pipeline; confirm its API version and current behavior with pipelines get before applying settings. The test token and all values are synthetic documentation values and are not usable credentials.

This is a confirmed write. The CLI reads the pipeline settings and revision before saving; dry-run still performs planning reads and previews the request. Turnstile setup-token validation can refuse the write, so use a fresh valid setup token when running for real.

The perPipeline limit controls requests across this pipeline. After success, inspect pipelines get for saved limits and Turnstile state, then finish the provider-side hostname setup if needed.

Synthetic V2 attached-widget rate and circuit-breaker limits

Adjust request ceilings and flood protection on every widget attached to an existing V2 pipeline.

sh
akedly pipelines update 89abcdef0123456789abcdef --rate-limits-file ./fixtures/widget-rate-limits.json --circuit-breaker-file ./fixtures/widget-circuit-breaker.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
  }
}

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "_id": "89abcdef0123456789abcdef",
    "name": "Example OTP",
    "active": false,
    "type": "Test",
    "updatedAt": "2030-03-12T09:00:00.000Z"
  }
}

Prerequisites: an authorized CLI login, an existing V2 pipeline, and its attached widgets. Check the API version and attachment list first; widget settings are refused for V1.2 pipelines.

The files use widget rate-limit and circuit-breaker input shapes. The CLI reads and revision-checks resources, then applies the supplied settings across attached widgets. If a later widget write fails, the command can return PARTIAL_UPDATE; inspect every applied and notApplied resource before retrying.

The rate ceiling is for OTP requests per individual widget. Circuit-breaker durations are supplied in seconds. After success, inspect the pipeline and attached widgets to confirm each resource's state.

Additional command forms

sh
akedly pipelines update <id> --status active --yes
sh
akedly pipelines update <id> --status inactive --yes
sh
akedly pipelines update <id> --redirect-url https://example.invalid/done --webhook-url https://example.invalid/webhook --yes
sh
akedly pipelines update <id> --webhook-url none --yes
sh
akedly pipelines update <id> --cluster-gate on --cluster-gate-position balanced --yes
sh
akedly pipelines update <id> --verification-methods whatsapp,sms,email --method-order custom --yes
sh
akedly pipelines update <id> --circuit-breaker on --circuit-breaker-sensitivity balanced --yes
sh
akedly pipelines update <id> --cluster-gate-home-countries EG,SA --yes
sh
akedly pipelines update <id> --cluster-gate-home-countries none --yes
sh
akedly pipelines update <id> --cluster-gate-home-countries EG,SA --dry-run
sh
akedly pipelines update <id> --otp-template <templateId> --yes
sh
akedly pipelines update <id> --otp-template default --yes
sh
akedly pipelines update <id> --pow-starting-difficulty adaptive --yes
sh
akedly pipelines update <id> --passkey-theme dark --yes
sh
akedly pipelines update <id> --turnstile on --turnstile-platform web --turnstile-site-key <site-key> --turnstile-secret-key-file <private-file> --turnstile-test-token <fresh-token> --yes
sh
akedly pipelines update <id> --circuit-breaker on --pow-starting-difficulty 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
TEMPLATE_NOT_APPROVEDRun akedly whatsapp otp-templates list and check approval for the pipeline language before attaching the template.
TEMPLATE_PIPELINE_REQUIRES_WHATSAPPEnable WhatsApp with --verification-methods before attaching a custom OTP template, or use --otp-template default.
API_VERSION_CHANGE_NOT_ALLOWEDOnly V1.2 to V2 is supported. Keep the current API version or create a separate pipeline for another version. V2 requires both --redirect-url and --webhook-url.
PIPELINE_POW_INVALIDUse --pow-starting-difficulty adaptive or a whole number from 2 to 7. This sets the starting difficulty; Akedly controls whether pipeline PoW is enabled.
PASSKEY_BRANDING_INVALIDUse an HTTPS logo, a company name of at most 100 characters, six-digit #RRGGBB colours and light, dark or system for the theme. Use none to restore a company default.
TURNSTILE_DOMAINS_NOT_EDITABLE--turnstile-allowed-domains is only for an enabled existing legacy Web integration. Manage customer-owned integration hostnames in Cloudflare.

Common error guidance.

pipelines delete

Remove a pipeline that should no longer accept verification traffic.

When to use

  • Use only after confirming no application or widget depends on it.

How it works

  1. Requests deletion after explicit confirmation; dry-run reports the planned operation without deleting.

Prerequisites

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

Expected outcome

The pipeline is deleted; the response contains the deleted pipeline under data and a confirmation message at the root.

Next steps

  • Remove references from applications and any widgets before running this irreversible action.

Usage

sh
akedly pipelines delete <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "pipelines delete" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Required positional argument.

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: pipelines:delete.

Server request: DELETE /pipelines/id/: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

Delete a pipeline. Read it first to check hasAttachedWidget; deletion has no attachment check.

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 pipelines delete workflow

Remove a pipeline that should no longer accept verification traffic.

sh
akedly pipelines delete 0123456789abcdef01234567 --yes

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "_id": "0123456789abcdef01234567",
    "name": "Example OTP",
    "active": false,
    "type": "Test",
    "securityConfig": {
      "apiVersion": "v1.2"
    }
  },
  "message": "Pipeline deleted successfully"
}

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 pipelines 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.

pipelines billing-status

Check the billing eligibility and status information used when deciding whether a pipeline can process paid verification traffic.

When to use

  • Use when a pipeline send is blocked by billing or during account setup.

How it works

  1. Reads the account billing-status endpoint.

Prerequisites

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

Expected outcome

Server billing-status object.

Next steps

  • Resolve any account billing requirement shown by the response before sending.

Usage

sh
akedly pipelines billing-status

Inspect this command offline before preparing an operation:

sh
akedly describe "pipelines billing-status" --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: pipelines:read.

Server request: GET /pipelines/billing-status/:userID.

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

Read billing status for your account pipelines.

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 pipelines billing-status workflow

Check the billing eligibility and status information used when deciding whether a pipeline can process paid verification traffic.

sh
akedly pipelines billing-status

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "user": {
      "_id": "0123456789abcdef01234567",
      "billingMode": "PPM",
      "resolvedBillingMode": "PPM",
      "resolvedSource": "user"
    },
    "billingPlan": {
      "_id": "89abcdef0123456789abcdef",
      "name": "Example plan",
      "billingMode": "PPM",
      "resolvedBillingMode": "PPM",
      "resolvedSource": "plan"
    },
    "pipelines": [
      {
        "_id": "fedcba987654321001234567",
        "name": "Example OTP",
        "billingMode": null,
        "resolvedBillingMode": "PPM",
        "resolvedSource": "plan"
      }
    ]
  }
}

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 pipelines billing-status

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.

pipelines active-billing-status

Check billing readiness for currently active pipelines before a rollout.

When to use

  • Use when confirming which active pipelines have usable billing status.

How it works

  1. Reads the active-pipeline billing summary.

Prerequisites

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

Expected outcome

Server billing status summary.

Next steps

  • Review inactive or unready pipelines separately with pipelines get and billing-status.

Usage

sh
akedly pipelines active-billing-status

Inspect this command offline before preparing an operation:

sh
akedly describe "pipelines active-billing-status" --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: pipelines:read.

Server request: GET /pipelines/active-billing-status/:userID.

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

Read billing status for the first active live pipeline.

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 pipelines active-billing-status workflow

Check billing readiness for currently active pipelines before a rollout.

sh
akedly pipelines active-billing-status

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "user": {
      "_id": "0123456789abcdef01234567",
      "billingMode": "PPM",
      "resolvedBillingMode": "PPM",
      "resolvedSource": "user"
    },
    "billingPlan": {
      "_id": "89abcdef0123456789abcdef",
      "name": "Example plan",
      "billingMode": "PPM",
      "resolvedBillingMode": "PPM",
      "resolvedSource": "plan"
    },
    "pipeline": {
      "_id": "fedcba987654321001234567",
      "name": "Example OTP",
      "active": true,
      "type": "Live",
      "billingMode": null,
      "resolvedBillingMode": "PPM",
      "resolvedSource": "plan"
    }
  }
}

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 pipelines active-billing-status

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.

pipelines otp-sms-preview

Preview the actual locale-specific OTP copy and SMS segmentation before configuring an OTP pipeline.

When to use

  • Use to inspect English or Arabic OTP text without sending a message.

How it works

  1. Renders a synthetic zero-filled code using the configured locale and digit count, applies the current company name or fallback, and returns encoding, characters, segments, and truncation details. It sends no SMS.

Prerequisites

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

Expected outcome

Rendered preview fields returned by the API.

Next steps

  • Review wording and length before enabling the corresponding pipeline settings.

Usage

sh
akedly pipelines otp-sms-preview

Inspect this command offline before preparing an operation:

sh
akedly describe "pipelines otp-sms-preview" --output json

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--otp-languageenumen | arCommand-specific option; see the full command details below. Query parameter: locale.
--digitsinteger4 to 6Command-specific option; see the full command details below. Query parameter: digits.
--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: pipelines:read.

Server request: GET /pipelines/otp-sms-preview.

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

Preview OTP SMS text without sending a message.

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 pipelines otp-sms-preview workflow

Preview the localized OTP SMS copy and digit count before choosing customer-facing message settings.

sh
akedly pipelines otp-sms-preview --otp-language en --digits 6

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "locale": "en",
    "otpDigits": 6,
    "appliesTo": "cequens",
    "wouldTruncate": false,
    "segments": 1,
    "encoding": "GSM7",
    "characters": 38,
    "companyName": "Example Co",
    "sample": "000000 is your OTP. Sent by Example Co"
  },
  "message": "OTP SMS preview generated successfully"
}

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 pipelines otp-sms-preview --otp-language en --digits 4

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.

pipelines pow-policy

See the server’s current proof-of-work policy before configuring abuse protection.

When to use

  • Use when deciding whether PoW thresholds comply with server policy.

How it works

  1. Reads the policy endpoint without changing a pipeline.

Prerequisites

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

Expected outcome

Policy values returned by the server.

Next steps

  • Use the reported limits when selecting PoW settings.

Usage

sh
akedly pipelines pow-policy

Inspect this command offline before preparing an operation:

sh
akedly describe "pipelines pow-policy" --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: pipelines:read.

Server request: GET /pipelines/pow-policy.

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 the proof-of-work policy.

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 pipelines pow-policy workflow

See the server’s current proof-of-work policy before configuring abuse protection.

sh
akedly pipelines pow-policy

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "minDifficulty": 3,
    "defaultDifficulty": 4,
    "maxDifficulty": 6
  }
}

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 pipelines pow-policy

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.

pipelines rate-recommendations

Estimate safer pipeline rate limits from observed traffic before applying limits.

When to use

  • Use when tuning an owned non-system pipeline; recommendations require enough analysed traffic and confidence.

How it works

  1. Requests an analysis for the selected period or custom date range; this command only returns recommendations.

Prerequisites

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

Expected outcome

Analysis result, including readiness/confidence and suggested settings when available.

Next steps

  • Apply only after reviewing recommendations with pipelines update; low traffic returns no ready settings.

Usage

sh
akedly pipelines rate-recommendations <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "pipelines rate-recommendations" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Required positional argument.

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: pipelines:update.

Server request: POST /pipeline-rate-recommendations/:pipelineID.

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 rate recommendations. Requires Full access; dates use server-local-day semantics.

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 pipelines rate-recommendations workflow

Estimate safer pipeline rate limits from observed traffic before applying limits.

sh
akedly pipelines rate-recommendations 0123456789abcdef01234567 --period last-month

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "applyReady": {
      "enoughTraffic": true,
      "confidence": "high",
      "analysedRequests": 250,
      "settings": {
        "rateLimiting": {
          "perPipeline": {
            "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 pipelines rate-recommendations <id> --period last-month

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.

pipelines dev-mode show

Inspect whether a pipeline currently has the development test-pair mode and bypasses enabled.

When to use

  • Use before running a safe development test pair or diagnosing why a test bypass is unavailable.

How it works

  1. Reads dev-mode configuration for the pipeline.

Prerequisites

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

Expected outcome

Current dev-mode settings.

Next steps

  • Use dev-mode set to change settings; test-pair flows are synthetic and are not production verification.

Usage

sh
akedly pipelines dev-mode show <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "pipelines dev-mode show" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Required positional argument.

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: pipelines:dev_mode.

Server request: GET /pipelines/id/:id/dev-mode.

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 dev mode and its disposable Test Pair. Requires Full access.

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 pipelines dev-mode show workflow

Inspect whether a pipeline currently has the development test-pair mode and bypasses enabled.

sh
akedly pipelines dev-mode show 0123456789abcdef01234567

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "enabled": false
  }
}

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 pipelines dev-mode show <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.

pipelines dev-mode set

Enable or disable the pipeline’s development test-pair behavior and permitted Turnstile/PoW bypasses.

When to use

  • Use for controlled development testing after confirming the pipeline is the intended test pipeline.

How it works

  1. Requires confirmation for writes; dry-run previews. Bypasses only affect eligible development test-pair traffic.

Prerequisites

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

Expected outcome

Saved development-mode settings.

Next steps

  • Run a test-pair flow and turn development mode off when finished.

Usage

sh
akedly pipelines dev-mode set <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "pipelines dev-mode set" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Required positional argument.

Flags

FlagTypeEnum / rangeRequiredDescription
--ksaboolean switch—noSelect the KSA deployment.
--dev-modeenumon | offyesCommand-specific option; see the full command details below. Manifest body field: 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.
--bypass-turnstileenumon | offnoCommand-specific option; see the full command details below. Manifest body field: bypassTurnstile. Tip: On V1.2 pipelines, use Bypass Turnstile for testing from localhost instead of adding localhost in Cloudflare: when it is on, while the dev-mode window is open, it skips Turnstile for every request to the pipeline, so never turn it on for a pipeline serving production traffic.
--bypass-powenumon | offnoCommand-specific option; see the full command details below. Manifest body field: bypassPoW. Tip: On V1.2 pipelines, keep Bypass PoW off unless proof-of-work blocks your tests: when it is on, while the dev-mode window is open, it skips the check for every request to the pipeline, not only the test number. It stops working when the window ends or dev mode is turned off.
--dev-mode-digitsinteger4 to 6noCommand-specific option; see the full command details below. Manifest body field: digits.
--dry-runboolean switch—noPreview without sending the write or creating output files; planning reads may still occur. Bypass consent.
--yesboolean switch—noConfirm this action where consent is required.
--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: pipelines:dev_mode.

Server request: PUT /pipelines/id/:id/dev-mode.

Shared server-guard guidance.

Consent

--yes. --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

Set the one-hour dev-mode window for V1.2. Enabling while already on does not extend the hour; disable and re-enable for a fresh hour and a new Test Pair. When enabling, omitted bypass flags reset to off. The server returns a disposable Test Pair without sending anything. Dev mode loosens live verification on this pipeline (it bypasses rate limiting and circuit breaker), so every change here needs --yes, turning it off included; --dry-run previews without --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 pipelines dev-mode set workflow

Enable or disable the pipeline’s development test-pair behavior and permitted Turnstile/PoW bypasses.

sh
akedly pipelines dev-mode set 0123456789abcdef01234567 --dev-mode on --yes

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "_id": "0123456789abcdef01234567",
    "name": "Example OTP",
    "active": false,
    "type": "Test",
    "devMode": {
      "enabled": true,
      "bypassTurnstile": true,
      "bypassPoW": true
    },
    "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 pipelines dev-mode set <id> --dev-mode on --dev-mode-digits 4 --yes
sh
akedly pipelines dev-mode set <id> --dev-mode off --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.

pipelines webhook-secret reveal

Recover the current webhook signing secret while it remains unacknowledged; the reveal operation can be repeated until acknowledgement.

When to use

  • Use before acknowledgement to recover the current secret when needed; repeated reveal calls continue to return it until acknowledged.

How it works

  1. Reads the current secret. Reveal does not consume or acknowledge it; only the acknowledgement command closes this reveal window. With --secret-file, the CLI removes the secret field from JSON and writes it privately; without it, JSON contains the secret.

Prerequisites

  • A CLI login with permission for this account and resource.
  • For secret-safe machine output, choose a new private --secret-file path; omitting it places webhookSigningSecret in the JSON response.

Expected outcome

The current webhook signing secret. A private file sink returns secretFile without the secret; without --secret-file the secret is present in JSON.

Next steps

  • Store the file in a secret manager; do not paste it into logs.

Usage

sh
akedly pipelines webhook-secret reveal <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "pipelines webhook-secret reveal" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Required positional argument.

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--secret-filetext—Write the secret to a new mode 0600 file and omit it from output; an existing path is refused.
--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: pipelines:update.

Server request: GET /pipelines/id/:id/webhook-secret.

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

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

Full command details

Reveal the webhook signing secret until acknowledged. Use --secret-file to suppress it from output.

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 pipelines webhook-secret reveal workflow

Recover the current unacknowledged secret and write it to a private file; the reveal can be repeated until acknowledged.

sh
akedly pipelines webhook-secret reveal 0123456789abcdef01234567 --secret-file ./private/webhook-secret.txt

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "secretFile": "./private/webhook-secret.txt"
  },
  "message": "Copy this secret now — it will not be shown again until you regenerate"
}

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

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

Additional command forms

sh
akedly pipelines webhook-secret reveal <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.

Without --secret-file, the CLI passes through the webhookSigningSecret in JSON. Use a private --secret-file to keep secret bytes out of stdout.

Common error guidance.

pipelines webhook-secret regenerate

Rotate a compromised or lost webhook signing secret, invalidating the previous secret immediately.

When to use

  • Use only when ready to deploy the replacement to the webhook receiver.

How it works

  1. Rotates the current secret, invalidating the previous value. With --secret-file, the CLI removes the secret field from JSON and writes it privately; without it, JSON contains the secret. Acknowledge after the replacement has been safely captured.

Prerequisites

  • A CLI login with permission for this account and resource.
  • For secret-safe machine output, choose a new private --secret-file path; omitting it places webhookSigningSecret in the JSON response.

Expected outcome

A newly rotated webhook signing secret. A private file sink returns secretFile without the secret; without --secret-file the secret is present in JSON.

Next steps

  • Deploy the replacement secret, then acknowledge it; until deployment, signed webhook verification using the old secret will fail.

Usage

sh
akedly pipelines webhook-secret regenerate <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "pipelines webhook-secret regenerate" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Required positional argument.

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--secret-filetext—Write the secret to a new mode 0600 file and omit it from output; an existing path is refused.
--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: pipelines:update.

Server request: POST /pipelines/id/:id/webhook-secret/regenerate.

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

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

Full command details

Rotate the webhook signing secret; the old secret stops immediately. Save the new secret before acknowledging it. The new secret is printed by default; prefer --secret-file <new path> to save it privately instead.

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 pipelines webhook-secret regenerate workflow

Rotate a compromised or lost webhook signing secret, invalidating the previous secret immediately.

sh
akedly pipelines webhook-secret regenerate 0123456789abcdef01234567 --yes --secret-file ./private/webhook-secret.txt

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "secretFile": "./private/webhook-secret.txt"
  },
  "message": "Webhook signing secret regenerated successfully. Update your server immediately."
}

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

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

Additional command forms

sh
akedly pipelines webhook-secret regenerate <id> --yes --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.

Without --secret-file, the CLI passes through the webhookSigningSecret in JSON. Use a private --secret-file to keep secret bytes out of stdout.

Common error guidance.

pipelines webhook-secret acknowledge

Confirm that the replacement webhook secret has been securely captured, allowing the secret lifecycle to be closed.

When to use

  • Use after saving a newly issued or revealed secret; supply either the saved secret file or its exact final four characters.

How it works

  1. Sends only the secret suffix for server-side acknowledgement; confirmation required.

Prerequisites

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

Expected outcome

Acknowledgement result without returning secret material.

Next steps

  • Keep the saved secret in the webhook receiver’s secret store.

Usage

sh
akedly pipelines webhook-secret acknowledge <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "pipelines webhook-secret acknowledge" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Required positional argument.

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--secret-filetext—Command-specific option; see the full command details below. Manifest body field: secretSuffix.
--secret-suffixtext—Command-specific option; see the full command details below. Manifest body field: secretSuffix.
--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: pipelines:update.

Server request: POST /pipelines/id/:id/webhook-secret/acknowledge.

Shared server-guard guidance.

Consent

--yes. --dry-run bypasses confirmation where supported. Destructive: true. 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

Acknowledge holding the secret using exactly one file or four-character suffix. After acknowledgement reveal is refused.

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 pipelines webhook-secret acknowledge workflow

Confirm that the replacement webhook secret has been securely captured, allowing the secret lifecycle to be closed.

sh
akedly pipelines webhook-secret acknowledge 0123456789abcdef01234567 --secret-suffix AQE= --yes

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "message": "Secret acknowledged"
}

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

Synthetic acknowledge from the saved webhook-secret file

Confirm that the replacement webhook signing secret was saved so its rotation can be acknowledged.

sh
akedly pipelines webhook-secret acknowledge 0123456789abcdef01234567 --secret-file ./fixtures/saved-webhook-secret.txt --yes

Input file: ./fixtures/saved-webhook-secret.txt (text).

text
[REDACTED — use your privately saved secret file]

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "message": "Secret acknowledged"
}

Prerequisites: an authorized CLI login and the exact saved secret file for this pipeline. The CLI sends only the file's final four characters for acknowledgement; it does not return a data object.

Secret fixture content is synthetic and must be redacted from any rendered human guide. Keep the real saved secret in the webhook receiver's secret store. Acknowledgement confirms capture; it does not revoke or consume the saved value.

Additional command forms

sh
akedly pipelines webhook-secret acknowledge <id> --secret-file <saved path> --yes
sh
akedly pipelines webhook-secret acknowledge <id> --secret-suffix <last 4 characters> --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 success response contains status and message only; it has no data field.

Common error guidance.

pipelines webhook-test preview

Inspect the payload and signing headers Akedly would use for a selected test webhook event.

When to use

  • Use to inspect the supported event list, generated signature-header placeholders and synthetic payload before testing a receiver.

How it works

  1. Builds a preview from the owned pipeline and requested event; read-only.

Prerequisites

  • An existing owned pipeline with an allowed test event for its API version and product; a configured callback URL is needed for the later run, not the preview.

Expected outcome

Preview payload and headers returned by the API.

Next steps

  • Check that the receiver accepts the event shape before using webhook-test run.

Usage

sh
akedly pipelines webhook-test preview <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "pipelines webhook-test preview" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Required positional argument.

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--eventtext—Command-specific option; see the full command details below. Query parameter: event.
--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: pipelines:read.

Server request: GET /pipelines/id/:id/webhook-test/preview.

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

Preview the sample webhook payload and placeholder signing headers.

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 pipelines webhook-test preview workflow

Inspect the payload and signing headers Akedly would use for a selected test webhook event.

sh
akedly pipelines webhook-test preview 0123456789abcdef01234567 --event verification

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "event": "verification",
    "events": [
      "verification"
    ],
    "method": "POST",
    "url": "https://receiver.example.invalid/hooks/akedly",
    "headers": {
      "Content-Type": "application/json",
      "User-Agent": "Akedly-Webhook/1.0",
      "svix-id": "msg_•••••• (generated)",
      "svix-timestamp": "•••••••••• (generated)",
      "svix-signature": "v1,•••••• (generated)"
    },
    "body": {
      "event": "webhook.test",
      "test": true,
      "mainTransaction": {
        "transactionID": "tx_example_001",
        "status": "Successful",
        "verificationAddress": {
          "phoneNumber": "+201234567890"
        },
        "OTP": "123456",
        "resolvedChannel": "whatsapp",
        "channels": [
          "whatsapp"
        ],
        "isTest": false,
        "userID": "0123456789abcdef01234567",
        "pipelineID": "89abcdef0123456789abcdef",
        "creationDate": "2030-03-12T08:57:00.000Z",
        "expirationDate": "2030-03-12T09:01:00.000Z",
        "updateDate": "2030-03-12T09:00:00.000Z",
        "verificationMethod": "Whatsapp"
      },
      "transactionReq": {
        "_id": "fedcba987654321001234567",
        "mainTransactionID": "tx_example_001",
        "status": "Successful",
        "isTest": false,
        "channels": [
          "whatsapp"
        ],
        "sentVerificationDate": "2030-03-12T08:57:00.000Z",
        "inputOTP": "123456",
        "verificationDate": "2030-03-12T09:00:00.000Z",
        "creationDate": "2030-03-12T08:57:00.000Z",
        "expirationDate": "2030-03-12T09:01:00.000Z",
        "verificationMethod": "Whatsapp"
      }
    }
  }
}

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 pipelines webhook-test preview <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.

The sample payload contains synthetic transaction and OTP values; actual previews are generated from a synthetic test transaction and vary by pipeline version/product.

Common error guidance.

pipelines webhook-test run

Send a signed test event to the pipeline’s configured webhook URL to verify receiver connectivity.

When to use

  • Use after previewing the event and confirming the configured URL is a safe test receiver.

How it works

  1. Requires explicit confirmation; this makes an outbound webhook request and can trigger receiver-side effects.

Prerequisites

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

Expected outcome

Delivery attempt result returned by the server.

Next steps

  • Inspect receiver logs and delivery result; avoid automatic retries if the outcome is ambiguous.

Usage

sh
akedly pipelines webhook-test run <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "pipelines webhook-test run" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Required positional argument.

Flags

FlagTypeEnum / rangeDescription
--ksaboolean switch—Select the KSA deployment.
--eventtext—Command-specific option; see the full command details below. Manifest body field: event.
--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: pipelines:update.

Server request: POST /pipelines/id/:id/webhook-test.

Shared server-guard guidance.

Consent

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

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: echo-scrub. echo-scrub masks secret-shaped text, credential fields, secret query parameters and JSON secret fields inside strings in the response, such as a webhook receiver echo or BYO-SMS steps; keep the output private anyway.

Full command details

Send a signed sample to the configured backend callback URL. Exit 0 means the request ran; read the top-level delivered (false on delivery failure), statusCode, error and tip. Secret-shaped text in any response string is shown as [REDACTED].

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 pipelines webhook-test run workflow

Send a signed test event to the pipeline’s configured webhook URL to verify receiver connectivity.

sh
akedly pipelines webhook-test run 0123456789abcdef01234567 --event verification --yes

Illustrative response (sensitive values omitted):

json
{
  "delivered": true,
  "statusCode": 200,
  "durationMs": 12,
  "error": null,
  "tip": null,
  "request": {
    "method": "POST",
    "url": "https://receiver.example.invalid/hooks/akedly",
    "headers": {
      "Content-Type": "application/json",
      "User-Agent": "Akedly-Webhook/1.0",
      "svix-id": "msg_fixture_001",
      "svix-timestamp": "1890000000",
      "svix-signature": "v1,AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
    },
    "body": {
      "event": "webhook.test",
      "test": true,
      "mainTransaction": {
        "transactionID": "tx_example_001",
        "status": "Successful",
        "verificationAddress": {
          "phoneNumber": "+201234567890"
        },
        "OTP": "123456",
        "resolvedChannel": "whatsapp",
        "channels": [
          "whatsapp"
        ],
        "isTest": false,
        "userID": "0123456789abcdef01234567",
        "pipelineID": "89abcdef0123456789abcdef",
        "creationDate": "2030-03-12T08:57:00.000Z",
        "expirationDate": "2030-03-12T09:01:00.000Z",
        "updateDate": "2030-03-12T09:00:00.000Z",
        "verificationMethod": "Whatsapp"
      },
      "transactionReq": {
        "_id": "fedcba987654321001234567",
        "mainTransactionID": "tx_example_001",
        "status": "Successful",
        "isTest": false,
        "channels": [
          "whatsapp"
        ],
        "sentVerificationDate": "2030-03-12T08:57:00.000Z",
        "inputOTP": "123456",
        "verificationDate": "2030-03-12T09:00:00.000Z",
        "creationDate": "2030-03-12T08:57:00.000Z",
        "expirationDate": "2030-03-12T09:01:00.000Z",
        "verificationMethod": "Whatsapp"
      }
    }
  },
  "response": {
    "body": "accepted"
  }
}

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

This operation contacts the configured webhook receiver; the synthetic example is not to be executed.

The receiver URL must be configured on the existing pipeline. This command contacts it; the sample must not be executed.

Additional command forms

sh
akedly pipelines webhook-test run <id> --yes
sh
akedly pipelines webhook-test run <id> --yes --fields delivered,statusCode,error,tip

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.

Delivery failures are HTTP 200 command results with delivered:false; statusCode and response.body can be null. Inspect error and tip before deciding whether to retry.

The request snapshot includes the synthetic test payload and signed headers. Actual timestamps, IDs and signatures are generated per run.

Common error guidance.

pipelines test-challenge

Fetch a fresh challenge for the dashboard test-send flow without sending an OTP.

When to use

  • Use immediately before a dashboard test send that requires PoW or Turnstile challenge data.

How it works

  1. Reads a fresh V1.2 challenge for the chosen pipeline.

Prerequisites

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

Expected outcome

Challenge token, difficulty, expiry, algorithm and Turnstile requirement as returned by the API.

Next steps

  • Pass the fresh challenge through the test-send flow; do not reuse expired challenge data.

Usage

sh
akedly pipelines test-challenge

Inspect this command offline before preparing an operation:

sh
akedly describe "pipelines test-challenge" --output json

Flags

FlagTypeEnum / rangeRequiredDescription
--ksaboolean switch—noSelect the KSA deployment.
--pipeline-idid—yesCommand-specific option; see the full command details below. Query parameter: pipelineID.
--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: sandbox:execute.

Server request: GET /api/v1.2/transactions/dashboard/challenge.

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

Fetch a fresh V1.2 dashboard PoW challenge. Requires a Full access CLI Login with sandbox:execute and a usable account API key; Read-only logins and logins approved by Akedly staff without full access are refused. First enable dev mode explicitly with pipelines dev-mode set <id> --dev-mode on --yes and use the returned fake Test Pair, valid for about an hour. Test commands never enable dev mode or bypass flags.

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 pipelines test-challenge workflow

Fetch a fresh challenge for the dashboard test-send flow without sending an OTP.

sh
akedly pipelines test-challenge --pipeline-id 0123456789abcdef01234567

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "challengeRequired": true,
    "challengeToken": "synthetic-token",
    "challenge": "synthetic-challenge",
    "difficulty": 2,
    "expiresAt": "2030-03-12T09:05:00.000Z",
    "algorithm": "sha256",
    "turnstile": {
      "required": false,
      "siteKey": 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 pipelines test-challenge --pipeline-id <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.

pipelines test-send

Send a dashboard test OTP to validate the pipeline and recipient path.

When to use

  • Use only with an authorized test destination and explicit confirmation; a real SMS/WhatsApp delivery may incur provider cost.

How it works

  1. Fetches a fresh challenge, solves PoW where required, then sends once; ambiguous POST outcomes are not automatically retried.

Prerequisites

  • An existing V1.2 OTP pipeline owned by the logged-in account.
  • An authorized test destination; this command sends an OTP and may incur provider cost.

Expected outcome

Transaction IDs for the send request.

Next steps

  • Check delivery and use test-verify with the transaction request ID if verifying the code.

Usage

sh
akedly pipelines test-send

Inspect this command offline before preparing an operation:

sh
akedly describe "pipelines test-send" --output json

Flags

FlagTypeEnum / rangeRequiredDescription
--ksaboolean switch—noSelect the KSA deployment.
--pipeline-idid—yesCommand-specific option; see the full command details below. Manifest body field: pipelineID.
--phone-numbertext—yesCommand-specific option; see the full command details below. Manifest body field: verificationAddress.phoneNumber.
--turnstile-tokentext—noCommand-specific option; see the full command details below. Manifest body field: turnstileToken.
--yesboolean switch—noConfirm this action where consent is required.
--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: sandbox:execute.

Server request: POST /api/v1.2/transactions/dashboard/send.

Shared server-guard guidance.

Consent

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

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

Fetch and solve a fresh PoW challenge, then send once. Requires --yes and a Full access CLI Login with sandbox:execute and a usable account API key; Read-only logins and logins approved by Akedly staff without full access are refused. The send is real and billed unless the number is the pipeline's dev-mode Test Pair. For a free test, first run akedly pipelines dev-mode set <id> --dev-mode on --yes and send to the Test Pair it returns (valid for about an hour). This command never enables dev mode or bypass flags. An ambiguous failure may have sent a message; check the destination before retrying. Dry runs send nothing and need no CLI Login.

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 pipelines test-send workflow

Send a dashboard test OTP to validate the pipeline and recipient path.

sh
akedly pipelines test-send --pipeline-id 0123456789abcdef01234567 --phone-number +201234567890 --yes

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "transactionID": "tx_example_001",
    "transactionReqID": "89abcdef0123456789abcdef"
  }
}

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

This operation sends an OTP and may incur cost; the synthetic example is not to be executed.

Additional command forms

sh
akedly pipelines test-send --pipeline-id <id> --phone-number <number> --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.

pipelines test-verify

Complete a V1.2 dashboard test verification by checking the OTP against its transaction request.

When to use

  • Use only after a V1.2 dashboard test-send has returned a transactionReqID and the test code is available.

How it works

  1. Checks transaction ownership for the logged-in account, then calls the V1.2 secure OTP verifier. A successful response returns verified, transactionID and frontendCallbackURL, and may include enrollmentToken for eligible phone verification.

Prerequisites

  • A transactionReqID returned by a V1.2 dashboard test-send for this account, plus the received test OTP.

Expected outcome

Transaction request status returned by the API.

Next steps

  • Check the final status; if expired or failed, begin a new test-send.

Usage

sh
akedly pipelines test-verify <transactionReqID>

Inspect this command offline before preparing an operation:

sh
akedly describe "pipelines test-verify" --output json
PositionalGrammarUsage guidance
<transactionReqID>^[a-fA-F0-9]{24}$transactionReqID must be a 24-hex transaction request id.

Flags

FlagTypeEnum / rangeRequiredDescription
--ksaboolean switch—noSelect the KSA deployment.
--otptext—yesCommand-specific option; see the full command details below. Manifest body field: otp.
--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: sandbox:execute.

Server request: POST /api/v1.2/transactions/dashboard/verify/:transactionReqID.

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

Sensitive output: live-otp. Responses may contain live OTP fields; keep them private.

Full command details

Verify a dashboard V1.2 transaction using a Full access CLI Login with sandbox:execute; Read-only logins and logins approved by Akedly staff without full access are refused. Successful verification can fire the configured backend webhook; responses can include live OTP fields, so keep output private.

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 pipelines test-verify workflow

Verify an OTP from a dashboard test-send transaction.

sh
akedly pipelines test-verify 89abcdef0123456789abcdef --otp 123456

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "verified": true,
    "transactionID": "tx_example_001",
    "frontendCallbackURL": "https://app.example.invalid/verified"
  },
  "message": "OTP verified successfully"
}

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 pipelines test-verify <transactionReqID> --otp 1234

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

This command uses the V1.2 dashboard verification endpoint. The success DTO contains verified, transactionID and frontendCallbackURL; enrollmentToken may be present for eligible phone verifications.

Common error guidance.

pipelines sandbox-demo ensure

Provision or retrieve the account’s isolated sandbox demo pipeline and associated demo resources.

When to use

  • Use for a sandbox walkthrough when a demo setup is needed; it is not a production pipeline.

How it works

  1. Ensures demo resources for the requested API version; repeated calls converge on the sandbox setup.

Prerequisites

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

Expected outcome

The ensured demo version, a safe pipeline projection, and either widget:null (V1.2) or an ensured widget projection (V2).

Next steps

  • For V1.2, use the direct API demo flow. For V2, inspect the returned widget, then finish hosted-widget setup as required; provisioning does not by itself complete a production embed.

Usage

sh
akedly pipelines sandbox-demo ensure

Inspect this command offline before preparing an operation:

sh
akedly describe "pipelines sandbox-demo ensure" --output json

Flags

FlagTypeEnum / rangeRequiredDescription
--ksaboolean switch—noSelect the KSA deployment.
--api-versionenumv1.2 | v2yesCommand-specific option; see the full command details below. Manifest body field: version. Tip: Use V2 if you will embed Akedly's hosted widget, and V1.2 if you will build the verification screens yourself or cannot embed an iframe or open a system browser. V1.0 is legacy and sunsets on December 30, 2026.
--yesboolean switch—noConfirm this action where consent is required.
--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: sandbox:execute.

Server request: POST /pipelines/sandbox-demo/ensure.

Shared server-guard guidance.

Consent

--yes. --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

Ensure the signed-in account's OTP sandbox demo resources with --api-version v1.2|v2 --yes (--version prints the CLI package version). Requires a Full access CLI Login with sandbox:execute and pipelines:create; V2 also requires widgets:create. Read-only logins are refused. This can adopt your existing unmarked OTP pipeline (or legacy pipeline with no product) named exactly "Sandbox Demo Pipeline" (for v1.2) or "Sandbox Widget Pipeline" (for v2) and the same API version and, for V2, an unmarked widget attached to it (one named "Sandbox Widget" first), or reattach a demo widget whose pipeline was deleted. Each run resets the demo pipeline's API version and, for V2, both callback URLs, so callback changes made with pipelines update do not persist. These writes need only the permissions above, not pipelines:update or widgets:update; --yes confirms them. New demo pipelines are active Test pipelines. V2 callbacks point to the environment's dashboard /admin and API /sandbox-webhook-sink. The API does not serve /sandbox-webhook-sink yet, so this callback is not a working demo webhook receiver; test your own handler with akedly pipelines webhook-test run <id> --yes on your own pipeline instead. This is separate from akedly utilities sandbox status/send and prepares OTP resources without sending, charging or enabling dev mode. Next for v1.2: run akedly pipelines dev-mode set <id> --dev-mode on --yes (needs pipelines:dev_mode), then akedly pipelines test-send --pipeline-id <id> --phone-number <Test Pair number> --yes, then akedly pipelines test-verify <transactionReqID> --otp <Test Pair OTP>, using data.transactionReqID from test-send. Use the current returned data.devMode.testPair phoneNumber and otp from dev-mode set while that window is active; only this Test Pair is free. test-send needs sandbox:execute and a usable server-selected account API key; any other number is a real, billed send. Inspect the returned pipeline id, name, API version, channel and server-reported devMode enabled/expiresAt; an enabled window can already be expired. V2 also returns widget id/publicKey, without its Secret. Reused or adopted pipelines and widgets keep their current active state and status, which the response does not show (reused widgets are not reactivated); check them with akedly pipelines get <id> and akedly widgets get <id>; reactivate with akedly pipelines update <id> --status active --yes or akedly widgets update <id> --status active --yes. No Test Pair, callback URLs, secrets or authentication URL are returned. This prepared V2 demo is not complete headless V2 setup: open the dashboard Home or Authentication page and choose Test now → Drop-in widget. Its sandbox launch requires an allowed dashboard Origin and session; the widget Secret is not returned here. Set widget dev mode with akedly widgets update <widgetId> --dev-mode on --yes (needs widgets:update), and read its current Test Pair at data.devMode.testPair with akedly widgets get <widgetId>. Resources can remain partly prepared after failure: repeat this command with the same --api-version to converge, except after a SANDBOX_PIPELINE_PURPOSE_CONFLICT or SANDBOX_WIDGET_PURPOSE_CONFLICT, which repeating will not fix; do not automatically delete them. Run akedly pipelines list first to inspect possible same-name adoption; dry-run does not inspect existing resources. Dry-run validates and previews offline without consent, credentials or requests.

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 pipelines sandbox-demo ensure workflow

Provision or retrieve the account’s isolated sandbox demo pipeline and associated demo resources.

sh
akedly pipelines sandbox-demo ensure --api-version v1.2 --yes

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "version": "v1.2",
    "pipeline": {
      "_id": "0123456789abcdef01234567",
      "name": "Sandbox Demo Pipeline",
      "apiVersion": "v1.2",
      "channel": "whatsapp",
      "devMode": {
        "enabled": false
      }
    },
    "widget": 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 pipelines sandbox-demo ensure --api-version v1.2 --yes
sh
akedly pipelines sandbox-demo ensure --api-version v2 --yes
sh
akedly pipelines sandbox-demo ensure --api-version v2 --dry-run

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.

Own recovery guidance

CodeHint
INVALID_SANDBOX_VERSIONUse --api-version v1.2 or --api-version v2; --version prints the CLI package version.
SANDBOX_INDEX_UNAVAILABLESandbox purpose indexes are unavailable. Retry later with the same --api-version or contact Akedly support.
SANDBOX_PIPELINE_PURPOSE_CONFLICTAn incompatible pipeline holds the demo purpose. Inspect akedly pipelines list and ask Akedly support to resolve the conflict before repeating ensure.
SANDBOX_WIDGET_PURPOSE_CONFLICTThe demo widget purpose is attached to another pipeline. Inspect akedly widgets list and akedly widgets list --status inactive, and ask Akedly support to resolve the conflict; do not delete resources automatically.
SANDBOX_RESOURCE_CHANGEDA sandbox resource changed during preparation. Repeat akedly pipelines sandbox-demo ensure with the same --api-version and --yes.
SANDBOX_ENSURE_FAILEDResources may be partly prepared. Repeat akedly pipelines sandbox-demo ensure with the same --api-version and --yes; if it keeps failing, contact Akedly support.

Common error guidance.

zero-verify-bans list

Review phone, email, or device identities currently banned for repeated verification attempts that never completed.

When to use

  • Use to diagnose why a customer identity cannot start another verification.

How it works

  1. Reads bans belonging to the logged-in account, newest first; identity values are sensitive account data.

Prerequisites

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

Expected outcome

Array of ban records with status, rung, dates, mode and lift metadata.

Next steps

  • If the ban is no longer warranted, unban its record ID; otherwise wait for expiry or review the underlying behavior.

Usage

sh
akedly zero-verify-bans list

Inspect this command offline before preparing an operation:

sh
akedly describe "zero-verify-bans list" --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: zero_verify_bans:read.

Server request: GET /zero-verify-bans.

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 account zero-verify bans.

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 zero-verify-bans list workflow

Review phone, email, or device identities currently banned for repeated verification attempts that never completed.

sh
akedly zero-verify-bans list

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": [
    {
      "_id": "0123456789abcdef01234567",
      "identityType": "phone",
      "identityValue": "+201234567890",
      "rung": 1,
      "bannedAt": "2030-03-12T09:00:00.000Z",
      "expiresAt": "2030-03-12T10:00:00.000Z",
      "status": "active",
      "mode": "enforce"
    }
  ]
}

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 zero-verify-bans 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.

zero-verify-bans unban

Lift one account-owned zero-verify ban and exonerate its associated identity.

When to use

  • Use after confirming the identity should regain access; lifting affects enforcement immediately.

How it works

  1. Requires confirmation, checks ownership/current status, records a manual lift and emits an operational notification.

Prerequisites

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

Expected outcome

Updated ban record with lifted status and timestamp.

Next steps

  • Retry the customer flow after lift; the identity may be banned again if the underlying pattern recurs.

Usage

sh
akedly zero-verify-bans unban <id>

Inspect this command offline before preparing an operation:

sh
akedly describe "zero-verify-bans unban" --output json
PositionalGrammarUsage guidance
<id>^[a-fA-F0-9]{24}$Required positional argument.

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: zero_verify_bans:update.

Server request: PATCH /zero-verify-bans/:id/unban.

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

Lift a zero-verify security ban.

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 zero-verify-bans unban workflow

Lift one account-owned zero-verify ban and exonerate its associated identity.

sh
akedly zero-verify-bans unban 0123456789abcdef01234567 --yes

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "_id": "0123456789abcdef01234567",
    "identityType": "phone",
    "identityValue": "+201234567890",
    "rung": 1,
    "bannedAt": "2030-03-12T09:00:00.000Z",
    "expiresAt": "2030-03-12T10:00:00.000Z",
    "status": "lifted",
    "liftedAt": "2030-03-12T09:30:00.000Z",
    "liftReason": "manual",
    "mode": "enforce"
  }
}

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 zero-verify-bans unban <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.

webhooks verify

Verify locally that a received Akedly webhook’s exact raw body matches its Svix signature and timestamp.

When to use

  • Use in a receiver or incident investigation with the original body bytes, headers and current pipeline signing secret.

How it works

  1. Reads bounded local files, checks timestamp tolerance, and computes HMAC locally; it sends no network request.

Prerequisites

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

Expected outcome

A valid verdict with timestampAgeSeconds, or a coded local verification error.

Next steps

  • Only parse/process the webhook after valid is true; preserve raw bytes and use the active secret.

Usage

sh
akedly webhooks verify

Inspect this command offline before preparing an operation:

sh
akedly describe "webhooks verify" --output json

Flags

FlagTypeEnum / rangeRequiredDescription
--secret-filetext—noCommand-specific option; see the full command details below.
--headerstext—yesCommand-specific option; see the full command details below.
--bodytext—yesCommand-specific option; see the full command details below.
--tolerance-secondsinteger1 to 86400noCommand-specific option; see the full command details below.
--atinteger0 to 4102444800noCommand-specific option; see the full command details below.
--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: public. Permission: none declared.

Shared server-guard guidance.

Consent

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

Retry

local: Local command; no HTTP retry.

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

Verify a webhook locally using the exact raw body and a JSON headers file. Use --secret-file or AKEDLY_WEBHOOK_SECRET (file wins). Tolerance defaults to 300 seconds inclusive; --at supplies Unix seconds for historical verification. Prints no body or secret.

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 webhooks verify workflow

Verify locally that a received Akedly webhook’s exact raw body matches its Svix signature and timestamp.

sh
akedly webhooks verify --secret-file ./private/webhook-secret.txt --headers ./fixtures/headers.json --body ./fixtures/body.json --at 1890000000

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

json
{
  "svix-id": "msg_fixture_001",
  "svix-timestamp": "1890000000",
  "svix-signature": "v1,DAQq9ohld8V3MrFI74qZ+kK69edzQRDy7XNEl02DaPY="
}

Input file: ./fixtures/body.json (text).

text
{"event":"otp.verified","data":{"transactionID":"tx_example_001"}}

Input file: ./private/webhook-secret.txt (text).

text
[REDACTED — use your privately saved secret file]

Illustrative response (sensitive values omitted):

json
{
  "status": "success",
  "data": {
    "valid": true,
    "timestampAgeSeconds": 0
  }
}

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

The signing key and signature are synthetic and provided only to make this offline verification fixture internally consistent; never use this key in a deployed receiver.

Additional command forms

sh
akedly webhooks verify --secret-file <path> --headers <headers.json> --body <body-file>

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

This is a local computation: no API request is made. The exact raw body bytes are signed; re-serializing JSON changes the signature.

Common error guidance.