Utilities discovery and configuration

{
  "flagTokenEncoding": {
    "booleans": "A boolean schema describes switch presence: write --flag with no value.",
    "valuedFlags": "A string schema describes the single argv token after --flag or after --flag=; numeric token schemas parse as decimal strings and validation.parsedValueSchema documents the converted number.",
    "csvFlags": "A list schema describes one comma-separated argv token, not multiple shell arguments.",
    "projection": "--fields is one comma-separated argv token of safe dot paths and changes returned output only."
  },
  "positionals": [],
  "flags": [
    {
      "name": "help",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "output",
      "schema": {
        "type": "string",
        "enum": [
          "json",
          "human"
        ]
      },
      "required": false
    },
    {
      "name": "fields",
      "schema": {
        "type": "string",
        "pattern": "^(?!.*(?:^|[.,])(?:__proto__|constructor|prototype)(?:[.,]|$))(?!,)(?!.*,,)(?!.*,$)[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*(?:,[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*)*$"
      },
      "required": false,
      "validation": {
        "syntax": "Comma-separated safe dot paths; reserved prototype keys are refused."
      }
    },
    {
      "name": "ksa",
      "schema": {
        "type": "boolean"
      },
      "required": false
    }
  ],
  "files": [],
  "wire": {
    "method": "GET",
    "route": "/utilities/cost-rates",
    "query": {},
    "body": {},
    "ownerParams": []
  }
}

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "status": {
        "const": "success"
      },
      "data": {
        "type": "object",
        "properties": {
          "currency": {
            "const": "EGP"
          },
          "smsPerSegmentEGP": {
            "type": [
              "number",
              "null"
            ]
          },
          "whatsappPerMessageEGP": {
            "type": [
              "number",
              "null"
            ]
          },
          "smsFlatFeeEGP": {
            "type": [
              "number",
              "null"
            ]
          },
          "smsFlatFeeVariesByDestination": {
            "type": "boolean"
          },
          "smsFlatFeeMinEGP": {
            "type": [
              "number",
              "null"
            ]
          },
          "smsFlatFeeMaxEGP": {
            "type": [
              "number",
              "null"
            ]
          },
          "smsProvider": {
            "type": [
              "string",
              "null"
            ]
          },
          "smsEligible": {
            "type": "boolean"
          }
        },
        "additionalProperties": true,
        "required": [
          "currency",
          "smsPerSegmentEGP",
          "whatsappPerMessageEGP",
          "smsFlatFeeEGP"
        ]
      }
    },
    "required": [
      "status",
      "data"
    ],
    "additionalProperties": true
  },
  "variants": [],
  "fieldSelection": {
    "flag": "fields",
    "behavior": "Selects comma-separated dot paths from the response root; for root arrays, paths apply to each element. Missing paths are omitted.",
    "sensitiveData": null
  }
}

[
  {
    "title": "Synthetic representative response",
    "value": {
      "status": "success",
      "data": {
        "currency": "EGP",
        "smsPerSegmentEGP": null,
        "whatsappPerMessageEGP": 0.75,
        "smsFlatFeeEGP": null,
        "smsFlatFeeVariesByDestination": false,
        "smsFlatFeeMinEGP": null,
        "smsFlatFeeMaxEGP": null,
        "smsProvider": null,
        "smsEligible": false
      }
    }
  }
]

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": [
      "status",
      "code",
      "message",
      "httpStatus",
      "hint"
    ],
    "properties": {
      "status": {
        "const": "error"
      },
      "code": {
        "type": "string"
      },
      "message": {
        "type": "string"
      },
      "httpStatus": {
        "type": [
          "integer",
          "null"
        ]
      },
      "details": {
        "anyOf": [
          {
            "type": "object",
            "minProperties": 1
          },
          {
            "type": "array",
            "minItems": 1
          }
        ]
      },
      "hint": {
        "type": "string"
      }
    },
    "additionalProperties": false
  },
  "globalHints": {
    "TOTP_DELETE_RECONCILIATION_PENDING": "Any Pending request blocks deletion, including one just opened; Failed requests can block too. Ordinary unverified, unbilled requests expire about five minutes after creation and normally become Expired on the next five-minute reconciliation run, within about ten minutes of creation; job delays or billing/counter recovery can extend that wait. Check the stored status in akedly totp history list; computed isExpired alone does not unblock deletion. Ask Akedly support if a request stays Pending or Failed beyond that normal window, or is Verified and still blocks.",
    "CLI_SECRET_ALREADY_DELIVERED": "Run akedly login again.",
    "CLI_LOGIN_INVALID": "Run akedly login.",
    "PERMISSION_DENIED": "If details.permission names a permission, ask an organization admin to grant it to your role. Otherwise read the server message: an organization admin cannot clear refusals such as an inactive or unverified account, an Akedly-managed global role, a reported-invitation pause or missing enterprise entitlement; follow the message or contact Akedly support. If the message says BYO-SMS is not enabled for this account, the account needs BYO-SMS entitlement and granular pricing; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and only Akedly can change either.",
    "ORG_ADMIN_REQUIRED": "If the message asks for an active organization session, run akedly login and approve it with the intended organization active in the dashboard. If it says organization admin access is required, ask an organization admin for access or to run the command. Role changes can take up to 60 seconds to apply.",
    "OWNER_REQUIRED": "Only the account owner can do this; an organization admin is not necessarily the owner. Ask the owner to run it from their own login. For seats, organization admins can read akedly seats visibility; akedly seats status is owner-only.",
    "LOGIN_REQUIRED": "Run akedly login. If you supplied a credential, check --ksa or AKEDLY_REGION.",
    "CLI_DISABLED": "Customer CLI access is turned off on this Akedly server. Try again later or contact Akedly support.",
    "CLI_IDENTITY_UNAVAILABLE": "Akedly could not confirm your login right now. Wait a minute and try again.",
    "CLI_LOGIN_INDEX_UNAVAILABLE": "CLI login is temporarily unavailable on this server. Try again later or contact Akedly support.",
    "WABA_PHONE_CHECK_UNAVAILABLE": "Meta did not confirm the number. Wait a few minutes, then run the command again.",
    "CLI_UPGRADE_REQUIRED": "Install the latest @akedly/cli.",
    "NOT_AVAILABLE_ON_SERVER": "Check the selected region or ask an operator to deploy CLI support.",
    "CLI_RATE_LIMITED": "Wait before trying again.",
    "CLI_LOGIN_DENIED": "Run akedly login again and approve the new code.",
    "CLI_LOGIN_REQUEST_EXPIRED": "Run akedly login again.",
    "LOGIN_TIMEOUT": "Run akedly login again and approve before the timeout.",
    "CLI_READ_ONLY": "This login is read-only. Run akedly login and choose Full access.",
    "CLI_LOGIN_LIMIT_REACHED": "Run akedly cli-logins list, then akedly cli-logins end <id>",
    "CLI_LOGIN_NOT_FOUND": "Run akedly cli-logins list and check the login id.",
    "CLI_LOGIN_OWNER_PROTECTED": "Ask the account owner to end this login.",
    "IMPERSONATION_BLOCKED": "This login was approved by Akedly staff and can't do this. Run akedly login and approve it in your own dashboard session.",
    "SELF_IDENTITY_REQUIRED": "Personal settings need your own login. Run akedly login and approve it in your own dashboard session.",
    "MEMBER_NOT_FOUND": "Check the email with akedly team members list; a pending invitation is not a member yet.",
    "MEMBER_AMBIGUOUS": "Pass the memberId from akedly team members list instead of the email.",
    "API_KEY_ACTIVE_CAP_REACHED": "Revoke an unused key before creating another.",
    "API_KEY_ISSUANCE_DISABLED": "Ask an operator to enable API-key issuance.",
    "API_KEY_VERSION_CONFLICT": "List the keys and retry the edit with the current version.",
    "API_KEY_BUDGET_CONFIRMATION_REQUIRED": "Review the reduction and pass --confirm-budget-reduction.",
    "API_KEY_ISSUE_RECOVERY_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_TRANSITION_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_ISSUE_IDEMPOTENCY_CONFLICT": "Use a new idempotency key for different issue details.",
    "API_KEY_SCOPE_NOT_ACTIVE": "Ask an operator to enable API-key scope editing.",
    "API_KEY_BUDGET_NOT_ACTIVE": "Ask an operator to enable API-key budget editing.",
    "API_KEY_NOT_FOUND": "Run akedly api-keys list and check the id.",
    "API_KEY_BUDGET_RACE": "List the keys and retry.",
    "V1_CREATION_NOT_ENTITLED": "V1 pipelines are not available to this account. Omit --api-version to create a V1.2 pipeline.",
    "SECRET_SUFFIX_REQUIRED": "Pass exactly one of --secret-file <saved path> or --secret-suffix <last 4 characters>.",
    "SECRET_SUFFIX_MISMATCH": "Reveal the current secret to --secret-file <new path> with akedly pipelines webhook-secret reveal <id> for webhook secrets, or akedly utilities pipelines signing-secret reveal <id> for utility request-signing secrets, then acknowledge with exactly one of --secret-file <that path> or --secret-suffix <last 4 characters>.",
    "CHANNEL_CHOICE_NOT_AVAILABLE": "Nothing in this request was saved. Each value in details.blockers names what is missing: not_entitled means Channel Choice isn't enabled on the account yet; legacy_pricing means the account needs granular pricing; not_pay_per_message means the pipeline is not billed per message, because it is billed per successful verification or the account has no billing plan yet; account_excluded and global_switch_off mean Channel Choice isn't offered to this account right now. Only Akedly can change these, so contact Akedly. utility_pipeline means utility pipelines have no Channel Choice. Resend any other changes without the Channel Choice flags.",
    "VERIFICATION_METHOD_UNAVAILABLE": "Nothing was saved. details.method is the word you typed, or the method's id if the method became unavailable after the CLI checked; running the command again rechecks the list and names the word. Remove that method from --verification-methods and retry, or contact Akedly if you expected it to be available.",
    "VERIFICATION_METHODS_REQUIRED": "A pipeline that has verification methods must keep at least one. Send the methods to keep instead of an empty list, for example akedly pipelines update <id> --verification-methods whatsapp,sms --yes.",
    "SETTING_NOT_FOR_THIS_PIPELINE": "Nothing in this request was saved. details.setting names the setting and details.useInstead what to use instead. For rate limits and the circuit breaker, reason api-version means this is a V1 or V2 pipeline, where they belong to a widget instead, so useInstead is widgets update. A widget must be attached to this pipeline first. Find attached widgets with akedly widgets list-filtered --pipeline-id <pipelineId>, then inspect the intended widget with akedly widgets get <widgetId>, using its 24-hex _id. This listing excludes inactive widgets by default. Also run akedly widgets list-filtered --pipeline-id <pipelineId> --status inactive before concluding that no widget is attached. Change its limits with akedly widgets update <widgetId> --rate-limits-file <file> --yes; use the widget file shape, not the pipeline file shape. Set its breaker with akedly widgets update <widgetId> --circuit-breaker on --yes (or off), and use --circuit-breaker-file <file> for widget thresholds and suspension durations; pipeline --circuit-breaker-sensitivity does not apply to widgets. If no widget is attached, create one with akedly widgets create --name <name> --pipeline-id <pipelineId> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <pipelineId> --yes. V2 attachment requires both callback URLs; V1 attachment requires entitlement. pipelines update now routes shared rate-limit, breaker and PoW flags to every attached widget on V1/V2. V1.2-only controls remain refused on V1/V2. Use the appropriate file shape for the resulting API version. For the Channel Choice widget experience, reason api-version means it needs a V2 pipeline, so create one with akedly pipelines create --name <name> --api-version v2 --redirect-url <url> --webhook-url <url> --secret-file <new path>, then attach a widget to it; reason no-widget means it needs a widget attached to this V2 pipeline, so create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <id> --yes, then retry. Resend any other changes without that flag.",
    "PIPELINE_CHANGED": "Another change landed first, so nothing was saved. Run the same command again; if you changed rate limits or destination countries, it reads the pipeline again first and merges your change onto the new version. Run akedly pipelines get <id> to see what changed.",
    "RATE_LIMIT_INVALID": "Check details.field and any details.errors. Use whole numbers above zero in the expected JSON object shape. Pipeline --rate-limits-file uses perPhoneNumber, perIpAddress and perPipeline; widget --rate-limits-file uses widgetAttempts and otpRequests, each with perPhoneNumber, perDevice and perWidget. Each takes perMinute, perHour and perDay. Widget --circuit-breaker-file uses floodThresholds and suspensionSeconds; durations are whole seconds. Correct the named field and rerun the command.",
    "EXPECTED_UPDATED_AT_INVALID": "The CLI reads the revision automatically. Run the command again to read the current settings; if this continues, check that the CLI and server are up to date and contact Akedly support. Do not invent a revision or remove the conflict check.",
    "DESTINATION_COUNTRIES_MODE_REQUIRED": "Nothing in this request was saved. A changed country list under mode all would be discarded: pass --destination-countries-mode only-selected or all-except-selected with --destination-countries, or leave the list out to keep every country open. --destination-countries-mode all on its own clears the list.",
    "NOT_ENOUGH_TRAFFIC": "Keep the current limits for now. Recommended limits need at least 100 analysed requests and better than low confidence; try again after more real traffic or with a longer --period such as last-quarter, or set limits yourself with --rate-limits-file.",
    "INVALID_COUNTRY_POLICY": "Nothing in this request was saved. Use two-letter country codes such as EG,SA with --destination-countries and a mode of all, only-selected or all-except-selected; the message names the problem.",
    "OTP_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "TURNSTILE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_NOT_AVAILABLE": "Nothing in this request was saved. Act on details.reason: not-offered means Cluster Gate is not offered for this pipeline right now, for example on a utility pipeline or in the KSA region; attaching a widget will not help on a V1.2 pipeline, because V1.2 pipelines cannot be attached to widgets; drop the Cluster Gate flags and resend any other changes; no-widget means Cluster Gate applies here only through a widget and none is attached, so attach an existing widget with akedly widgets update <widgetId> --pipeline-id <id> --yes, or create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, then retry; the pipeline must first be active, with both callback URLs and a verification method, and WIDGET_PIPELINE_NOT_READY says what is missing; on-create comes only from raw API requests that set Cluster Gate while creating a pipeline: create the pipeline first, then set Cluster Gate with akedly pipelines update <id> --cluster-gate on --cluster-gate-position balanced --yes; check-failed means availability could not be checked, so retry later; intent-missing comes only from raw API requests that omit clusterGateIntent: true.",
    "SECRET_ALREADY_ACKNOWLEDGED": "The secret was already acknowledged and cannot be shown again. Use the saved copy from pipeline creation (webhook secrets) or from reveal, for example the file written with --secret-file. Only if that copy is lost, use akedly pipelines webhook-secret regenerate <id> --yes --secret-file <new path> for webhook secrets, or akedly utilities pipelines signing-secret regenerate <id> --yes --secret-file <new path> for utility request-signing secrets. Regenerating stops the current secret immediately; deploy the new secret before using signed requests or accepting signed webhooks.",
    "WIDGET_PIPELINE_NOT_READY": "Fix each item in details.missing with akedly pipelines update <pipelineId> --status active --redirect-url <url> --webhook-url <url> --verification-methods whatsapp,sms,email --yes, passing only the flags for the missing items, then retry.",
    "WIDGET_IDENTITY_INDEX_UNAVAILABLE": "Widget identity indexes are unavailable. Retry later or contact Akedly support.",
    "INCOMPLETE_DATE_RANGE": "Supply both --start-date and --end-date, or neither.",
    "DATE_RANGE_TOO_LARGE": "Choose a date range of at most 30 days, counted as the command help describes.",
    "INVALID_DATE_RANGE": "Check both date bounds and their order.",
    "INVALID_DATE": "Use valid ISO dates for the requested range.",
    "NEEDS_BROWSER": "Turn Turnstile off for the pipeline in the dashboard, or run akedly pipelines dev-mode set <pipelineId> --dev-mode on --bypass-turnstile on --bypass-pow on --yes.",
    "SETUP_REQUIRED": "Finish phone setup on the Personal Notifications page of your Akedly dashboard, then retry.",
    "INVALID_API_KEY": "Check the API key: akedly api-keys list, or create one with akedly api-keys create --label <name> --save --yes.",
    "API_KEY_SCOPE_DENIED": "This API key is scoped to other pipelines; use a key that includes this pipeline.",
    "MAX_ATTEMPTS_EXCEEDED": "Too many wrong codes; send a new OTP.",
    "ALREADY_VERIFIED": "This request is already verified; check it with akedly transactions status.",
    "INVALID_OTP": "Check the code and retry; attempts are limited.",
    "PIPELINE_INACTIVE": "Run akedly pipelines update <pipelineId> --status active --yes, then retry.",
    "POW_CHALLENGE_EXPIRED": "Run the command again; it fetches a fresh challenge.",
    "POW_CHALLENGE_REPLAYED": "Run the command again; it fetches a fresh challenge.",
    "POW_DIFFICULTY_STALE": "Run the command again; it fetches a fresh challenge.",
    "STATUS_LOOKUP_RATE_LIMITED": "Wait for the retryAfter seconds in details, then retry; each lookup counts against the 300 ids per minute limit.",
    "TRANSACTION_EXPIRED": "This code or request has expired; send a new one.",
    "USE_V1_2_ENDPOINT": "This pipeline is V1.2. Use akedly otp v1.2 send.",
    "SIGNATURE_EXPIRED": "This machine's clock differs from the server's by more than 60 seconds. Fix the clock and run the command again; it signs a fresh request each time.",
    "WIDGET_USER_MISMATCH": "This API key belongs to a different account than the widget. Use a key from the widget owner's account.",
    "WEBHOOK_SIGNATURE_INVALID": "Use the pipeline's current whsec_ secret (regenerating invalidates the old one), the exact raw body bytes the server received (no re-serialising, no trailing newline), and the svix-id, svix-timestamp and svix-signature headers.",
    "WAIT_EXPIRED": "The request expired before it was verified; it cannot complete. Start a new one (otp v2 attempt, otp v1.2 send or otp v1 create).",
    "WAIT_FAILED": "The verification failed and cannot complete; start a new one.",
    "WAIT_TIMEOUT": "The wait ended; the verification may still complete. Check it with akedly transactions status. Resume with akedly transactions status --attempt-id <id> --wait (or --transaction-id <id> --wait).",
    "WEBHOOK_TIMESTAMP_STALE": "The webhook timestamp is outside the allowed window. Check this machine's clock, or pass --at <unix seconds> to check an older delivery, or --tolerance-seconds <seconds>.",
    "WEBHOOK_HEADERS_MISSING": "Pass a headers JSON file with the svix-id, svix-timestamp and svix-signature headers exactly as received.",
    "NO_USABLE_API_KEY": "This account has no usable API key for this pipeline. Create one with akedly api-keys create --label <name> --save --yes; a key scoped to selected pipelines must include this pipeline.",
    "INVALID_API_VERSION": "This command does not support this pipeline's API version. Check it with akedly pipelines get <id> and use the matching command for that version.",
    "DOCTOR_FAILED": "Fix the failed checks in details.checks, then run akedly doctor again.",
    "PAGINATION_LIMIT": "Narrow the filters, for example a date range or status, or raise --limit (maximum 100), then run again.",
    "PAGINATION_STALLED": "The list changed while it was being read, or the server stopped advancing. Run the command again.",
    "REPORT_NOT_FOUND": "Run akedly reports list and check the reportId.",
    "DAILY_LIMIT_REACHED": "Wait until an earlier successful, sent or in-flight report generation leaves the rolling 24-hour window; for example, a generation at 14:00 stops counting after 14:00 the next day. This limit covers the whole account, including dashboard and teammate generations.",
    "REPORT_IN_PROGRESS": "A report is already generating for this account; dashboard and teammate generations share the same slot. Run akedly reports list before trying again.",
    "TEMPLATE_DUPLICATE": "Run akedly whatsapp otp-templates list; recover missing languages with update --add-languages instead of adding the same template again.",
    "TEMPLATE_LIMIT_REACHED": "Archive an unused template with akedly whatsapp otp-templates delete <id> --yes before adding another; the limit is 20 per WABA.",
    "TEMPLATE_PROVISIONING_FAILED": "The template or changes are saved. Run akedly whatsapp otp-templates list, then update <id> --add-languages <failed languages> rather than creating again.",
    "TEMPLATE_WABA_REQUIRED": "Connect an active own WhatsApp Business Account in the dashboard before managing OTP templates; check akedly whatsapp status.",
    "TEMPLATE_WABA_CHANGED": "This template belongs to the previous WABA. Add it again for the currently connected account.",
    "COUNTRY_CATALOG_UNAVAILABLE": "The country catalog is temporarily unavailable. Try again later.",
    "NOT_A_UTILITY_PIPELINE": "Choose an owned utility pipeline from akedly pipelines list, or create one with akedly pipelines create --product utility --name <name>.",
    "TEST_RATE_LIMITED": "Wait for Retry-After before testing again; account, recipient or replay safety limits may apply. Reuse the same Vodafone idempotencyKey when checking an existing attempt.",
    "EGRESS_FINGERPRINT_STALE": "The sending address changed. Run akedly byo-sms vodafone readiness, check the new address list, then acknowledge again with the new fingerprint.",
    "VODAFONE_EGRESS_NOT_READY": "Run akedly byo-sms vodafone readiness; ask Akedly support to verify the outbound addresses before acknowledging.",
    "UNROUTABLE_COUNTRY": "Run akedly byo-sms countries and choose routable country codes; use ALL alone for catch-all coverage.",
    "SOURCE_COVERAGE_UNROUTABLE": "Update the source integration countries using akedly byo-sms countries, then clone again.",
    "INVALID_TEST_PHONE": "Supply --test-phone-number in international format or update the saved test destination.",
    "TEST_PHONE_OUT_OF_COVERAGE": "Choose a test number in the integration countries, or update its countries before testing.",
    "VODAFONE_TEST_GUARD_UNAVAILABLE": "No new test was sent. Retry with the same idempotencyKey; contact Akedly support if send protection remains unavailable.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_REQUIRED": "Supply --idempotency-key with a unique request key and reuse it after an uncertain response.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_INVALID": "Supply --idempotency-key with 1 to 255 characters.",
    "VODAFONE_ACCEPTED_RETEST_INVALID": "Supply --previous-test-key with the accepted test key before requesting another test.",
    "VODAFONE_ACCEPTED_RETEST_REQUIRED": "Check akedly byo-sms get <id>; to send again after an accepted result, supply --previous-test-key and a new --idempotency-key with --yes.",
    "VODAFONE_NEW_TEST_CONFIRMATION_REQUIRED": "Check the previous result with akedly byo-sms get <id>; --allow-new-after-unknown with a new --idempotency-key and --yes can send another message.",
    "VODAFONE_NEW_TEST_IN_PROGRESS": "Wait for the current Vodafone test result; inspect akedly byo-sms get <id> before starting another attempt.",
    "BYO_SMS_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "VODAFONE_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "BYO_SMS_STEPS_INVALID": "Check the steps JSON and secret names; secret and extraction names use letters, numbers and underscore."
  },
  "commandHints": {},
  "hintPrecedence": [
    "explicit handler hint",
    "command-specific hint",
    "global code hint",
    "HTTP 429 fallback",
    "generic command-help fallback"
  ],
  "exitCodes": {
    "USAGE": 64,
    "CONFIRMATION_REQUIRED": 65,
    "LOGIN_REQUIRED": 66,
    "PERMISSION_DENIED": 67,
    "ORG_ADMIN_REQUIRED": 67,
    "OWNER_REQUIRED": 67,
    "CLI_READ_ONLY": 67,
    "IMPERSONATION_BLOCKED": 67,
    "SELF_IDENTITY_REQUIRED": 67,
    "CLI_LOGIN_OWNER_PROTECTED": 67,
    "NEEDS_BROWSER": 68,
    "SETUP_REQUIRED": 68,
    "CLI_RATE_LIMITED": 69,
    "NOT_AVAILABLE_ON_SERVER": 70,
    "CLI_UPGRADE_REQUIRED": 70,
    "CLI_DISABLED": 70
  }
}

{
  "flagTokenEncoding": {
    "booleans": "A boolean schema describes switch presence: write --flag with no value.",
    "valuedFlags": "A string schema describes the single argv token after --flag or after --flag=; numeric token schemas parse as decimal strings and validation.parsedValueSchema documents the converted number.",
    "csvFlags": "A list schema describes one comma-separated argv token, not multiple shell arguments.",
    "projection": "--fields is one comma-separated argv token of safe dot paths and changes returned output only."
  },
  "positionals": [],
  "flags": [
    {
      "name": "help",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "output",
      "schema": {
        "type": "string",
        "enum": [
          "json",
          "human"
        ]
      },
      "required": false
    },
    {
      "name": "fields",
      "schema": {
        "type": "string",
        "pattern": "^(?!.*(?:^|[.,])(?:__proto__|constructor|prototype)(?:[.,]|$))(?!,)(?!.*,,)(?!.*,$)[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*(?:,[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*)*$"
      },
      "required": false,
      "validation": {
        "syntax": "Comma-separated safe dot paths; reserved prototype keys are refused."
      }
    },
    {
      "name": "ksa",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "pipeline-id",
      "schema": {
        "type": "string",
        "pattern": "^[a-fA-F0-9]{24}$"
      },
      "required": true,
      "wire": [
        {
          "path": "pipelineID",
          "transform": "identity",
          "role": "body",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "validation": {
        "syntax": "24-digit hexadecimal object ID."
      }
    },
    {
      "name": "phone-number",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "phone",
          "transform": "identity",
          "role": "body",
          "input": "phone-number",
          "contributors": [
            "phone-number"
          ]
        }
      ]
    },
    {
      "name": "dry-run",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "dry-run",
        "validationBoundary": "No separately curated semantic file schema is available; use the local reader contract and command help to understand additional handler or server validation."
      },
      "wire": [
        {
          "role": "local",
          "input": "dry-run",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "dry-run",
          "contributors": [
            "dry-run"
          ]
        }
      ]
    }
  ],
  "files": [],
  "wire": {
    "method": "POST",
    "route": "/utilities/routing-preview",
    "query": {},
    "body": {
      "pipeline-id": [
        {
          "path": "pipelineID",
          "transform": "identity",
          "role": "body",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "phone-number": [
        {
          "path": "phone",
          "transform": "identity",
          "role": "body",
          "input": "phone-number",
          "contributors": [
            "phone-number"
          ]
        }
      ]
    },
    "ownerParams": []
  }
}

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "status": {
        "const": "success"
      },
      "data": {
        "type": "object",
        "properties": {
          "recipient": {
            "type": "string"
          },
          "route": {
            "type": "boolean"
          },
          "reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "country": {
            "type": [
              "string",
              "null"
            ]
          },
          "providerKey": {
            "type": [
              "string",
              "null"
            ]
          },
          "integrationID": {
            "type": [
              "string",
              "null"
            ]
          },
          "requiresDurableIdentity": {
            "type": "boolean"
          },
          "code": {
            "type": [
              "string",
              "null"
            ]
          },
          "message": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "recipient",
          "route",
          "reason",
          "country",
          "providerKey",
          "integrationID",
          "requiresDurableIdentity",
          "code",
          "message"
        ],
        "additionalProperties": true
      }
    },
    "required": [
      "status",
      "data"
    ],
    "additionalProperties": true
  },
  "variants": [],
  "fieldSelection": {
    "flag": "fields",
    "behavior": "Selects comma-separated dot paths from the response root; for root arrays, paths apply to each element. Missing paths are omitted.",
    "sensitiveData": null
  }
}

[
  {
    "title": "Synthetic representative response",
    "value": {
      "status": "success",
      "data": {
        "recipient": "+201234567890",
        "route": false,
        "reason": "no_active_integration",
        "country": "US",
        "providerKey": null,
        "integrationID": null,
        "requiresDurableIdentity": false,
        "code": "NO_ACTIVE_INTEGRATION",
        "message": "No active BYO-SMS integration covers this destination."
      }
    }
  }
]

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": [
      "status",
      "code",
      "message",
      "httpStatus",
      "hint"
    ],
    "properties": {
      "status": {
        "const": "error"
      },
      "code": {
        "type": "string"
      },
      "message": {
        "type": "string"
      },
      "httpStatus": {
        "type": [
          "integer",
          "null"
        ]
      },
      "details": {
        "anyOf": [
          {
            "type": "object",
            "minProperties": 1
          },
          {
            "type": "array",
            "minItems": 1
          }
        ]
      },
      "hint": {
        "type": "string"
      }
    },
    "additionalProperties": false
  },
  "globalHints": {
    "TOTP_DELETE_RECONCILIATION_PENDING": "Any Pending request blocks deletion, including one just opened; Failed requests can block too. Ordinary unverified, unbilled requests expire about five minutes after creation and normally become Expired on the next five-minute reconciliation run, within about ten minutes of creation; job delays or billing/counter recovery can extend that wait. Check the stored status in akedly totp history list; computed isExpired alone does not unblock deletion. Ask Akedly support if a request stays Pending or Failed beyond that normal window, or is Verified and still blocks.",
    "CLI_SECRET_ALREADY_DELIVERED": "Run akedly login again.",
    "CLI_LOGIN_INVALID": "Run akedly login.",
    "PERMISSION_DENIED": "If details.permission names a permission, ask an organization admin to grant it to your role. Otherwise read the server message: an organization admin cannot clear refusals such as an inactive or unverified account, an Akedly-managed global role, a reported-invitation pause or missing enterprise entitlement; follow the message or contact Akedly support. If the message says BYO-SMS is not enabled for this account, the account needs BYO-SMS entitlement and granular pricing; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and only Akedly can change either.",
    "ORG_ADMIN_REQUIRED": "If the message asks for an active organization session, run akedly login and approve it with the intended organization active in the dashboard. If it says organization admin access is required, ask an organization admin for access or to run the command. Role changes can take up to 60 seconds to apply.",
    "OWNER_REQUIRED": "Only the account owner can do this; an organization admin is not necessarily the owner. Ask the owner to run it from their own login. For seats, organization admins can read akedly seats visibility; akedly seats status is owner-only.",
    "LOGIN_REQUIRED": "Run akedly login. If you supplied a credential, check --ksa or AKEDLY_REGION.",
    "CLI_DISABLED": "Customer CLI access is turned off on this Akedly server. Try again later or contact Akedly support.",
    "CLI_IDENTITY_UNAVAILABLE": "Akedly could not confirm your login right now. Wait a minute and try again.",
    "CLI_LOGIN_INDEX_UNAVAILABLE": "CLI login is temporarily unavailable on this server. Try again later or contact Akedly support.",
    "WABA_PHONE_CHECK_UNAVAILABLE": "Meta did not confirm the number. Wait a few minutes, then run the command again.",
    "CLI_UPGRADE_REQUIRED": "Install the latest @akedly/cli.",
    "NOT_AVAILABLE_ON_SERVER": "Check the selected region or ask an operator to deploy CLI support.",
    "CLI_RATE_LIMITED": "Wait before trying again.",
    "CLI_LOGIN_DENIED": "Run akedly login again and approve the new code.",
    "CLI_LOGIN_REQUEST_EXPIRED": "Run akedly login again.",
    "LOGIN_TIMEOUT": "Run akedly login again and approve before the timeout.",
    "CLI_READ_ONLY": "This login is read-only. Run akedly login and choose Full access.",
    "CLI_LOGIN_LIMIT_REACHED": "Run akedly cli-logins list, then akedly cli-logins end <id>",
    "CLI_LOGIN_NOT_FOUND": "Run akedly cli-logins list and check the login id.",
    "CLI_LOGIN_OWNER_PROTECTED": "Ask the account owner to end this login.",
    "IMPERSONATION_BLOCKED": "This login was approved by Akedly staff and can't do this. Run akedly login and approve it in your own dashboard session.",
    "SELF_IDENTITY_REQUIRED": "Personal settings need your own login. Run akedly login and approve it in your own dashboard session.",
    "MEMBER_NOT_FOUND": "Check the email with akedly team members list; a pending invitation is not a member yet.",
    "MEMBER_AMBIGUOUS": "Pass the memberId from akedly team members list instead of the email.",
    "API_KEY_ACTIVE_CAP_REACHED": "Revoke an unused key before creating another.",
    "API_KEY_ISSUANCE_DISABLED": "Ask an operator to enable API-key issuance.",
    "API_KEY_VERSION_CONFLICT": "List the keys and retry the edit with the current version.",
    "API_KEY_BUDGET_CONFIRMATION_REQUIRED": "Review the reduction and pass --confirm-budget-reduction.",
    "API_KEY_ISSUE_RECOVERY_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_TRANSITION_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_ISSUE_IDEMPOTENCY_CONFLICT": "Use a new idempotency key for different issue details.",
    "API_KEY_SCOPE_NOT_ACTIVE": "Ask an operator to enable API-key scope editing.",
    "API_KEY_BUDGET_NOT_ACTIVE": "Ask an operator to enable API-key budget editing.",
    "API_KEY_NOT_FOUND": "Run akedly api-keys list and check the id.",
    "API_KEY_BUDGET_RACE": "List the keys and retry.",
    "V1_CREATION_NOT_ENTITLED": "V1 pipelines are not available to this account. Omit --api-version to create a V1.2 pipeline.",
    "SECRET_SUFFIX_REQUIRED": "Pass exactly one of --secret-file <saved path> or --secret-suffix <last 4 characters>.",
    "SECRET_SUFFIX_MISMATCH": "Reveal the current secret to --secret-file <new path> with akedly pipelines webhook-secret reveal <id> for webhook secrets, or akedly utilities pipelines signing-secret reveal <id> for utility request-signing secrets, then acknowledge with exactly one of --secret-file <that path> or --secret-suffix <last 4 characters>.",
    "CHANNEL_CHOICE_NOT_AVAILABLE": "Nothing in this request was saved. Each value in details.blockers names what is missing: not_entitled means Channel Choice isn't enabled on the account yet; legacy_pricing means the account needs granular pricing; not_pay_per_message means the pipeline is not billed per message, because it is billed per successful verification or the account has no billing plan yet; account_excluded and global_switch_off mean Channel Choice isn't offered to this account right now. Only Akedly can change these, so contact Akedly. utility_pipeline means utility pipelines have no Channel Choice. Resend any other changes without the Channel Choice flags.",
    "VERIFICATION_METHOD_UNAVAILABLE": "Nothing was saved. details.method is the word you typed, or the method's id if the method became unavailable after the CLI checked; running the command again rechecks the list and names the word. Remove that method from --verification-methods and retry, or contact Akedly if you expected it to be available.",
    "VERIFICATION_METHODS_REQUIRED": "A pipeline that has verification methods must keep at least one. Send the methods to keep instead of an empty list, for example akedly pipelines update <id> --verification-methods whatsapp,sms --yes.",
    "SETTING_NOT_FOR_THIS_PIPELINE": "Nothing in this request was saved. details.setting names the setting and details.useInstead what to use instead. For rate limits and the circuit breaker, reason api-version means this is a V1 or V2 pipeline, where they belong to a widget instead, so useInstead is widgets update. A widget must be attached to this pipeline first. Find attached widgets with akedly widgets list-filtered --pipeline-id <pipelineId>, then inspect the intended widget with akedly widgets get <widgetId>, using its 24-hex _id. This listing excludes inactive widgets by default. Also run akedly widgets list-filtered --pipeline-id <pipelineId> --status inactive before concluding that no widget is attached. Change its limits with akedly widgets update <widgetId> --rate-limits-file <file> --yes; use the widget file shape, not the pipeline file shape. Set its breaker with akedly widgets update <widgetId> --circuit-breaker on --yes (or off), and use --circuit-breaker-file <file> for widget thresholds and suspension durations; pipeline --circuit-breaker-sensitivity does not apply to widgets. If no widget is attached, create one with akedly widgets create --name <name> --pipeline-id <pipelineId> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <pipelineId> --yes. V2 attachment requires both callback URLs; V1 attachment requires entitlement. pipelines update now routes shared rate-limit, breaker and PoW flags to every attached widget on V1/V2. V1.2-only controls remain refused on V1/V2. Use the appropriate file shape for the resulting API version. For the Channel Choice widget experience, reason api-version means it needs a V2 pipeline, so create one with akedly pipelines create --name <name> --api-version v2 --redirect-url <url> --webhook-url <url> --secret-file <new path>, then attach a widget to it; reason no-widget means it needs a widget attached to this V2 pipeline, so create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <id> --yes, then retry. Resend any other changes without that flag.",
    "PIPELINE_CHANGED": "Another change landed first, so nothing was saved. Run the same command again; if you changed rate limits or destination countries, it reads the pipeline again first and merges your change onto the new version. Run akedly pipelines get <id> to see what changed.",
    "RATE_LIMIT_INVALID": "Check details.field and any details.errors. Use whole numbers above zero in the expected JSON object shape. Pipeline --rate-limits-file uses perPhoneNumber, perIpAddress and perPipeline; widget --rate-limits-file uses widgetAttempts and otpRequests, each with perPhoneNumber, perDevice and perWidget. Each takes perMinute, perHour and perDay. Widget --circuit-breaker-file uses floodThresholds and suspensionSeconds; durations are whole seconds. Correct the named field and rerun the command.",
    "EXPECTED_UPDATED_AT_INVALID": "The CLI reads the revision automatically. Run the command again to read the current settings; if this continues, check that the CLI and server are up to date and contact Akedly support. Do not invent a revision or remove the conflict check.",
    "DESTINATION_COUNTRIES_MODE_REQUIRED": "Nothing in this request was saved. A changed country list under mode all would be discarded: pass --destination-countries-mode only-selected or all-except-selected with --destination-countries, or leave the list out to keep every country open. --destination-countries-mode all on its own clears the list.",
    "NOT_ENOUGH_TRAFFIC": "Keep the current limits for now. Recommended limits need at least 100 analysed requests and better than low confidence; try again after more real traffic or with a longer --period such as last-quarter, or set limits yourself with --rate-limits-file.",
    "INVALID_COUNTRY_POLICY": "Nothing in this request was saved. Use two-letter country codes such as EG,SA with --destination-countries and a mode of all, only-selected or all-except-selected; the message names the problem.",
    "OTP_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "TURNSTILE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_NOT_AVAILABLE": "Nothing in this request was saved. Act on details.reason: not-offered means Cluster Gate is not offered for this pipeline right now, for example on a utility pipeline or in the KSA region; attaching a widget will not help on a V1.2 pipeline, because V1.2 pipelines cannot be attached to widgets; drop the Cluster Gate flags and resend any other changes; no-widget means Cluster Gate applies here only through a widget and none is attached, so attach an existing widget with akedly widgets update <widgetId> --pipeline-id <id> --yes, or create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, then retry; the pipeline must first be active, with both callback URLs and a verification method, and WIDGET_PIPELINE_NOT_READY says what is missing; on-create comes only from raw API requests that set Cluster Gate while creating a pipeline: create the pipeline first, then set Cluster Gate with akedly pipelines update <id> --cluster-gate on --cluster-gate-position balanced --yes; check-failed means availability could not be checked, so retry later; intent-missing comes only from raw API requests that omit clusterGateIntent: true.",
    "SECRET_ALREADY_ACKNOWLEDGED": "The secret was already acknowledged and cannot be shown again. Use the saved copy from pipeline creation (webhook secrets) or from reveal, for example the file written with --secret-file. Only if that copy is lost, use akedly pipelines webhook-secret regenerate <id> --yes --secret-file <new path> for webhook secrets, or akedly utilities pipelines signing-secret regenerate <id> --yes --secret-file <new path> for utility request-signing secrets. Regenerating stops the current secret immediately; deploy the new secret before using signed requests or accepting signed webhooks.",
    "WIDGET_PIPELINE_NOT_READY": "Fix each item in details.missing with akedly pipelines update <pipelineId> --status active --redirect-url <url> --webhook-url <url> --verification-methods whatsapp,sms,email --yes, passing only the flags for the missing items, then retry.",
    "WIDGET_IDENTITY_INDEX_UNAVAILABLE": "Widget identity indexes are unavailable. Retry later or contact Akedly support.",
    "INCOMPLETE_DATE_RANGE": "Supply both --start-date and --end-date, or neither.",
    "DATE_RANGE_TOO_LARGE": "Choose a date range of at most 30 days, counted as the command help describes.",
    "INVALID_DATE_RANGE": "Check both date bounds and their order.",
    "INVALID_DATE": "Use valid ISO dates for the requested range.",
    "NEEDS_BROWSER": "Turn Turnstile off for the pipeline in the dashboard, or run akedly pipelines dev-mode set <pipelineId> --dev-mode on --bypass-turnstile on --bypass-pow on --yes.",
    "SETUP_REQUIRED": "Finish phone setup on the Personal Notifications page of your Akedly dashboard, then retry.",
    "INVALID_API_KEY": "Check the API key: akedly api-keys list, or create one with akedly api-keys create --label <name> --save --yes.",
    "API_KEY_SCOPE_DENIED": "This API key is scoped to other pipelines; use a key that includes this pipeline.",
    "MAX_ATTEMPTS_EXCEEDED": "Too many wrong codes; send a new OTP.",
    "ALREADY_VERIFIED": "This request is already verified; check it with akedly transactions status.",
    "INVALID_OTP": "Check the code and retry; attempts are limited.",
    "PIPELINE_INACTIVE": "Run akedly pipelines update <pipelineId> --status active --yes, then retry.",
    "POW_CHALLENGE_EXPIRED": "Run the command again; it fetches a fresh challenge.",
    "POW_CHALLENGE_REPLAYED": "Run the command again; it fetches a fresh challenge.",
    "POW_DIFFICULTY_STALE": "Run the command again; it fetches a fresh challenge.",
    "STATUS_LOOKUP_RATE_LIMITED": "Wait for the retryAfter seconds in details, then retry; each lookup counts against the 300 ids per minute limit.",
    "TRANSACTION_EXPIRED": "This code or request has expired; send a new one.",
    "USE_V1_2_ENDPOINT": "This pipeline is V1.2. Use akedly otp v1.2 send.",
    "SIGNATURE_EXPIRED": "This machine's clock differs from the server's by more than 60 seconds. Fix the clock and run the command again; it signs a fresh request each time.",
    "WIDGET_USER_MISMATCH": "This API key belongs to a different account than the widget. Use a key from the widget owner's account.",
    "WEBHOOK_SIGNATURE_INVALID": "Use the pipeline's current whsec_ secret (regenerating invalidates the old one), the exact raw body bytes the server received (no re-serialising, no trailing newline), and the svix-id, svix-timestamp and svix-signature headers.",
    "WAIT_EXPIRED": "The request expired before it was verified; it cannot complete. Start a new one (otp v2 attempt, otp v1.2 send or otp v1 create).",
    "WAIT_FAILED": "The verification failed and cannot complete; start a new one.",
    "WAIT_TIMEOUT": "The wait ended; the verification may still complete. Check it with akedly transactions status. Resume with akedly transactions status --attempt-id <id> --wait (or --transaction-id <id> --wait).",
    "WEBHOOK_TIMESTAMP_STALE": "The webhook timestamp is outside the allowed window. Check this machine's clock, or pass --at <unix seconds> to check an older delivery, or --tolerance-seconds <seconds>.",
    "WEBHOOK_HEADERS_MISSING": "Pass a headers JSON file with the svix-id, svix-timestamp and svix-signature headers exactly as received.",
    "NO_USABLE_API_KEY": "This account has no usable API key for this pipeline. Create one with akedly api-keys create --label <name> --save --yes; a key scoped to selected pipelines must include this pipeline.",
    "INVALID_API_VERSION": "This command does not support this pipeline's API version. Check it with akedly pipelines get <id> and use the matching command for that version.",
    "DOCTOR_FAILED": "Fix the failed checks in details.checks, then run akedly doctor again.",
    "PAGINATION_LIMIT": "Narrow the filters, for example a date range or status, or raise --limit (maximum 100), then run again.",
    "PAGINATION_STALLED": "The list changed while it was being read, or the server stopped advancing. Run the command again.",
    "REPORT_NOT_FOUND": "Run akedly reports list and check the reportId.",
    "DAILY_LIMIT_REACHED": "Wait until an earlier successful, sent or in-flight report generation leaves the rolling 24-hour window; for example, a generation at 14:00 stops counting after 14:00 the next day. This limit covers the whole account, including dashboard and teammate generations.",
    "REPORT_IN_PROGRESS": "A report is already generating for this account; dashboard and teammate generations share the same slot. Run akedly reports list before trying again.",
    "TEMPLATE_DUPLICATE": "Run akedly whatsapp otp-templates list; recover missing languages with update --add-languages instead of adding the same template again.",
    "TEMPLATE_LIMIT_REACHED": "Archive an unused template with akedly whatsapp otp-templates delete <id> --yes before adding another; the limit is 20 per WABA.",
    "TEMPLATE_PROVISIONING_FAILED": "The template or changes are saved. Run akedly whatsapp otp-templates list, then update <id> --add-languages <failed languages> rather than creating again.",
    "TEMPLATE_WABA_REQUIRED": "Connect an active own WhatsApp Business Account in the dashboard before managing OTP templates; check akedly whatsapp status.",
    "TEMPLATE_WABA_CHANGED": "This template belongs to the previous WABA. Add it again for the currently connected account.",
    "COUNTRY_CATALOG_UNAVAILABLE": "The country catalog is temporarily unavailable. Try again later.",
    "NOT_A_UTILITY_PIPELINE": "Choose an owned utility pipeline from akedly pipelines list, or create one with akedly pipelines create --product utility --name <name>.",
    "TEST_RATE_LIMITED": "Wait for Retry-After before testing again; account, recipient or replay safety limits may apply. Reuse the same Vodafone idempotencyKey when checking an existing attempt.",
    "EGRESS_FINGERPRINT_STALE": "The sending address changed. Run akedly byo-sms vodafone readiness, check the new address list, then acknowledge again with the new fingerprint.",
    "VODAFONE_EGRESS_NOT_READY": "Run akedly byo-sms vodafone readiness; ask Akedly support to verify the outbound addresses before acknowledging.",
    "UNROUTABLE_COUNTRY": "Run akedly byo-sms countries and choose routable country codes; use ALL alone for catch-all coverage.",
    "SOURCE_COVERAGE_UNROUTABLE": "Update the source integration countries using akedly byo-sms countries, then clone again.",
    "INVALID_TEST_PHONE": "Supply --test-phone-number in international format or update the saved test destination.",
    "TEST_PHONE_OUT_OF_COVERAGE": "Choose a test number in the integration countries, or update its countries before testing.",
    "VODAFONE_TEST_GUARD_UNAVAILABLE": "No new test was sent. Retry with the same idempotencyKey; contact Akedly support if send protection remains unavailable.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_REQUIRED": "Supply --idempotency-key with a unique request key and reuse it after an uncertain response.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_INVALID": "Supply --idempotency-key with 1 to 255 characters.",
    "VODAFONE_ACCEPTED_RETEST_INVALID": "Supply --previous-test-key with the accepted test key before requesting another test.",
    "VODAFONE_ACCEPTED_RETEST_REQUIRED": "Check akedly byo-sms get <id>; to send again after an accepted result, supply --previous-test-key and a new --idempotency-key with --yes.",
    "VODAFONE_NEW_TEST_CONFIRMATION_REQUIRED": "Check the previous result with akedly byo-sms get <id>; --allow-new-after-unknown with a new --idempotency-key and --yes can send another message.",
    "VODAFONE_NEW_TEST_IN_PROGRESS": "Wait for the current Vodafone test result; inspect akedly byo-sms get <id> before starting another attempt.",
    "BYO_SMS_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "VODAFONE_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "BYO_SMS_STEPS_INVALID": "Check the steps JSON and secret names; secret and extraction names use letters, numbers and underscore."
  },
  "commandHints": {
    "INVALID_PIPELINE": "Pass --pipeline-id with a 24-hex owned utility pipeline id.",
    "INVALID_PHONE": "Check --phone-number, or the saved account phone when it is omitted.",
    "NO_UTILITY_PIPELINE": "Run akedly pipelines create --product utility --name <name> to create a utility pipeline, then akedly pipelines update <id> --status active --yes; or choose an owned, active utility pipeline from akedly pipelines list."
  },
  "hintPrecedence": [
    "explicit handler hint",
    "command-specific hint",
    "global code hint",
    "HTTP 429 fallback",
    "generic command-help fallback"
  ],
  "exitCodes": {
    "USAGE": 64,
    "CONFIRMATION_REQUIRED": 65,
    "LOGIN_REQUIRED": 66,
    "PERMISSION_DENIED": 67,
    "ORG_ADMIN_REQUIRED": 67,
    "OWNER_REQUIRED": 67,
    "CLI_READ_ONLY": 67,
    "IMPERSONATION_BLOCKED": 67,
    "SELF_IDENTITY_REQUIRED": 67,
    "CLI_LOGIN_OWNER_PROTECTED": 67,
    "NEEDS_BROWSER": 68,
    "SETUP_REQUIRED": 68,
    "CLI_RATE_LIMITED": 69,
    "NOT_AVAILABLE_ON_SERVER": 70,
    "CLI_UPGRADE_REQUIRED": 70,
    "CLI_DISABLED": 70
  }
}

{
  "flagTokenEncoding": {
    "booleans": "A boolean schema describes switch presence: write --flag with no value.",
    "valuedFlags": "A string schema describes the single argv token after --flag or after --flag=; numeric token schemas parse as decimal strings and validation.parsedValueSchema documents the converted number.",
    "csvFlags": "A list schema describes one comma-separated argv token, not multiple shell arguments.",
    "projection": "--fields is one comma-separated argv token of safe dot paths and changes returned output only."
  },
  "positionals": [
    {
      "name": "id",
      "type": "string",
      "required": true,
      "pattern": "^[a-fA-F0-9]{24}$",
      "validation": "Use an owned utility pipeline id from akedly pipelines list.",
      "mapsToRouteParameter": "id",
      "routeParameterValidation": "A route parameter cannot be . or .., including percent-encoded forms."
    }
  ],
  "flags": [
    {
      "name": "help",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "output",
      "schema": {
        "type": "string",
        "enum": [
          "json",
          "human"
        ]
      },
      "required": false
    },
    {
      "name": "fields",
      "schema": {
        "type": "string",
        "pattern": "^(?!.*(?:^|[.,])(?:__proto__|constructor|prototype)(?:[.,]|$))(?!,)(?!.*,,)(?!.*,$)[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*(?:,[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*)*$"
      },
      "required": false,
      "validation": {
        "syntax": "Comma-separated safe dot paths; reserved prototype keys are refused."
      }
    },
    {
      "name": "ksa",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "file",
      "schema": {
        "type": "string"
      },
      "required": true,
      "input": {
        "role": "input-file",
        "contract": "utility-channels",
        "requestTargets": [
          {
            "role": "body",
            "path": "$",
            "transform": "json-fields",
            "fileContract": "utility-channels"
          }
        ],
        "schema": {
          "$schema": "https://json-schema.org/draft/2020-12/schema",
          "title": "Utilities pipeline channel settings patch",
          "description": "Sparse object containing at least one recognized field. channels can contain whatsapp/sms booleans; channelOrder accepts whatsapp and/or sms; allowedCountries accepts two-letter country codes; smsFallback is boolean. Server requires at least one channel enabled after the patch and applies eligibility checks when enabling channels/fallback.",
          "type": "object",
          "properties": {
            "channels": {
              "type": "object",
              "properties": {
                "whatsapp": {
                  "type": "boolean"
                },
                "sms": {
                  "type": "boolean"
                }
              },
              "additionalProperties": false
            },
            "channelOrder": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "whatsapp",
                  "sms"
                ]
              }
            },
            "allowedCountries": {
              "type": "array",
              "items": {
                "type": "string",
                "pattern": "^[A-Za-z]{2}$"
              }
            },
            "smsFallback": {
              "type": "boolean"
            }
          },
          "minProperties": 1,
          "additionalProperties": false
        },
        "localReaderSchema": {
          "$schema": "https://json-schema.org/draft/2020-12/schema",
          "type": "object",
          "properties": {
            "channels": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                },
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                },
                {
                  "type": "object",
                  "additionalProperties": true
                },
                {
                  "type": "array",
                  "items": true
                }
              ]
            },
            "channelOrder": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                },
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                },
                {
                  "type": "object",
                  "additionalProperties": true
                },
                {
                  "type": "array",
                  "items": true
                }
              ]
            },
            "allowedCountries": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                },
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                },
                {
                  "type": "object",
                  "additionalProperties": true
                },
                {
                  "type": "array",
                  "items": true
                }
              ]
            },
            "smsFallback": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                },
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                },
                {
                  "type": "object",
                  "additionalProperties": true
                },
                {
                  "type": "array",
                  "items": true
                }
              ]
            }
          },
          "additionalProperties": false
        },
        "fileContract": {
          "format": "json-object",
          "maxBytes": 65536,
          "regularFile": true,
          "fields": [
            "channels",
            "channelOrder",
            "allowedCountries",
            "smsFallback"
          ],
          "reader": "utilities.js:pipelines channels set",
          "type": "json-object",
          "exclusive": false,
          "mode": null,
          "trim": false,
          "writer": null,
          "minBytes": 0,
          "detectChanges": true,
          "fieldMappings": {
            "channels": {
              "path": "channels",
              "transform": "identity"
            },
            "channelOrder": {
              "path": "channelOrder",
              "transform": "identity"
            },
            "allowedCountries": {
              "path": "allowedCountries",
              "transform": "identity"
            },
            "smsFallback": {
              "path": "smsFallback",
              "transform": "identity"
            }
          }
        },
        "semanticSchema": {
          "$schema": "https://json-schema.org/draft/2020-12/schema",
          "title": "Utilities pipeline channel settings patch",
          "description": "Sparse object containing at least one recognized field. channels can contain whatsapp/sms booleans; channelOrder accepts whatsapp and/or sms; allowedCountries accepts two-letter country codes; smsFallback is boolean. Server requires at least one channel enabled after the patch and applies eligibility checks when enabling channels/fallback.",
          "type": "object",
          "properties": {
            "channels": {
              "type": "object",
              "properties": {
                "whatsapp": {
                  "type": "boolean"
                },
                "sms": {
                  "type": "boolean"
                }
              },
              "additionalProperties": false
            },
            "channelOrder": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "whatsapp",
                  "sms"
                ]
              }
            },
            "allowedCountries": {
              "type": "array",
              "items": {
                "type": "string",
                "pattern": "^[A-Za-z]{2}$"
              }
            },
            "smsFallback": {
              "type": "boolean"
            }
          },
          "minProperties": 1,
          "additionalProperties": false
        },
        "validationBoundary": "semanticSchema describes curated command file-content constraints; localReaderSchema describes file-reader constraints. Read command help and schema descriptions for additional handler or server validation."
      },
      "wire": [
        {
          "role": "local",
          "input": "file",
          "inputRole": "input-file",
          "transform": "identity",
          "fileContract": "utility-channels",
          "contributors": [
            "file"
          ]
        },
        {
          "role": "body",
          "path": "allowedCountries",
          "transform": "identity",
          "fileContract": "utility-channels",
          "input": "file",
          "contributors": [
            "file"
          ],
          "fileKey": "allowedCountries",
          "inputTransform": "json-fields"
        },
        {
          "role": "body",
          "path": "channelOrder",
          "transform": "identity",
          "fileContract": "utility-channels",
          "input": "file",
          "contributors": [
            "file"
          ],
          "fileKey": "channelOrder",
          "inputTransform": "json-fields"
        },
        {
          "role": "body",
          "path": "channels",
          "transform": "identity",
          "fileContract": "utility-channels",
          "input": "file",
          "contributors": [
            "file"
          ],
          "fileKey": "channels",
          "inputTransform": "json-fields"
        },
        {
          "role": "body",
          "path": "smsFallback",
          "transform": "identity",
          "fileContract": "utility-channels",
          "input": "file",
          "contributors": [
            "file"
          ],
          "fileKey": "smsFallback",
          "inputTransform": "json-fields"
        }
      ]
    },
    {
      "name": "dry-run",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "dry-run",
        "validationBoundary": "No separately curated semantic file schema is available; use the local reader contract and command help to understand additional handler or server validation."
      },
      "wire": [
        {
          "role": "local",
          "input": "dry-run",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "dry-run",
          "contributors": [
            "dry-run"
          ]
        }
      ]
    }
  ],
  "files": [
    {
      "name": "utility-channels",
      "contract": {
        "format": "json-object",
        "maxBytes": 65536,
        "regularFile": true,
        "fields": [
          "channels",
          "channelOrder",
          "allowedCountries",
          "smsFallback"
        ],
        "reader": "utilities.js:pipelines channels set",
        "type": "json-object",
        "exclusive": false,
        "mode": null,
        "trim": false,
        "writer": null,
        "minBytes": 0,
        "detectChanges": true,
        "fieldMappings": {
          "channels": {
            "path": "channels",
            "transform": "identity"
          },
          "channelOrder": {
            "path": "channelOrder",
            "transform": "identity"
          },
          "allowedCountries": {
            "path": "allowedCountries",
            "transform": "identity"
          },
          "smsFallback": {
            "path": "smsFallback",
            "transform": "identity"
          }
        }
      },
      "schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": {
          "channels": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "array",
                "items": true
              }
            ]
          },
          "channelOrder": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "array",
                "items": true
              }
            ]
          },
          "allowedCountries": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "array",
                "items": true
              }
            ]
          },
          "smsFallback": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "array",
                "items": true
              }
            ]
          }
        },
        "additionalProperties": false
      },
      "uses": [
        {
          "flag": "file",
          "role": "input-file",
          "purpose": null,
          "semanticSchema": {
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "title": "Utilities pipeline channel settings patch",
            "description": "Sparse object containing at least one recognized field. channels can contain whatsapp/sms booleans; channelOrder accepts whatsapp and/or sms; allowedCountries accepts two-letter country codes; smsFallback is boolean. Server requires at least one channel enabled after the patch and applies eligibility checks when enabling channels/fallback.",
            "type": "object",
            "properties": {
              "channels": {
                "type": "object",
                "properties": {
                  "whatsapp": {
                    "type": "boolean"
                  },
                  "sms": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": false
              },
              "channelOrder": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "whatsapp",
                    "sms"
                  ]
                }
              },
              "allowedCountries": {
                "type": "array",
                "items": {
                  "type": "string",
                  "pattern": "^[A-Za-z]{2}$"
                }
              },
              "smsFallback": {
                "type": "boolean"
              }
            },
            "minProperties": 1,
            "additionalProperties": false
          }
        }
      ]
    }
  ],
  "wire": {
    "method": "PUT",
    "route": "/utilities/pipelines/:id/channels",
    "query": {},
    "body": {},
    "ownerParams": []
  }
}