Command reference

Utilities templates

Akedly CLI command reference: Utilities templates.

Build with AI agents

utilities templates library

find a Meta or Akedly-curated utility-template starting point before authoring.

When to use

find a Meta or Akedly-curated utility-template starting point before authoring.

How it works

Search the live library with language/search/topic and page with Meta paging.after; curated seeds repeat on every page and ignore topic.

Prerequisites

Authenticated account with utilities:read permission.

Expected outcome

Returns library results and availability; if Meta is unavailable curated seeds remain available.

Next steps

Copy/adapt a result, remove its server metadata, then lint a local file.

Usage

akedly utilities templates library

Inspect this command offline before preparing an operation:

akedly describe "utilities templates library" --output json

Flags

Flag	Type	Enum / range	Description
`--ksa`	boolean switch	—	Select the KSA deployment.
`--search`	text	—	Command-specific option; see the full command details below. Query parameter: search.
`--topic`	text	—	Command-specific option; see the full command details below. Query parameter: topic.
`--language`	enum	en \| ar	Command-specific option; see the full command details below. Query parameter: language.
`--after`	text	—	Command-specific option; see the full command details below. Query parameter: after.
`--limit`	integer	1 to 100	Command-specific option; see the full command details below. Query parameter: limit.
`--help`	boolean switch	—	Show offline command help.
`--output`	enum	json \| human	Select JSON or human output.
`--fields`	dot-paths	—	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: utilities:read.

Server request: GET /utilities/templates/library.

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

Browse the live Meta Template Library and Akedly curated seeds. --language defaults to en; --limit defaults to 100 (maximum 100). Pass data.paging.after as --after for the next Meta page. Curated seeds are returned again on every --after page and ignore --topic. There is no numeric --page or --all. If the live library is unavailable, libraryAvailable:false and curated seeds remain a successful response. Copy and adapt an entry before creating a template. Read-only logins are supported.

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 CLI scenario

find a Meta or Akedly-curated utility-template starting point before authoring.

akedly utilities templates library --language en --limit 10

Illustrative response (sensitive values omitted):

json

{
  "status": "success",
  "data": {
    "libraryAvailable": true,
    "meta": [
      {
        "id": "meta-library-example-1",
        "name": "order_update",
        "language": "en_US",
        "category": "UTILITY",
        "body": "Your order {{1}} is ready.",
        "body_params": [
          "order id"
        ],
        "body_param_types": [
          "text"
        ],
        "buttons": []
      }
    ],
    "curated": [
      {
        "id": "seed-order-confirmed-en",
        "name": "Order confirmed",
        "language": "en",
        "category": "UTILITY",
        "body": "Hi {{name}}, your order {{order_id}} is confirmed.",
        "variables": [
          {
            "name": "name",
            "example": "Sam"
          },
          {
            "name": "order_id",
            "example": "ORD-17"
          }
        ]
      }
    ],
    "paging": {
      "after": "cursor-example",
      "hasMore": true
    }
  }
}

Resource identifiers and records are fictional prerequisites, not claims that these resources exist.

Additional command forms

akedly utilities templates library

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.

json

{
  "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": "search",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "search",
          "transform": "identity",
          "role": "query",
          "input": "search",
          "contributors": [
            "search"
          ]
        }
      ]
    },
    {
      "name": "topic",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "topic",
          "transform": "identity",
          "role": "query",
          "input": "topic",
          "contributors": [
            "topic"
          ]
        }
      ]
    },
    {
      "name": "language",
      "schema": {
        "type": "string",
        "enum": [
          "en",
          "ar"
        ]
      },
      "required": false,
      "wire": [
        {
          "path": "language",
          "transform": "identity",
          "role": "query",
          "input": "language",
          "contributors": [
            "language"
          ]
        }
      ]
    },
    {
      "name": "after",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "after",
          "transform": "identity",
          "role": "query",
          "input": "after",
          "contributors": [
            "after"
          ]
        }
      ]
    },
    {
      "name": "limit",
      "schema": {
        "type": "string",
        "pattern": "^(?:\\+?0*(?:[1-9]|(?:1[0-9]|[2-8]\\d{1}|9[0-9])|100)(?:\\.0+)?)$"
      },
      "required": false,
      "wire": [
        {
          "path": "limit",
          "transform": "identity",
          "role": "query",
          "input": "limit",
          "contributors": [
            "limit"
          ]
        }
      ],
      "validation": {
        "syntax": "Decimal integer token.",
        "minimum": 1,
        "maximum": 100,
        "parsedValueSchema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100
        }
      }
    }
  ],
  "files": [],
  "wire": {
    "method": "GET",
    "route": "/utilities/templates/library",
    "query": {
      "search": [
        {
          "path": "search",
          "transform": "identity",
          "role": "query",
          "input": "search",
          "contributors": [
            "search"
          ]
        }
      ],
      "topic": [
        {
          "path": "topic",
          "transform": "identity",
          "role": "query",
          "input": "topic",
          "contributors": [
            "topic"
          ]
        }
      ],
      "language": [
        {
          "path": "language",
          "transform": "identity",
          "role": "query",
          "input": "language",
          "contributors": [
            "language"
          ]
        }
      ],
      "after": [
        {
          "path": "after",
          "transform": "identity",
          "role": "query",
          "input": "after",
          "contributors": [
            "after"
          ]
        }
      ],
      "limit": [
        {
          "path": "limit",
          "transform": "identity",
          "role": "query",
          "input": "limit",
          "contributors": [
            "limit"
          ]
        }
      ]
    },
    "body": {},
    "ownerParams": []
  }
}

Response contract

Response fields outside the modeled stable fields may be passed through from the server.

The API response envelope is preserved by the CLI; stable fields are modeled and other server fields remain extensible.

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "status": {
        "const": "success"
      },
      "data": {
        "type": "object",
        "properties": {
          "libraryAvailable": {
            "type": "boolean"
          },
          "meta": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "language": {
                  "type": "string"
                },
                "category": {
                  "type": "string"
                },
                "topic": {
                  "type": "string"
                },
                "usecase": {
                  "type": "string"
                },
                "industry": {
                  "type": "string"
                },
                "header": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "body": {
                  "type": "string"
                },
                "footer": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "body_params": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "body_param_types": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "buttons": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {},
                    "required": [],
                    "additionalProperties": true
                  }
                }
              },
              "required": [
                "id",
                "name",
                "language",
                "category",
                "body"
              ],
              "additionalProperties": true
            }
          },
          "curated": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "language": {
                  "type": "string"
                },
                "category": {
                  "type": "string"
                },
                "body": {
                  "type": "string"
                },
                "variables": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string"
                      },
                      "example": {
                        "type": [
                          "string",
                          "number",
                          "boolean"
                        ]
                      }
                    },
                    "required": [
                      "name",
                      "example"
                    ],
                    "additionalProperties": true
                  }
                }
              },
              "required": [
                "id",
                "name",
                "language",
                "category",
                "body",
                "variables"
              ],
              "additionalProperties": true
            }
          },
          "paging": {
            "type": "object",
            "properties": {
              "after": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "hasMore": {
                "type": "boolean"
              }
            },
            "required": [
              "after",
              "hasMore"
            ],
            "additionalProperties": true
          }
        },
        "required": [
          "libraryAvailable",
          "meta",
          "curated",
          "paging"
        ],
        "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
  }
}

json

{
  "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_QUERY": "Use text values for --search, --topic and --after.",
    "INVALID_LANGUAGE": "Choose --language en or ar."
  },
  "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
  }
}

Own recovery guidance

Code	Hint
INVALID_QUERY	Use text values for `--search`, `--topic` and `--after`.
INVALID_LANGUAGE	Choose `--language` en or ar.

Common error guidance.

utilities templates list

review owned utility-template statuses and locate a template before inspecting or changing it.

When to use

review owned utility-template statuses and locate a template before inspecting or changing it.

How it works

Filter by Akedly status/name and page through owned templates; offset pages can shift while records change.

Prerequisites

Authenticated account with utilities:read permission.

Expected outcome

Returns a page or all requested pages, with server pagination metadata.

Next steps

Use the returned _id with templates get; lint a proposed edit before update.

Usage

akedly utilities templates list

Inspect this command offline before preparing an operation:

akedly describe "utilities templates list" --output json

Flags

Flag	Type	Enum / range	Description
`--ksa`	boolean switch	—	Select the KSA deployment.
`--status`	text	—	Command-specific option; see the full command details below. Query parameter: status.
`--search`	text	—	Command-specific option; see the full command details below. Query parameter: search.
`--page`	integer	1 to unbounded	Command-specific option; see the full command details below. Query parameter: page.
`--limit`	integer	1 to 100	Command-specific option; see the full command details below. Query parameter: limit.
`--all`	boolean switch	—	Command-specific option; see the full command details below.
`--help`	boolean switch	—	Show offline command help.
`--output`	enum	json \| human	Select JSON or human output.
`--fields`	dot-paths	—	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: utilities:read.

Server request: GET /utilities/templates.

Shared server-guard guidance.

Consent

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

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

List your utility templates. --status passes through as the Akedly status filter. Values are draft, pending_review, approved and rejected (akedlyStatus, not metaStatus); any other value returns no templates. --search matches the name (the server trims it and limits it to 100 characters). Page defaults to 1 and limit to 20; --all defaults omitted limit to 100 and uses the shared Pagination rules. Offset paging is not a snapshot and can skip rows during concurrent changes. Read-only logins are supported.

Pagination rules.

Worked examples

Synthetic CLI scenario

review owned utility-template statuses and locate a template before inspecting or changing it.

akedly utilities templates list --status draft --page 1

Illustrative response (sensitive values omitted):

json

{
  "status": "success",
  "data": {
    "templates": [
      {
        "_id": "64b000000000000000000002",
        "name": "Order update",
        "language": "en",
        "body": "Your order {{1}} is ready.",
        "variables": [
          {
            "name": "1",
            "example": "ORD-17"
          }
        ],
        "usableOn": {
          "whatsapp": true,
          "sms": false
        },
        "parameterFormat": "POSITIONAL",
        "akedlyStatus": "draft",
        "metaStatus": null,
        "metaTemplateId": null,
        "metaCategory": null,
        "suggestedCategory": null,
        "whatsappSubmitError": null,
        "whatsappResubmittable": false,
        "rejectionReason": null,
        "sourceLibraryName": null,
        "createdAt": "2050-01-02T03:04:05.000Z",
        "updatedAt": "2050-01-02T03:04:05.000Z"
      }
    ],
    "pagination": {
      "currentPage": 1,
      "totalPages": 1,
      "totalCount": 1,
      "limit": 20
    }
  }
}

Resource identifiers and records are fictional prerequisites, not claims that these resources exist.

Additional command forms

akedly utilities templates list

Input and file contracts

json

{
  "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": "status",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "status",
          "transform": "identity",
          "role": "query",
          "input": "status",
          "contributors": [
            "status"
          ]
        }
      ]
    },
    {
      "name": "search",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "search",
          "transform": "identity",
          "role": "query",
          "input": "search",
          "contributors": [
            "search"
          ]
        }
      ]
    },
    {
      "name": "page",
      "schema": {
        "type": "string",
        "pattern": "^(?:\\+?0*(?:[1-9]\\d*)(?:\\.0+)?)$"
      },
      "required": false,
      "wire": [
        {
          "path": "page",
          "transform": "identity",
          "role": "query",
          "input": "page",
          "contributors": [
            "page"
          ]
        }
      ],
      "validation": {
        "syntax": "Decimal integer token.",
        "minimum": 1,
        "parsedValueSchema": {
          "type": "integer",
          "minimum": 1
        }
      }
    },
    {
      "name": "limit",
      "schema": {
        "type": "string",
        "pattern": "^(?:\\+?0*(?:[1-9]|(?:1[0-9]|[2-8]\\d{1}|9[0-9])|100)(?:\\.0+)?)$"
      },
      "required": false,
      "wire": [
        {
          "path": "limit",
          "transform": "identity",
          "role": "query",
          "input": "limit",
          "contributors": [
            "limit"
          ]
        }
      ],
      "validation": {
        "syntax": "Decimal integer token.",
        "minimum": 1,
        "maximum": 100,
        "parsedValueSchema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100
        }
      }
    },
    {
      "name": "all",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "all",
        "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": "all",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "all",
          "contributors": [
            "all"
          ]
        }
      ]
    }
  ],
  "files": [],
  "wire": {
    "method": "GET",
    "route": "/utilities/templates",
    "query": {
      "status": [
        {
          "path": "status",
          "transform": "identity",
          "role": "query",
          "input": "status",
          "contributors": [
            "status"
          ]
        }
      ],
      "search": [
        {
          "path": "search",
          "transform": "identity",
          "role": "query",
          "input": "search",
          "contributors": [
            "search"
          ]
        }
      ],
      "page": [
        {
          "path": "page",
          "transform": "identity",
          "role": "query",
          "input": "page",
          "contributors": [
            "page"
          ]
        }
      ],
      "limit": [
        {
          "path": "limit",
          "transform": "identity",
          "role": "query",
          "input": "limit",
          "contributors": [
            "limit"
          ]
        }
      ]
    },
    "body": {},
    "ownerParams": []
  }
}

Response contract

Response fields outside the modeled stable fields may be passed through from the server.

The API response envelope is preserved by the CLI; stable fields are modeled and other server fields remain extensible.

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "status": {
        "const": "success"
      },
      "data": {
        "type": "object",
        "properties": {
          "templates": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "_id": {
                  "type": "string",
                  "pattern": "^[a-fA-F0-9]{24}$"
                },
                "name": {
                  "type": "string"
                },
                "language": {
                  "type": "string"
                },
                "body": {
                  "type": "string"
                },
                "header": {
                  "type": "object",
                  "properties": {
                    "text": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "text"
                  ],
                  "additionalProperties": true
                },
                "footer": {
                  "type": "string"
                },
                "buttons": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string"
                      },
                      "text": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string"
                      },
                      "phoneNumber": {
                        "type": "string"
                      },
                      "actionId": {
                        "type": "string"
                      },
                      "actionLabel": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "type",
                      "text"
                    ],
                    "additionalProperties": true
                  }
                },
                "variables": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string"
                      },
                      "example": {
                        "type": [
                          "string",
                          "number",
                          "boolean"
                        ]
                      },
                      "fallback": {
                        "type": "string"
                      },
                      "maxLength": {
                        "type": "integer",
                        "minimum": 1
                      }
                    },
                    "required": [
                      "name",
                      "example"
                    ],
                    "additionalProperties": true
                  }
                },
                "usableOn": {
                  "type": "object",
                  "properties": {
                    "whatsapp": {
                      "type": "boolean"
                    },
                    "sms": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "whatsapp",
                    "sms"
                  ],
                  "additionalProperties": true
                },
                "parameterFormat": {
                  "type": "string"
                },
                "akedlyStatus": {
                  "enum": [
                    "draft",
                    "pending_review",
                    "approved",
                    "rejected"
                  ]
                },
                "metaStatus": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "metaTemplateId": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "metaCategory": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "suggestedCategory": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "whatsappSubmitError": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "whatsappResubmittable": {
                  "type": "boolean"
                },
                "rejectionReason": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "sourceLibraryName": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "createdAt": {
                  "type": "string",
                  "format": "date-time"
                },
                "updatedAt": {
                  "type": "string",
                  "format": "date-time"
                }
              },
              "required": [
                "_id",
                "name",
                "language",
                "body",
                "variables",
                "usableOn",
                "parameterFormat",
                "akedlyStatus",
                "metaStatus",
                "whatsappResubmittable",
                "createdAt",
                "updatedAt"
              ],
              "additionalProperties": true
            }
          },
          "pagination": {
            "type": "object",
            "properties": {
              "currentPage": {
                "type": "integer",
                "minimum": 1
              },
              "totalPages": {
                "type": "integer",
                "minimum": 0
              },
              "totalCount": {
                "type": "integer",
                "minimum": 0
              },
              "limit": {
                "type": "integer",
                "minimum": 1
              }
            },
            "required": [
              "currentPage",
              "totalPages",
              "totalCount",
              "limit"
            ],
            "additionalProperties": true
          }
        },
        "required": [
          "templates",
          "pagination"
        ],
        "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
  }
}

json

{
  "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
  }
}

Common error guidance.

utilities templates get

inspect one owned template, including Akedly review and Meta submission state, before acting.

When to use

inspect one owned template, including Akedly review and Meta submission state, before acting.

How it works

Fetch the template by its 24-hex id from templates list.

Prerequisites

Authenticated account with utilities:read permission.
An owned template id from `utilities templates list`.

Expected outcome

Returns the owned template record.

Next steps

For a draft/rejected template, lint edits; inspect approval/submission errors before resubmission.

Usage

akedly utilities templates get <id>

Inspect this command offline before preparing an operation:

akedly describe "utilities templates get" --output json

Positional	Grammar	Usage guidance
<id>	^[a-fA-F0-9]{24}$	Use the id from akedly utilities templates list.

Flags

Flag	Type	Enum / range	Description
`--ksa`	boolean switch	—	Select the KSA deployment.
`--help`	boolean switch	—	Show offline command help.
`--output`	enum	json \| human	Select JSON or human output.
`--fields`	dot-paths	—	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: utilities:read.

Server request: GET /utilities/templates/:id.

Shared server-guard guidance.

Consent

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

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

Read one owned utility template using its 24-hex id from akedly utilities templates list. Read-only logins are supported.

Worked examples

Synthetic CLI scenario

inspect one owned template, including Akedly review and Meta submission state, before acting.

akedly utilities templates get 64b000000000000000000001

Illustrative response (sensitive values omitted):

json

{
  "status": "success",
  "data": {
    "_id": "64b000000000000000000002",
    "name": "Order update",
    "language": "en",
    "body": "Your order {{1}} is ready.",
    "header": {
      "text": "Order"
    },
    "buttons": [],
    "variables": [
      {
        "name": "1",
        "example": "ORD-17"
      }
    ],
    "usableOn": {
      "whatsapp": true,
      "sms": false
    },
    "parameterFormat": "POSITIONAL",
    "akedlyStatus": "draft",
    "metaStatus": null,
    "metaTemplateId": null,
    "metaCategory": null,
    "suggestedCategory": null,
    "whatsappSubmitError": null,
    "whatsappResubmittable": false,
    "rejectionReason": null,
    "sourceLibraryName": null,
    "createdAt": "2050-01-02T03:04:05.000Z",
    "updatedAt": "2050-01-02T03:04:05.000Z"
  }
}

Resource identifiers and records are fictional prerequisites, not claims that these resources exist.

Additional command forms

akedly utilities templates get <id>

Input and file contracts

Response contract

Read one owned utility template using its 24-hex id from akedly utilities templates list. Read-only logins are supported.

Response fields outside the modeled stable fields may be passed through from the server.

The API response envelope is preserved by the CLI; stable fields are modeled and other server fields remain extensible.

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "status": {
        "const": "success"
      },
      "data": {
        "type": "object",
        "properties": {
          "_id": {
            "type": "string",
            "pattern": "^[a-fA-F0-9]{24}$"
          },
          "name": {
            "type": "string"
          },
          "language": {
            "type": "string"
          },
          "body": {
            "type": "string"
          },
          "header": {
            "type": "object",
            "properties": {
              "text": {
                "type": "string"
              }
            },
            "required": [
              "text"
            ],
            "additionalProperties": true
          },
          "footer": {
            "type": "string"
          },
          "buttons": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "enum": [
                    "URL",
                    "PHONE_NUMBER",
                    "QUICK_REPLY"
                  ]
                },
                "text": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "phoneNumber": {
                  "type": "string"
                },
                "actionId": {
                  "type": "string"
                },
                "actionLabel": {
                  "type": "string"
                }
              },
              "required": [
                "type",
                "text"
              ],
              "additionalProperties": true
            }
          },
          "variables": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "example": {
                  "type": [
                    "string",
                    "number",
                    "boolean"
                  ]
                },
                "fallback": {
                  "type": "string"
                },
                "maxLength": {
                  "type": "integer",
                  "minimum": 1
                }
              },
              "required": [
                "name",
                "example"
              ],
              "additionalProperties": true
            }
          },
          "usableOn": {
            "type": "object",
            "properties": {
              "whatsapp": {
                "type": "boolean"
              },
              "sms": {
                "type": "boolean"
              }
            },
            "required": [
              "whatsapp",
              "sms"
            ],
            "additionalProperties": true
          },
          "parameterFormat": {
            "type": "string"
          },
          "akedlyStatus": {
            "type": "string"
          },
          "metaStatus": {
            "type": [
              "string",
              "null"
            ]
          },
          "metaTemplateId": {
            "type": [
              "string",
              "null"
            ]
          },
          "metaCategory": {
            "type": [
              "string",
              "null"
            ]
          },
          "suggestedCategory": {
            "type": [
              "string",
              "null"
            ]
          },
          "whatsappSubmitError": {
            "type": [
              "string",
              "null"
            ]
          },
          "whatsappResubmittable": {
            "type": "boolean"
          },
          "rejectionReason": {
            "type": [
              "string",
              "null"
            ]
          },
          "sourceLibraryName": {
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "_id",
          "name",
          "language",
          "body",
          "variables",
          "usableOn",
          "parameterFormat",
          "akedlyStatus",
          "metaStatus",
          "whatsappResubmittable",
          "createdAt",
          "updatedAt"
        ],
        "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
  }
}

json

{
  "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": {
    "NOT_FOUND": "Run akedly utilities templates list and check the template id."
  },
  "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
  }
}

Own recovery guidance

Code	Hint
NOT_FOUND	Run akedly utilities templates list and check the template id.

Common error guidance.

utilities templates lint

check proposed template structure and server-side content rules without saving, submitting, sending or charging.

When to use

check proposed template structure and server-side content rules without saving, submitting, sending or charging.

How it works

Read a JSON object file, validate the local lint shape, then ask the server for lint rules and advisory prediction.

Prerequisites

Authenticated account with utilities:read permission.

Expected outcome

HTTP 200 may return passed:false; that is a lint finding, not command failure. predictedOutcome is Meta prediction, not Akedly approval.

Next steps

Fix issues, then lint again; inspect predictedOutcome for possible Marketing reclassification before submitting.

Usage

akedly utilities templates lint

Inspect this command offline before preparing an operation:

akedly describe "utilities templates lint" --output json

Flags

Flag	Type	Enum / range	Required	Description
`--ksa`	boolean switch	—	no	Select the KSA deployment.
`--file`	text	—	yes	Command-specific option; see the full command details below. Manifest body field: body, buttons, footer, header, id, language, name, variables.
`--dry-run`	boolean switch	—	no	Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
`--help`	boolean switch	—	no	Show offline command help.
`--output`	enum	json \| human	no	Select JSON or human output.
`--fields`	dot-paths	—	no	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: utilities:read.

Server request: POST /utilities/templates/lint.

Shared server-guard guidance.

Consent

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

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

Lint a proposed template without saving, submitting, sending or charging. --file is required: a JSON object at most 64 KiB containing only id, name, language, body, variables, header, footer and buttons; extra top-level fields are refused. Optional id must be a 24-hex template id. Set id only to an existing Akedly template's _id (from akedly utilities templates get) so lint does not report it as its own duplicate; remove id, category and other extra fields from library or curated entries before linting. Shape checks run locally; template rules and advisory predictions come from the server, not the CLI. HTTP 200 with data.passed:false remains a successful lint and exits 0; inspect issues and predictedOutcome (Meta's predicted verdict, not Akedly approval). predictedOutcome approve_with_reclassification predicts likely Meta approval as Marketing, which costs more per message than Utility; reword the content first or submit knowingly. This is advisory, not Meta approval. Read-only logins are supported. --dry-run prints the validated request without contacting the server.

Worked examples

Synthetic CLI scenario

check proposed template structure and server-side content rules without saving, submitting, sending or charging.

akedly utilities templates lint --file template.json

Input file: template.json (json).

json

{
  "name": "Appointment reminder",
  "language": "en",
  "body": "Your appointment is tomorrow.",
  "variables": []
}

Illustrative response (sensitive values omitted):

json

{
  "status": "success",
  "data": {
    "passed": true,
    "strict": false,
    "predictedOutcome": "approve_with_reclassification",
    "issues": [
      {
        "ruleId": "CATEGORY_UTILITY_RECLASSIFICATION",
        "severity": "warning",
        "channel": "category",
        "component": "body",
        "message": "This content may be classified as Marketing."
      }
    ]
  }
}

Resource identifiers and records are fictional prerequisites, not claims that these resources exist.

Additional command forms

akedly utilities templates lint --file <path>

Input and file contracts

json

{
  "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": "file",
      "schema": {
        "type": "string"
      },
      "required": true,
      "input": {
        "role": "input-file",
        "contract": "utility-template-lint",
        "requestTargets": [
          {
            "role": "body",
            "path": "$",
            "transform": "json-fields",
            "fileContract": "utility-template-lint"
          }
        ],
        "schema": {
          "$schema": "https://json-schema.org/draft/2020-12/schema",
          "title": "Utility-template lint input",
          "description": "JSON object containing only the listed top-level fields. Values are linted for template grammar and component rules; the CLI checks shape/types and the server linter supplies semantic constraints. Arrays contain objects, with documented fields typed below.",
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "pattern": "^[a-fA-F0-9]{24}$"
            },
            "name": {
              "type": "string"
            },
            "language": {
              "type": "string"
            },
            "body": {
              "type": "string"
            },
            "variables": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/lintVariable"
              }
            },
            "header": {
              "$ref": "#/$defs/header"
            },
            "footer": {
              "type": "string"
            },
            "buttons": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/button"
              }
            }
          },
          "additionalProperties": false,
          "$defs": {
            "lintVariable": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "example": {
                  "type": "string"
                },
                "fallback": {
                  "type": "string"
                },
                "maxLength": {
                  "type": "number"
                }
              },
              "additionalProperties": true
            },
            "header": {
              "type": "object",
              "properties": {
                "text": {
                  "type": "string"
                }
              },
              "additionalProperties": true
            },
            "button": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string"
                },
                "text": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "phoneNumber": {
                  "type": "string"
                },
                "actionId": {
                  "type": "string"
                },
                "actionLabel": {
                  "type": "string"
                }
              },
              "additionalProperties": true
            }
          }
        },
        "localReaderSchema": {
          "$schema": "https://json-schema.org/draft/2020-12/schema",
          "type": "object",
          "properties": {
            "id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                },
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                },
                {
                  "type": "object",
                  "additionalProperties": true
                },
                {
                  "type": "array",
                  "items": true
                }
              ]
            },
            "name": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                },
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                },
                {
                  "type": "object",
                  "additionalProperties": true
                },
                {
                  "type": "array",
                  "items": true
                }
              ]
            },
            "language": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                },
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                },
                {
                  "type": "object",
                  "additionalProperties": true
                },
                {
                  "type": "array",
                  "items": true
                }
              ]
            },
            "body": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                },
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                },
                {
                  "type": "object",
                  "additionalProperties": true
                },
                {
                  "type": "array",
                  "items": true
                }
              ]
            },
            "variables": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                },
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                },
                {
                  "type": "object",
                  "additionalProperties": true
                },
                {
                  "type": "array",
                  "items": true
                }
              ]
            },
            "header": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                },
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                },
                {
                  "type": "object",
                  "additionalProperties": true
                },
                {
                  "type": "array",
                  "items": true
                }
              ]
            },
            "footer": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                },
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                },
                {
                  "type": "object",
                  "additionalProperties": true
                },
                {
                  "type": "array",
                  "items": true
                }
              ]
            },
            "buttons": {
              "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": [
            "id",
            "name",
            "language",
            "body",
            "variables",
            "header",
            "footer",
            "buttons"
          ],
          "reader": "utilitytemplates.js:lintPlan",
          "type": "json-object",
          "exclusive": false,
          "mode": null,
          "trim": false,
          "writer": null,
          "minBytes": 0,
          "detectChanges": true,
          "fieldMappings": {
            "id": {
              "path": "id",
              "transform": "identity"
            },
            "name": {
              "path": "name",
              "transform": "identity"
            },
            "language": {
              "path": "language",
              "transform": "identity"
            },
            "body": {
              "path": "body",
              "transform": "identity"
            },
            "variables": {
              "path": "variables",
              "transform": "identity"
            },
            "header": {
              "path": "header",
              "transform": "identity"
            },
            "footer": {
              "path": "footer",
              "transform": "identity"
            },
            "buttons": {
              "path": "buttons",
              "transform": "identity"
            }
          }
        },
        "semanticSchema": {
          "$schema": "https://json-schema.org/draft/2020-12/schema",
          "title": "Utility-template lint input",
          "description": "JSON object containing only the listed top-level fields. Values are linted for template grammar and component rules; the CLI checks shape/types and the server linter supplies semantic constraints. Arrays contain objects, with documented fields typed below.",
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "pattern": "^[a-fA-F0-9]{24}$"
            },
            "name": {
              "type": "string"
            },
            "language": {
              "type": "string"
            },
            "body": {
              "type": "string"
            },
            "variables": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/lintVariable"
              }
            },
            "header": {
              "$ref": "#/$defs/header"
            },
            "footer": {
              "type": "string"
            },
            "buttons": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/button"
              }
            }
          },
          "additionalProperties": false,
          "$defs": {
            "lintVariable": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "example": {
                  "type": "string"
                },
                "fallback": {
                  "type": "string"
                },
                "maxLength": {
                  "type": "number"
                }
              },
              "additionalProperties": true
            },
            "header": {
              "type": "object",
              "properties": {
                "text": {
                  "type": "string"
                }
              },
              "additionalProperties": true
            },
            "button": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string"
                },
                "text": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "phoneNumber": {
                  "type": "string"
                },
                "actionId": {
                  "type": "string"
                },
                "actionLabel": {
                  "type": "string"
                }
              },
              "additionalProperties": true
            }
          }
        },
        "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-template-lint",
          "contributors": [
            "file"
          ]
        },
        {
          "role": "body",
          "path": "body",
          "transform": "identity",
          "fileContract": "utility-template-lint",
          "input": "file",
          "contributors": [
            "file"
          ],
          "fileKey": "body",
          "inputTransform": "json-fields"
        },
        {
          "role": "body",
          "path": "buttons",
          "transform": "identity",
          "fileContract": "utility-template-lint",
          "input": "file",
          "contributors": [
            "file"
          ],
          "fileKey": "buttons",
          "inputTransform": "json-fields"
        },
        {
          "role": "body",
          "path": "footer",
          "transform": "identity",
          "fileContract": "utility-template-lint",
          "input": "file",
          "contributors": [
            "file"
          ],
          "fileKey": "footer",
          "inputTransform": "json-fields"
        },
        {
          "role": "body",
          "path": "header",
          "transform": "identity",
          "fileContract": "utility-template-lint",
          "input": "file",
          "contributors": [
            "file"
          ],
          "fileKey": "header",
          "inputTransform": "json-fields"
        },
        {
          "role": "body",
          "path": "id",
          "transform": "identity",
          "fileContract": "utility-template-lint",
          "input": "file",
          "contributors": [
            "file"
          ],
          "fileKey": "id",
          "inputTransform": "json-fields"
        },
        {
          "role": "body",
          "path": "language",
          "transform": "identity",
          "fileContract": "utility-template-lint",
          "input": "file",
          "contributors": [
            "file"
          ],
          "fileKey": "language",
          "inputTransform": "json-fields"
        },
        {
          "role": "body",
          "path": "name",
          "transform": "identity",
          "fileContract": "utility-template-lint",
          "input": "file",
          "contributors": [
            "file"
          ],
          "fileKey": "name",
          "inputTransform": "json-fields"
        },
        {
          "role": "body",
          "path": "variables",
          "transform": "identity",
          "fileContract": "utility-template-lint",
          "input": "file",
          "contributors": [
            "file"
          ],
          "fileKey": "variables",
          "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-template-lint",
      "contract": {
        "format": "json-object",
        "maxBytes": 65536,
        "regularFile": true,
        "fields": [
          "id",
          "name",
          "language",
          "body",
          "variables",
          "header",
          "footer",
          "buttons"
        ],
        "reader": "utilitytemplates.js:lintPlan",
        "type": "json-object",
        "exclusive": false,
        "mode": null,
        "trim": false,
        "writer": null,
        "minBytes": 0,
        "detectChanges": true,
        "fieldMappings": {
          "id": {
            "path": "id",
            "transform": "identity"
          },
          "name": {
            "path": "name",
            "transform": "identity"
          },
          "language": {
            "path": "language",
            "transform": "identity"
          },
          "body": {
            "path": "body",
            "transform": "identity"
          },
          "variables": {
            "path": "variables",
            "transform": "identity"
          },
          "header": {
            "path": "header",
            "transform": "identity"
          },
          "footer": {
            "path": "footer",
            "transform": "identity"
          },
          "buttons": {
            "path": "buttons",
            "transform": "identity"
          }
        }
      },
      "schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": {
          "id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "array",
                "items": true
              }
            ]
          },
          "name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "array",
                "items": true
              }
            ]
          },
          "language": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "array",
                "items": true
              }
            ]
          },
          "body": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "array",
                "items": true
              }
            ]
          },
          "variables": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "array",
                "items": true
              }
            ]
          },
          "header": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "array",
                "items": true
              }
            ]
          },
          "footer": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "array",
                "items": true
              }
            ]
          },
          "buttons": {
            "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": "Utility-template lint input",
            "description": "JSON object containing only the listed top-level fields. Values are linted for template grammar and component rules; the CLI checks shape/types and the server linter supplies semantic constraints. Arrays contain objects, with documented fields typed below.",
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "pattern": "^[a-fA-F0-9]{24}$"
              },
              "name": {
                "type": "string"
              },
              "language": {
                "type": "string"
              },
              "body": {
                "type": "string"
              },
              "variables": {
                "type": "array",
                "items": {
                  "$ref": "#/$defs/lintVariable"
                }
              },
              "header": {
                "$ref": "#/$defs/header"
              },
              "footer": {
                "type": "string"
              },
              "buttons": {
                "type": "array",
                "items": {
                  "$ref": "#/$defs/button"
                }
              }
            },
            "additionalProperties": false,
            "$defs": {
              "lintVariable": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "example": {
                    "type": "string"
                  },
                  "fallback": {
                    "type": "string"
                  },
                  "maxLength": {
                    "type": "number"
                  }
                },
                "additionalProperties": true
              },
              "header": {
                "type": "object",
                "properties": {
                  "text": {
                    "type": "string"
                  }
                },
                "additionalProperties": true
              },
              "button": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string"
                  },
                  "text": {
                    "type": "string"
                  },
                  "url": {
                    "type": "string"
                  },
                  "phoneNumber": {
                    "type": "string"
                  },
                  "actionId": {
                    "type": "string"
                  },
                  "actionLabel": {
                    "type": "string"
                  }
                },
                "additionalProperties": true
              }
            }
          }
        }
      ]
    }
  ],
  "wire": {
    "method": "POST",
    "route": "/utilities/templates/lint",
    "query": {},
    "body": {},
    "ownerParams": []
  }
}

Response contract

Response fields outside the modeled stable fields may be passed through from the server.

The API response envelope is preserved by the CLI; stable fields are modeled and other server fields remain extensible.

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "status": {
        "const": "success"
      },
      "data": {
        "type": "object",
        "properties": {
          "passed": {
            "type": "boolean"
          },
          "strict": {
            "type": "boolean"
          },
          "predictedOutcome": {
            "enum": [
              "reject",
              "approve_with_reclassification",
              "approve"
            ]
          },
          "issues": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "ruleId": {
                  "type": "string"
                },
                "severity": {
                  "type": "string"
                },
                "channel": {
                  "type": "string"
                },
                "group": {
                  "type": "integer"
                },
                "component": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                },
                "span": {
                  "type": "object",
                  "properties": {
                    "start": {
                      "type": "integer"
                    },
                    "end": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "start",
                    "end"
                  ],
                  "additionalProperties": true
                },
                "buttonIndex": {
                  "type": "integer"
                },
                "variable": {
                  "type": "string"
                },
                "field": {
                  "type": "string"
                },
                "fixHint": {
                  "type": "string"
                },
                "metaCode": {
                  "type": "string"
                }
              },
              "required": [
                "ruleId",
                "severity",
                "channel",
                "component",
                "message"
              ],
              "additionalProperties": true
            }
          }
        },
        "required": [
          "passed",
          "strict",
          "predictedOutcome",
          "issues"
        ],
        "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
  }
}

json

{
  "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_SHAPE": "Check the JSON field shapes in --file; see akedly utilities templates lint --help.",
    "INPUT_TOO_LARGE": "Reduce the template input; --file is limited to 64 KiB and the server also bounds individual fields."
  },
  "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
  }
}

Own recovery guidance

Code	Hint
INVALID_SHAPE	Check the JSON field shapes in `--file`; see akedly utilities templates lint `--help`.
INPUT_TOO_LARGE	Reduce the template input; `--file` is limited to 64 KiB and the server also bounds individual fields.

Common error guidance.

utilities templates create

save an owned draft utility template after linting/adapting content; creation does not submit or notify.

When to use

save an owned draft utility template after linting/adapting content; creation does not submit or notify.

How it works

Read validated authoring JSON and create a draft; omitted language defaults to en and usableOn has server defaults.

Prerequisites

Authenticated account with utilities:create permission.

Expected outcome

Returns the created template record.

Next steps

Read it with templates get, lint the final content, then submit only when ready.

Usage

akedly utilities templates create

Inspect this command offline before preparing an operation:

akedly describe "utilities templates create" --output json

Flags

Flag	Type	Enum / range	Required	Description
`--ksa`	boolean switch	—	no	Select the KSA deployment.
`--file`	text	—	yes	Command-specific option; see the full command details below. Manifest body field: body, buttons, footer, header, language, name, sourceLibraryName, usableOn, variables.
`--dry-run`	boolean switch	—	no	Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
`--help`	boolean switch	—	no	Show offline command help.
`--output`	enum	json \| human	no	Select JSON or human output.
`--fields`	dot-paths	—	no	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: utilities:create.

Server request: POST /utilities/templates.

Shared server-guard guidance.

Consent

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

Retry

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

Output

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

Full command details

Create an owned draft utility template without submitting it or sending notifications. Required --file is a regular JSON object at most 64 KiB containing only name, language, body, variables, sourceLibraryName, usableOn, header, footer and buttons. sourceLibraryName records the library entry the template was copied or adapted from. name and body must be non-empty strings. Omitted language defaults to en; other language strings pass through to the server. usableOn accepts only whatsapp/sms JSON booleans (defaults whatsapp on, sms off); SMS requires eligible BYO-SMS. Variables are an array of objects with name, example, optional string fallback and integer maxLength >= 1; examples may be strings, numbers or booleans. Optional header is {text}, footer is text, and buttons is an array with type URL, PHONE_NUMBER or QUICK_REPLY plus text and type-specific url, phoneNumber, actionId or actionLabel. Server template rules remain authoritative. Do not copy id, category or other server metadata into the file. An ambiguous network or server failure is not retried; list templates before repeating. Read-only logins are refused. --dry-run validates and prints the request without contacting the server.

Worked examples

Synthetic CLI scenario

save an owned draft utility template after linting/adapting content; creation does not submit or notify.

akedly utilities templates create --file template.json

Input file: template.json (json).

json

{
  "name": "Appointment reminder",
  "language": "en",
  "body": "Your appointment is tomorrow.",
  "variables": [],
  "sourceLibraryName": "Appointment reminder",
  "usableOn": {
    "whatsapp": true,
    "sms": false
  }
}

Illustrative response (sensitive values omitted):

json

{
  "status": "success",
  "data": {
    "_id": "64b000000000000000000002",
    "name": "Order update",
    "language": "en",
    "body": "Your order {{1}} is ready.",
    "header": {
      "text": "Order"
    },
    "buttons": [],
    "variables": [
      {
        "name": "1",
        "example": "ORD-17"
      }
    ],
    "usableOn": {
      "whatsapp": true,
      "sms": false
    },
    "parameterFormat": "POSITIONAL",
    "akedlyStatus": "draft",
    "metaStatus": null,
    "metaTemplateId": null,
    "metaCategory": null,
    "suggestedCategory": null,
    "whatsappSubmitError": null,
    "whatsappResubmittable": false,
    "rejectionReason": null,
    "sourceLibraryName": null,
    "createdAt": "2050-01-02T03:04:05.000Z",
    "updatedAt": "2050-01-02T03:04:05.000Z"
  }
}

Resource identifiers and records are fictional prerequisites, not claims that these resources exist.

Additional command forms

akedly utilities templates create --file <path>

Input and file contracts

json

{
  "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": "file",
      "schema": {
        "type": "string"
      },
      "required": true,
      "input": {
        "role": "input-file",
        "contract": "utility-template-create",
        "requestTargets": [
          {
            "role": "body",
            "path": "$",
            "transform": "json-fields",
            "fileContract": "utility-template-create"
          }
        ],
        "schema": {
          "$schema": "https://json-schema.org/draft/2020-12/schema",
          "title": "Utility-template create document",
          "description": "JSON object with only these top-level fields. name and body are required non-empty strings; authoring variables are named entries with optional example, fallback and maxLength; backend checks template grammar and channel components.",
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "minLength": 1,
              "pattern": "\\S"
            },
            "language": {
              "type": "string",
              "pattern": "\\S"
            },
            "body": {
              "type": "string",
              "minLength": 1,
              "pattern": "\\S"
            },
            "variables": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/authoringVariable"
              }
            },
            "sourceLibraryName": {
              "type": "string"
            },
            "usableOn": {
              "$ref": "#/$defs/usableOn"
            },
            "header": {
              "$ref": "#/$defs/header"
            },
            "footer": {
              "type": "string"
            },
            "buttons": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/button"
              }
            }
          },
          "required": [
            "name",
            "body"
          ],
          "additionalProperties": false,
          "$defs": {
            "authoringVariable": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "example": {
                  "type": [
                    "string",
                    "number",
                    "boolean"
                  ]
                },
                "fallback": {
                  "type": "string"
                },
                "maxLength": {
                  "type": "integer",
                  "minimum": 1
                }
              },
              "additionalProperties": true
            },
            "usableOn": {
              "type": "object",
              "properties": {
                "whatsapp": {
                  "type": "boolean"
                },
                "sms": {
                  "type": "boolean"
                }
              },
              "additionalProperties": false
            },
            "header": {
              "type": "object",
              "properties": {
                "text": {
                  "type": "string"
                }
              },
              "additionalProperties": true
            },
            "button": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "URL",
                    "PHONE_NUMBER",
                    "QUICK_REPLY"
                  ]
                },
                "text": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "phoneNumber": {
                  "type": "string"
                },
                "actionId": {
                  "type": "string"
                },
                "actionLabel": {
                  "type": "string"
                }
              },
              "additionalProperties": true
            }
          }
        },
        "localReaderSchema": {
          "$schema": "https://json-schema.org/draft/2020-12/schema",
          "type": "object",
          "properties": {
            "name": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                },
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                },
                {
                  "type": "object",
                  "additionalProperties": true
                },
                {
                  "type": "array",
                  "items": true
                }
              ]
            },
            "language": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                },
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                },
                {
                  "type": "object",
                  "additionalProperties": true
                },
                {
                  "type": "array",
                  "items": true
                }
              ]
            },
            "body": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                },
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                },
                {
                  "type": "object",
                  "additionalProperties": true
                },
                {
                  "type": "array",
                  "items": true
                }
              ]
            },
            "variables": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                },
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                },
                {
                  "type": "object",
                  "additionalProperties": true
                },
                {
                  "type": "array",
                  "items": true
                }
              ]
            },
            "sourceLibraryName": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                },
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                },
                {
                  "type": "object",
                  "additionalProperties": true
                },
                {
                  "type": "array",
                  "items": true
                }
              ]
            },
            "usableOn": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                },
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                },
                {
                  "type": "object",
                  "additionalProperties": true
                },
                {
                  "type": "array",
                  "items": true
                }
              ]
            },
            "header": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                },
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                },
                {
                  "type": "object",
                  "additionalProperties": true
                },
                {
                  "type": "array",
                  "items": true
                }
              ]
            },
            "footer": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                },
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                },
                {
                  "type": "object",
                  "additionalProperties": true
                },
                {
                  "type": "array",
                  "items": true
                }
              ]
            },
            "buttons": {
              "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": [
            "name",
            "language",
            "body",
            "variables",
            "sourceLibraryName",
            "usableOn",
            "header",
            "footer",
            "buttons"
          ],
          "reader": "utilitytemplatewrites.js:authoringPlan",
          "type": "json-object",
          "exclusive": false,
          "mode": null,
          "trim": false,
          "writer": null,
          "minBytes": 0,
          "detectChanges": true,
          "fieldMappings": {
            "name": {
              "path": "name",
              "transform": "identity"
            },
            "language": {
              "path": "language",
              "transform": "identity"
            },
            "body": {
              "path": "body",
              "transform": "identity"
            },
            "variables": {
              "path": "variables",
              "transform": "identity"
            },
            "sourceLibraryName": {
              "path": "sourceLibraryName",
              "transform": "identity"
            },
            "usableOn": {
              "path": "usableOn",
              "transform": "identity"
            },
            "header": {
              "path": "header",
              "transform": "identity"
            },
            "footer": {
              "path": "footer",
              "transform": "identity"
            },
            "buttons": {
              "path": "buttons",
              "transform": "identity"
            }
          }
        },
        "semanticSchema": {
          "$schema": "https://json-schema.org/draft/2020-12/schema",
          "title": "Utility-template create document",
          "description": "JSON object with only these top-level fields. name and body are required non-empty strings; authoring variables are named entries with optional example, fallback and maxLength; backend checks template grammar and channel components.",
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "minLength": 1,
              "pattern": "\\S"
            },
            "language": {
              "type": "string",
              "pattern": "\\S"
            },
            "body": {
              "type": "string",
              "minLength": 1,
              "pattern": "\\S"
            },
            "variables": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/authoringVariable"
              }
            },
            "sourceLibraryName": {
              "type": "string"
            },
            "usableOn": {
              "$ref": "#/$defs/usableOn"
            },
            "header": {
              "$ref": "#/$defs/header"
            },
            "footer": {
              "type": "string"
            },
            "buttons": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/button"
              }
            }
          },
          "required": [
            "name",
            "body"
          ],
          "additionalProperties": false,
          "$defs": {
            "authoringVariable": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "example": {
                  "type": [
                    "string",
                    "number",
                    "boolean"
                  ]
                },
                "fallback": {
                  "type": "string"
                },
                "maxLength": {
                  "type": "integer",
                  "minimum": 1
                }
              },
              "additionalProperties": true
            },
            "usableOn": {
              "type": "object",
              "properties": {
                "whatsapp": {
                  "type": "boolean"
                },
                "sms": {
                  "type": "boolean"
                }
              },
              "additionalProperties": false
            },
            "header": {
              "type": "object",
              "properties": {
                "text": {
                  "type": "string"
                }
              },
              "additionalProperties": true
            },
            "button": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "URL",
                    "PHONE_NUMBER",
                    "QUICK_REPLY"
                  ]
                },
                "text": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "phoneNumber": {
                  "type": "string"
                },
                "actionId": {
                  "type": "string"
                },
                "actionLabel": {
                  "type": "string"
                }
              },
              "additionalProperties": true
            }
          }
        },
        "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-template-create",
          "contributors": [
            "file"
          ]
        },
        {
          "role": "body",
          "path": "body",
          "transform": "identity",
          "fileContract": "utility-template-create",
          "input": "file",
          "contributors": [
            "file"
          ],
          "fileKey": "body",
          "inputTransform": "json-fields"
        },
        {
          "role": "body",
          "path": "buttons",
          "transform": "identity",
          "fileContract": "utility-template-create",
          "input": "file",
          "contributors": [
            "file"
          ],
          "fileKey": "buttons",
          "inputTransform": "json-fields"
        },
        {
          "role": "body",
          "path": "footer",
          "transform": "identity",
          "fileContract": "utility-template-create",
          "input": "file",
          "contributors": [
            "file"
          ],
          "fileKey": "footer",
          "inputTransform": "json-fields"
        },
        {
          "role": "body",
          "path": "header",
          "transform": "identity",
          "fileContract": "utility-template-create",
          "input": "file",
          "contributors": [
            "file"
          ],
          "fileKey": "header",
          "inputTransform": "json-fields"
        },
        {
          "role": "body",
          "path": "language",
          "transform": "identity",
          "fileContract": "utility-template-create",
          "input": "file",
          "contributors": [
            "file"
          ],
          "fileKey": "language",
          "inputTransform": "json-fields"
        },
        {
          "role": "body",
          "path": "name",
          "transform": "identity",
          "fileContract": "utility-template-create",
          "input": "file",
          "contributors": [
            "file"
          ],
          "fileKey": "name",
          "inputTransform": "json-fields"
        },
        {
          "role": "body",
          "path": "sourceLibraryName",
          "transform": "identity",
          "fileContract": "utility-template-create",
          "input": "file",
          "contributors": [
            "file"
          ],
          "fileKey": "sourceLibraryName",
          "inputTransform": "json-fields"
        },
        {
          "role": "body",
          "path": "usableOn",
          "transform": "identity",
          "fileContract": "utility-template-create",
          "input": "file",
          "contributors": [
            "file"
          ],
          "fileKey": "usableOn",
          "inputTransform": "json-fields"
        },
        {
          "role": "body",
          "path": "variables",
          "transform": "identity",
          "fileContract": "utility-template-create",
          "input": "file",
          "contributors": [
            "file"
          ],
          "fileKey": "variables",
          "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-template-create",
      "contract": {
        "format": "json-object",
        "maxBytes": 65536,
        "regularFile": true,
        "fields": [
          "name",
          "language",
          "body",
          "variables",
          "sourceLibraryName",
          "usableOn",
          "header",
          "footer",
          "buttons"
        ],
        "reader": "utilitytemplatewrites.js:authoringPlan",
        "type": "json-object",
        "exclusive": false,
        "mode": null,
        "trim": false,
        "writer": null,
        "minBytes": 0,
        "detectChanges": true,
        "fieldMappings": {
          "name": {
            "path": "name",
            "transform": "identity"
          },
          "language": {
            "path": "language",
            "transform": "identity"
          },
          "body": {
            "path": "body",
            "transform": "identity"
          },
          "variables": {
            "path": "variables",
            "transform": "identity"
          },
          "sourceLibraryName": {
            "path": "sourceLibraryName",
            "transform": "identity"
          },
          "usableOn": {
            "path": "usableOn",
            "transform": "identity"
          },
          "header": {
            "path": "header",
            "transform": "identity"
          },
          "footer": {
            "path": "footer",
            "transform": "identity"
          },
          "buttons": {
            "path": "buttons",
            "transform": "identity"
          }
        }
      },
      "schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": {
          "name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "array",
                "items": true
              }
            ]
          },
          "language": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "array",
                "items": true
              }
            ]
          },
          "body": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "array",
                "items": true
              }
            ]
          },
          "variables": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "array",
                "items": true
              }
            ]
          },
          "sourceLibraryName": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "array",
                "items": true
              }
            ]
          },
          "usableOn": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "array",
                "items": true
              }
            ]
          },
          "header": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "array",
                "items": true
              }
            ]
          },
          "footer": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "array",
                "items": true
              }
            ]
          },
          "buttons": {
            "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": "Utility-template create document",
            "description": "JSON object with only these top-level fields. name and body are required non-empty strings; authoring variables are named entries with optional example, fallback and maxLength; backend checks template grammar and channel components.",
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "minLength": 1,
                "pattern": "\\S"
              },
              "language": {
                "type": "string",
                "pattern": "\\S"
              },
              "body": {
                "type": "string",
                "minLength": 1,
                "pattern": "\\S"
              },
              "variables": {
                "type": "array",
                "items": {
                  "$ref": "#/$defs/authoringVariable"
                }
              },
              "sourceLibraryName": {
                "type": "string"
              },
              "usableOn": {
                "$ref": "#/$defs/usableOn"
              },
              "header": {
                "$ref": "#/$defs/header"
              },
              "footer": {
                "type": "string"
              },
              "buttons": {
                "type": "array",
                "items": {
                  "$ref": "#/$defs/button"
                }
              }
            },
            "required": [
              "name",
              "body"
            ],
            "additionalProperties": false,
            "$defs": {
              "authoringVariable": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "example": {
                    "type": [
                      "string",
                      "number",
                      "boolean"
                    ]
                  },
                  "fallback": {
                    "type": "string"
                  },
                  "maxLength": {
                    "type": "integer",
                    "minimum": 1
                  }
                },
                "additionalProperties": true
              },
              "usableOn": {
                "type": "object",
                "properties": {
                  "whatsapp": {
                    "type": "boolean"
                  },
                  "sms": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": false
              },
              "header": {
                "type": "object",
                "properties": {
                  "text": {
                    "type": "string"
                  }
                },
                "additionalProperties": true
              },
              "button": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "URL",
                      "PHONE_NUMBER",
                      "QUICK_REPLY"
                    ]
                  },
                  "text": {
                    "type": "string"
                  },
                  "url": {
                    "type": "string"
                  },
                  "phoneNumber": {
                    "type": "string"
                  },
                  "actionId": {
                    "type": "string"
                  },
                  "actionLabel": {
                    "type": "string"
                  }
                },
                "additionalProperties": true
              }
            }
          }
        }
      ]
    }
  ],
  "wire": {
    "method": "POST",
    "route": "/utilities/templates",
    "query": {},
    "body": {},
    "ownerParams": []
  }
}

Response contract

Response fields outside the modeled stable fields may be passed through from the server.

The API response envelope is preserved by the CLI; stable fields are modeled and other server fields remain extensible.

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "status": {
        "const": "success"
      },
      "data": {
        "type": "object",
        "properties": {
          "_id": {
            "type": "string",
            "pattern": "^[a-fA-F0-9]{24}$"
          },
          "name": {
            "type": "string"
          },
          "language": {
            "type": "string"
          },
          "body": {
            "type": "string"
          },
          "header": {
            "type": "object",
            "properties": {
              "text": {
                "type": "string"
              }
            },
            "required": [
              "text"
            ],
            "additionalProperties": true
          },
          "footer": {
            "type": "string"
          },
          "buttons": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "enum": [
                    "URL",
                    "PHONE_NUMBER",
                    "QUICK_REPLY"
                  ]
                },
                "text": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "phoneNumber": {
                  "type": "string"
                },
                "actionId": {
                  "type": "string"
                },
                "actionLabel": {
                  "type": "string"
                }
              },
              "required": [
                "type",
                "text"
              ],
              "additionalProperties": true
            }
          },
          "variables": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "example": {
                  "type": [
                    "string",
                    "number",
                    "boolean"
                  ]
                },
                "fallback": {
                  "type": "string"
                },
                "maxLength": {
                  "type": "integer",
                  "minimum": 1
                }
              },
              "required": [
                "name",
                "example"
              ],
              "additionalProperties": true
            }
          },
          "usableOn": {
            "type": "object",
            "properties": {
              "whatsapp": {
                "type": "boolean"
              },
              "sms": {
                "type": "boolean"
              }
            },
            "required": [
              "whatsapp",
              "sms"
            ],
            "additionalProperties": true
          },
          "parameterFormat": {
            "type": "string"
          },
          "akedlyStatus": {
            "type": "string"
          },
          "metaStatus": {
            "type": [
              "string",
              "null"
            ]
          },
          "metaTemplateId": {
            "type": [
              "string",
              "null"
            ]
          },
          "metaCategory": {
            "type": [
              "string",
              "null"
            ]
          },
          "suggestedCategory": {
            "type": [
              "string",
              "null"
            ]
          },
          "whatsappSubmitError": {
            "type": [
              "string",
              "null"
            ]
          },
          "whatsappResubmittable": {
            "type": "boolean"
          },
          "rejectionReason": {
            "type": [
              "string",
              "null"
            ]
          },
          "sourceLibraryName": {
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "_id",
          "name",
          "language",
          "body",
          "variables",
          "usableOn",
          "parameterFormat",
          "akedlyStatus",
          "metaStatus",
          "metaTemplateId",
          "metaCategory",
          "suggestedCategory",
          "whatsappSubmitError",
          "whatsappResubmittable",
          "rejectionReason",
          "sourceLibraryName",
          "createdAt",
          "updatedAt"
        ],
        "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
  }
}

json

{
  "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": {
    "DUPLICATE_NAME": "Run akedly utilities templates list and choose an unused name and language.",
    "NO_TEMPLATE_CHANNEL": "Enable at least one of usableOn.whatsapp or usableOn.sms in --file.",
    "UTILITY_SMS_REQUIRES_BYO": "Connect, test and activate an eligible BYO-SMS integration before enabling usableOn.sms. Check akedly byo-sms list and akedly whoami for BYO-SMS entitlement and granular pricing."
  },
  "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
  }
}

Own recovery guidance

Code	Hint
DUPLICATE_NAME	Run akedly utilities templates list and choose an unused name and language.
NO_TEMPLATE_CHANNEL	Enable at least one of usableOn.whatsapp or usableOn.sms in `--file`.
UTILITY_SMS_REQUIRES_BYO	Connect, test and activate an eligible BYO-SMS integration before enabling usableOn.sms. Check akedly byo-sms list and akedly whoami for BYO-SMS entitlement and granular pricing.

Common error guidance.

utilities templates update

change authoring fields on an owned eligible template; editing resets Akedly approval/rejection and can notify staff.

When to use

change authoring fields on an owned eligible template; editing resets Akedly approval/rejection and can notify staff.

How it works

Read partial authoring JSON; omitted fields remain, supplied arrays replace entirely, nullable fields can clear. Requires explicit confirmation.

Prerequisites

Authenticated account with utilities:update permission.
Writable owner account and explicit confirmation where required.
An owned template in draft, rejected, or eligible approved-but-never-submitted state; at least one supplied authoring field.

Expected outcome

Returns updated template state.

Next steps

Get the template and lint it. Submit again for Akedly review if appropriate; do not retry an ambiguous update before checking current state.

Usage

akedly utilities templates update <id>

Inspect this command offline before preparing an operation:

akedly describe "utilities templates update" --output json

Positional	Grammar	Usage guidance
<id>	^[a-fA-F0-9]{24}$	Use the id from akedly utilities templates list.

Flags

Flag	Type	Enum / range	Required	Description
`--ksa`	boolean switch	—	no	Select the KSA deployment.
`--file`	text	—	yes	Command-specific option; see the full command details below. Manifest body field: body, buttons, footer, header, language, name, usableOn, variables.
`--yes`	boolean switch	—	no	Confirm this action where consent is required.
`--dry-run`	boolean switch	—	no	Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
`--help`	boolean switch	—	no	Show offline command help.
`--output`	enum	json \| human	no	Select JSON or human output.
`--fields`	dot-paths	—	no	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: utilities:update.

Server request: PUT /utilities/templates/:id.

Shared server-guard guidance.

Consent

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

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

Update only supplied authoring fields on an owned template with --yes. Required --file is a regular JSON object at most 64 KiB containing only name, language, body, variables, usableOn, header, footer and buttons; sourceLibraryName and server metadata are refused. Field shapes match akedly utilities templates create --help. usableOn replaces both channels; supply both. A supplied language must be a non-empty string. Omitted fields are preserved; variables/buttons replace whole arrays, null header/footer or an empty buttons array clear those components. variables:null or [] clears every example, fallback and maxLength; names are re-derived from body, header and URL-button placeholders. Only draft, rejected or approved WhatsApp-enabled templates with no Meta submission are editable. Editing resets Akedly approval to draft and clears prior rejection/Meta submission state, and may notify Akedly staff. An ambiguous network or server failure is not retried; state may already have changed, so get the template before repeating. Read-only logins are refused. --dry-run validates and prints the request without contacting the server.

Worked examples

Synthetic CLI scenario

change authoring fields on an owned eligible template; editing resets Akedly approval/rejection and can notify staff.

akedly utilities templates update 64b000000000000000000001 --file template.json --yes

Input file: template.json (json).

json

{
  "body": "Your appointment is tomorrow."
}

Illustrative response (sensitive values omitted):

json

{
  "status": "success",
  "data": {
    "_id": "64b000000000000000000002",
    "name": "Order update",
    "language": "en",
    "body": "Your order {{1}} is ready.",
    "header": {
      "text": "Order"
    },
    "buttons": [],
    "variables": [
      {
        "name": "1",
        "example": "ORD-17"
      }
    ],
    "usableOn": {
      "whatsapp": true,
      "sms": false
    },
    "parameterFormat": "POSITIONAL",
    "akedlyStatus": "draft",
    "metaStatus": null,
    "metaTemplateId": null,
    "metaCategory": null,
    "suggestedCategory": null,
    "whatsappSubmitError": null,
    "whatsappResubmittable": false,
    "rejectionReason": null,
    "sourceLibraryName": null,
    "createdAt": "2050-01-02T03:04:05.000Z",
    "updatedAt": "2050-01-02T03:04:05.000Z"
  }
}

Synthetic example only; do not execute against a live account.

Additional command forms

akedly utilities templates update <id> --file <path> --yes

Input and file contracts

json

{
  "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 the id from akedly utilities templates 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-template-update",
        "requestTargets": [
          {
            "role": "body",
            "path": "$",
            "transform": "json-fields",
            "fileContract": "utility-template-update"
          }
        ],
        "schema": {
          "$schema": "https://json-schema.org/draft/2020-12/schema",
          "title": "Utility-template partial update document",
          "description": "Sparse JSON object replacing only supplied editable fields; at least one listed field is required by the CLI. usableOn must include both whatsapp and sms when supplied. name/body, when supplied, and language when supplied must be non-empty strings.",
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "minLength": 1,
              "pattern": "\\S"
            },
            "language": {
              "type": "string",
              "minLength": 1,
              "pattern": "\\S"
            },
            "body": {
              "type": "string",
              "minLength": 1,
              "pattern": "\\S"
            },
            "variables": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/authoringVariable"
              }
            },
            "usableOn": {
              "$ref": "#/$defs/usableOn"
            },
            "header": {
              "$ref": "#/$defs/header"
            },
            "footer": {
              "type": "string"
            },
            "buttons": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/button"
              }
            }
          },
          "minProperties": 1,
          "additionalProperties": false,
          "$defs": {
            "authoringVariable": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "example": {
                  "type": [
                    "string",
                    "number",
                    "boolean"
                  ]
                },
                "fallback": {
                  "type": "string"
                },
                "maxLength": {
                  "type": "integer",
                  "minimum": 1
                }
              },
              "additionalProperties": true
            },
            "usableOn": {
              "type": "object",
              "properties": {
                "whatsapp": {
                  "type": "boolean"
                },
                "sms": {
                  "type": "boolean"
                }
              },
              "required": [
                "whatsapp",
                "sms"
              ],
              "additionalProperties": false
            },
            "header": {
              "type": "object",
              "properties": {
                "text": {
                  "type": "string"
                }
              },
              "additionalProperties": true
            },
            "button": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "URL",
                    "PHONE_NUMBER",
                    "QUICK_REPLY"
                  ]
                },
                "text": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "phoneNumber": {
                  "type": "string"
                },
                "actionId": {
                  "type": "string"
                },
                "actionLabel": {
                  "type": "string"
                }
              },
              "additionalProperties": true
            }
          }
        },
        "localReaderSchema": {
          "$schema": "https://json-schema.org/draft/2020-12/schema",
          "type": "object",
          "properties": {
            "name": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                },
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                },
                {
                  "type": "object",
                  "additionalProperties": true
                },
                {
                  "type": "array",
                  "items": true
                }
              ]
            },
            "language": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                },
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                },
                {
                  "type": "object",
                  "additionalProperties": true
                },
                {
                  "type": "array",
                  "items": true
                }
              ]
            },
            "body": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                },
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                },
                {
                  "type": "object",
                  "additionalProperties": true
                },
                {
                  "type": "array",
                  "items": true
                }
              ]
            },
            "variables": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                },
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                },
                {
                  "type": "object",
                  "additionalProperties": true
                },
                {
                  "type": "array",
                  "items": true
                }
              ]
            },
            "usableOn": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                },
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                },
                {
                  "type": "object",
                  "additionalProperties": true
                },
                {
                  "type": "array",
                  "items": true
                }
              ]
            },
            "header": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                },
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                },
                {
                  "type": "object",
                  "additionalProperties": true
                },
                {
                  "type": "array",
                  "items": true
                }
              ]
            },
            "footer": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                },
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                },
                {
                  "type": "object",
                  "additionalProperties": true
                },
                {
                  "type": "array",
                  "items": true
                }
              ]
            },
            "buttons": {
              "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": [
            "name",
            "language",
            "body",
            "variables",
            "usableOn",
            "header",
            "footer",
            "buttons"
          ],
          "reader": "utilitytemplatewrites.js:authoringPlan",
          "type": "json-object",
          "exclusive": false,
          "mode": null,
          "trim": false,
          "writer": null,
          "minBytes": 0,
          "detectChanges": true,
          "fieldMappings": {
            "name": {
              "path": "name",
              "transform": "identity"
            },
            "language": {
              "path": "language",
              "transform": "identity"
            },
            "body": {
              "path": "body",
              "transform": "identity"
            },
            "variables": {
              "path": "variables",
              "transform": "identity"
            },
            "usableOn": {
              "path": "usableOn",
              "transform": "identity"
            },
            "header": {
              "path": "header",
              "transform": "identity"
            },
            "footer": {
              "path": "footer",
              "transform": "identity"
            },
            "buttons": {
              "path": "buttons",
              "transform": "identity"
            }
          }
        },
        "semanticSchema": {
          "$schema": "https://json-schema.org/draft/2020-12/schema",
          "title": "Utility-template partial update document",
          "description": "Sparse JSON object replacing only supplied editable fields; at least one listed field is required by the CLI. usableOn must include both whatsapp and sms when supplied. name/body, when supplied, and language when supplied must be non-empty strings.",
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "minLength": 1,
              "pattern": "\\S"
            },
            "language": {
              "type": "string",
              "minLength": 1,
              "pattern": "\\S"
            },
            "body": {
              "type": "string",
              "minLength": 1,
              "pattern": "\\S"
            },
            "variables": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/authoringVariable"
              }
            },
            "usableOn": {
              "$ref": "#/$defs/usableOn"
            },
            "header": {
              "$ref": "#/$defs/header"
            },
            "footer": {
              "type": "string"
            },
            "buttons": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/button"
              }
            }
          },
          "minProperties": 1,
          "additionalProperties": false,
          "$defs": {
            "authoringVariable": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "example": {
                  "type": [
                    "string",
                    "number",
                    "boolean"
                  ]
                },
                "fallback": {
                  "type": "string"
                },
                "maxLength": {
                  "type": "integer",
                  "minimum": 1
                }
              },
              "additionalProperties": true
            },
            "usableOn": {
              "type": "object",
              "properties": {
                "whatsapp": {
                  "type": "boolean"
                },
                "sms": {
                  "type": "boolean"
                }
              },
              "required": [
                "whatsapp",
                "sms"
              ],
              "additionalProperties": false
            },
            "header": {
              "type": "object",
              "properties": {
                "text": {
                  "type": "string"
                }
              },
              "additionalProperties": true
            },
            "button": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "URL",
                    "PHONE_NUMBER",
                    "QUICK_REPLY"
                  ]
                },
                "text": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "phoneNumber": {
                  "type": "string"
                },
                "actionId": {
                  "type": "string"
                },
                "actionLabel": {
                  "type": "string"
                }
              },
              "additionalProperties": true
            }
          }
        },
        "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-template-update",
          "contributors": [
            "file"
          ]
        },
        {
          "role": "body",
          "path": "body",
          "transform": "identity",
          "fileContract": "utility-template-update",
          "input": "file",
          "contributors": [
            "file"
          ],
          "fileKey": "body",
          "inputTransform": "json-fields"
        },
        {
          "role": "body",
          "path": "buttons",
          "transform": "identity",
          "fileContract": "utility-template-update",
          "input": "file",
          "contributors": [
            "file"
          ],
          "fileKey": "buttons",
          "inputTransform": "json-fields"
        },
        {
          "role": "body",
          "path": "footer",
          "transform": "identity",
          "fileContract": "utility-template-update",
          "input": "file",
          "contributors": [
            "file"
          ],
          "fileKey": "footer",
          "inputTransform": "json-fields"
        },
        {
          "role": "body",
          "path": "header",
          "transform": "identity",
          "fileContract": "utility-template-update",
          "input": "file",
          "contributors": [
            "file"
          ],
          "fileKey": "header",
          "inputTransform": "json-fields"
        },
        {
          "role": "body",
          "path": "language",
          "transform": "identity",
          "fileContract": "utility-template-update",
          "input": "file",
          "contributors": [
            "file"
          ],
          "fileKey": "language",
          "inputTransform": "json-fields"
        },
        {
          "role": "body",
          "path": "name",
          "transform": "identity",
          "fileContract": "utility-template-update",
          "input": "file",
          "contributors": [
            "file"
          ],
          "fileKey": "name",
          "inputTransform": "json-fields"
        },
        {
          "role": "body",
          "path": "usableOn",
          "transform": "identity",
          "fileContract": "utility-template-update",
          "input": "file",
          "contributors": [
            "file"
          ],
          "fileKey": "usableOn",
          "inputTransform": "json-fields"
        },
        {
          "role": "body",
          "path": "variables",
          "transform": "identity",
          "fileContract": "utility-template-update",
          "input": "file",
          "contributors": [
            "file"
          ],
          "fileKey": "variables",
          "inputTransform": "json-fields"
        }
      ]
    },
    {
      "name": "yes",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "yes",
        "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": "yes",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "yes",
          "contributors": [
            "yes"
          ]
        }
      ]
    },
    {
      "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-template-update",
      "contract": {
        "format": "json-object",
        "maxBytes": 65536,
        "regularFile": true,
        "fields": [
          "name",
          "language",
          "body",
          "variables",
          "usableOn",
          "header",
          "footer",
          "buttons"
        ],
        "reader": "utilitytemplatewrites.js:authoringPlan",
        "type": "json-object",
        "exclusive": false,
        "mode": null,
        "trim": false,
        "writer": null,
        "minBytes": 0,
        "detectChanges": true,
        "fieldMappings": {
          "name": {
            "path": "name",
            "transform": "identity"
          },
          "language": {
            "path": "language",
            "transform": "identity"
          },
          "body": {
            "path": "body",
            "transform": "identity"
          },
          "variables": {
            "path": "variables",
            "transform": "identity"
          },
          "usableOn": {
            "path": "usableOn",
            "transform": "identity"
          },
          "header": {
            "path": "header",
            "transform": "identity"
          },
          "footer": {
            "path": "footer",
            "transform": "identity"
          },
          "buttons": {
            "path": "buttons",
            "transform": "identity"
          }
        }
      },
      "schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": {
          "name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "array",
                "items": true
              }
            ]
          },
          "language": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "array",
                "items": true
              }
            ]
          },
          "body": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "array",
                "items": true
              }
            ]
          },
          "variables": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "array",
                "items": true
              }
            ]
          },
          "usableOn": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "array",
                "items": true
              }
            ]
          },
          "header": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "array",
                "items": true
              }
            ]
          },
          "footer": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "array",
                "items": true
              }
            ]
          },
          "buttons": {
            "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": "Utility-template partial update document",
            "description": "Sparse JSON object replacing only supplied editable fields; at least one listed field is required by the CLI. usableOn must include both whatsapp and sms when supplied. name/body, when supplied, and language when supplied must be non-empty strings.",
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "minLength": 1,
                "pattern": "\\S"
              },
              "language": {
                "type": "string",
                "minLength": 1,
                "pattern": "\\S"
              },
              "body": {
                "type": "string",
                "minLength": 1,
                "pattern": "\\S"
              },
              "variables": {
                "type": "array",
                "items": {
                  "$ref": "#/$defs/authoringVariable"
                }
              },
              "usableOn": {
                "$ref": "#/$defs/usableOn"
              },
              "header": {
                "$ref": "#/$defs/header"
              },
              "footer": {
                "type": "string"
              },
              "buttons": {
                "type": "array",
                "items": {
                  "$ref": "#/$defs/button"
                }
              }
            },
            "minProperties": 1,
            "additionalProperties": false,
            "$defs": {
              "authoringVariable": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "example": {
                    "type": [
                      "string",
                      "number",
                      "boolean"
                    ]
                  },
                  "fallback": {
                    "type": "string"
                  },
                  "maxLength": {
                    "type": "integer",
                    "minimum": 1
                  }
                },
                "additionalProperties": true
              },
              "usableOn": {
                "type": "object",
                "properties": {
                  "whatsapp": {
                    "type": "boolean"
                  },
                  "sms": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "whatsapp",
                  "sms"
                ],
                "additionalProperties": false
              },
              "header": {
                "type": "object",
                "properties": {
                  "text": {
                    "type": "string"
                  }
                },
                "additionalProperties": true
              },
              "button": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "URL",
                      "PHONE_NUMBER",
                      "QUICK_REPLY"
                    ]
                  },
                  "text": {
                    "type": "string"
                  },
                  "url": {
                    "type": "string"
                  },
                  "phoneNumber": {
                    "type": "string"
                  },
                  "actionId": {
                    "type": "string"
                  },
                  "actionLabel": {
                    "type": "string"
                  }
                },
                "additionalProperties": true
              }
            }
          }
        }
      ]
    }
  ],
  "wire": {
    "method": "PUT",
    "route": "/utilities/templates/:id",
    "query": {},
    "body": {},
    "ownerParams": []
  }
}

Response contract

Response fields outside the modeled stable fields may be passed through from the server.

The API response envelope is preserved by the CLI; stable fields are modeled and other server fields remain extensible.

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "status": {
        "const": "success"
      },
      "data": {
        "type": "object",
        "properties": {
          "_id": {
            "type": "string",
            "pattern": "^[a-fA-F0-9]{24}$"
          },
          "name": {
            "type": "string"
          },
          "language": {
            "type": "string"
          },
          "body": {
            "type": "string"
          },
          "header": {
            "type": "object",
            "properties": {
              "text": {
                "type": "string"
              }
            },
            "required": [
              "text"
            ],
            "additionalProperties": true
          },
          "footer": {
            "type": "string"
          },
          "buttons": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "enum": [
                    "URL",
                    "PHONE_NUMBER",
                    "QUICK_REPLY"
                  ]
                },
                "text": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "phoneNumber": {
                  "type": "string"
                },
                "actionId": {
                  "type": "string"
                },
                "actionLabel": {
                  "type": "string"
                }
              },
              "required": [
                "type",
                "text"
              ],
              "additionalProperties": true
            }
          },
          "variables": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "example": {
                  "type": [
                    "string",
                    "number",
                    "boolean"
                  ]
                },
                "fallback": {
                  "type": "string"
                },
                "maxLength": {
                  "type": "integer",
                  "minimum": 1
                }
              },
              "required": [
                "name",
                "example"
              ],
              "additionalProperties": true
            }
          },
          "usableOn": {
            "type": "object",
            "properties": {
              "whatsapp": {
                "type": "boolean"
              },
              "sms": {
                "type": "boolean"
              }
            },
            "required": [
              "whatsapp",
              "sms"
            ],
            "additionalProperties": true
          },
          "parameterFormat": {
            "type": "string"
          },
          "akedlyStatus": {
            "type": "string"
          },
          "metaStatus": {
            "type": [
              "string",
              "null"
            ]
          },
          "metaTemplateId": {
            "type": [
              "string",
              "null"
            ]
          },
          "metaCategory": {
            "type": [
              "string",
              "null"
            ]
          },
          "suggestedCategory": {
            "type": [
              "string",
              "null"
            ]
          },
          "whatsappSubmitError": {
            "type": [
              "string",
              "null"
            ]
          },
          "whatsappResubmittable": {
            "type": "boolean"
          },
          "rejectionReason": {
            "type": [
              "string",
              "null"
            ]
          },
          "sourceLibraryName": {
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "_id",
          "name",
          "language",
          "body",
          "variables",
          "usableOn",
          "parameterFormat",
          "akedlyStatus",
          "metaStatus",
          "metaTemplateId",
          "metaCategory",
          "suggestedCategory",
          "whatsappSubmitError",
          "whatsappResubmittable",
          "rejectionReason",
          "sourceLibraryName",
          "createdAt",
          "updatedAt"
        ],
        "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
  }
}

json

{
  "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": {
    "NOT_FOUND": "Run akedly utilities templates list and check the template id.",
    "NOT_EDITABLE": "Only draft, rejected or approved WhatsApp-enabled templates with no Meta submission are editable. Check akedly utilities templates get <id> before changing the file.",
    "SUBMISSION_IN_FLIGHT": "A Meta submission is in progress. Wait for details.retryAfterSeconds, then check akedly utilities templates get <id> before editing.",
    "DUPLICATE_NAME": "Run akedly utilities templates list and choose an unused name and language.",
    "NO_TEMPLATE_CHANNEL": "Enable at least one of usableOn.whatsapp or usableOn.sms in --file.",
    "UTILITY_SMS_REQUIRES_BYO": "Connect, test and activate an eligible BYO-SMS integration before enabling usableOn.sms. Check akedly byo-sms list and akedly whoami for BYO-SMS entitlement and granular pricing."
  },
  "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
  }
}

Own recovery guidance

Code	Hint
NOT_FOUND	Run akedly utilities templates list and check the template id.
NOT_EDITABLE	Only draft, rejected or approved WhatsApp-enabled templates with no Meta submission are editable. Check akedly utilities templates get <id> before changing the file.
SUBMISSION_IN_FLIGHT	A Meta submission is in progress. Wait for details.retryAfterSeconds, then check akedly utilities templates get <id> before editing.
DUPLICATE_NAME	Run akedly utilities templates list and choose an unused name and language.
NO_TEMPLATE_CHANNEL	Enable at least one of usableOn.whatsapp or usableOn.sms in `--file`.
UTILITY_SMS_REQUIRES_BYO	Connect, test and activate an eligible BYO-SMS integration before enabling usableOn.sms. Check akedly byo-sms list and akedly whoami for BYO-SMS entitlement and granular pricing.

Common error guidance.

utilities templates submit

place a draft or rejected template into Akedly staff review; this does not submit it to Meta.

When to use

place a draft or rejected template into Akedly staff review; this does not submit it to Meta.

How it works

Submit an existing owned template after reviewing lint blockers and Meta classification prediction. Requires confirmation.

Prerequisites

Authenticated account with utilities:update permission.
Writable owner account and explicit confirmation where required.
An owned draft or rejected template; lint findings reviewed, including possible Meta Marketing reclassification.

Expected outcome

Returns updated review status; may notify Akedly staff.

Next steps

Get template to confirm pending_review; wait for Akedly decision before Meta submission.

Usage

akedly utilities templates submit <id>

Inspect this command offline before preparing an operation:

akedly describe "utilities templates submit" --output json

Positional	Grammar	Usage guidance
<id>	^[a-fA-F0-9]{24}$	Use the id from akedly utilities templates list.

Flags

Flag	Type	Enum / range	Description
`--ksa`	boolean switch	—	Select the KSA deployment.
`--yes`	boolean switch	—	Confirm this action where consent is required.
`--dry-run`	boolean switch	—	Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
`--help`	boolean switch	—	Show offline command help.
`--output`	enum	json \| human	Select JSON or human output.
`--fields`	dot-paths	—	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: utilities:update.

Server request: POST /utilities/templates/:id/submit.

Shared server-guard guidance.

Consent

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

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

Submit an owned draft or rejected template for Akedly staff review with --yes. Before submitting, run akedly utilities templates lint --file <path> on the lint-compatible copy described below and review predictedOutcome. This saves pending_review and may notify Akedly staff; it does not itself submit to Meta. Fix the blockers in details.issues, save with akedly utilities templates update <id> --file <path> --yes, then run akedly utilities templates submit <id> --yes. For akedly utilities templates lint --file <path>, use a copy containing only name, language, body, variables (string examples), header, footer and buttons. Lint predictedOutcome predicts Meta, not Akedly approval. An ambiguous network or server failure is not retried; state may already have changed, so get the template before repeating. Read-only logins are refused. --dry-run validates and prints the request without contacting the server. Meta may reclassify a template as Marketing, which costs more per message than Utility; inspect lint predictedOutcome before submitting knowingly.

Worked examples

Synthetic CLI scenario

place a draft or rejected template into Akedly staff review; this does not submit it to Meta.

akedly utilities templates submit 64b000000000000000000001 --yes

Illustrative response (sensitive values omitted):

json

{
  "status": "success",
  "data": {
    "_id": "64b000000000000000000002",
    "name": "Order update",
    "language": "en",
    "body": "Your order {{1}} is ready.",
    "header": {
      "text": "Order"
    },
    "buttons": [],
    "variables": [
      {
        "name": "1",
        "example": "ORD-17"
      }
    ],
    "usableOn": {
      "whatsapp": true,
      "sms": false
    },
    "parameterFormat": "POSITIONAL",
    "akedlyStatus": "pending_review",
    "metaStatus": null,
    "metaTemplateId": null,
    "metaCategory": null,
    "suggestedCategory": null,
    "whatsappSubmitError": null,
    "whatsappResubmittable": false,
    "rejectionReason": null,
    "sourceLibraryName": null,
    "createdAt": "2050-01-02T03:04:05.000Z",
    "updatedAt": "2050-01-02T03:04:05.000Z"
  }
}

Synthetic example only; do not execute against a live account.

Additional command forms

akedly utilities templates submit <id> --yes

Input and file contracts

json

{
  "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 the id from akedly utilities templates 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": "yes",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "yes",
        "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": "yes",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "yes",
          "contributors": [
            "yes"
          ]
        }
      ]
    },
    {
      "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/templates/:id/submit",
    "query": {},
    "body": {},
    "ownerParams": []
  }
}

Response contract

Response fields outside the modeled stable fields may be passed through from the server.

The API response envelope is preserved by the CLI; stable fields are modeled and other server fields remain extensible.

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "status": {
        "const": "success"
      },
      "data": {
        "type": "object",
        "properties": {
          "_id": {
            "type": "string",
            "pattern": "^[a-fA-F0-9]{24}$"
          },
          "name": {
            "type": "string"
          },
          "language": {
            "type": "string"
          },
          "body": {
            "type": "string"
          },
          "header": {
            "type": "object",
            "properties": {
              "text": {
                "type": "string"
              }
            },
            "required": [
              "text"
            ],
            "additionalProperties": true
          },
          "footer": {
            "type": "string"
          },
          "buttons": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "enum": [
                    "URL",
                    "PHONE_NUMBER",
                    "QUICK_REPLY"
                  ]
                },
                "text": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "phoneNumber": {
                  "type": "string"
                },
                "actionId": {
                  "type": "string"
                },
                "actionLabel": {
                  "type": "string"
                }
              },
              "required": [
                "type",
                "text"
              ],
              "additionalProperties": true
            }
          },
          "variables": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "example": {
                  "type": [
                    "string",
                    "number",
                    "boolean"
                  ]
                },
                "fallback": {
                  "type": "string"
                },
                "maxLength": {
                  "type": "integer",
                  "minimum": 1
                }
              },
              "required": [
                "name",
                "example"
              ],
              "additionalProperties": true
            }
          },
          "usableOn": {
            "type": "object",
            "properties": {
              "whatsapp": {
                "type": "boolean"
              },
              "sms": {
                "type": "boolean"
              }
            },
            "required": [
              "whatsapp",
              "sms"
            ],
            "additionalProperties": true
          },
          "parameterFormat": {
            "type": "string"
          },
          "akedlyStatus": {
            "type": "string"
          },
          "metaStatus": {
            "type": [
              "string",
              "null"
            ]
          },
          "metaTemplateId": {
            "type": [
              "string",
              "null"
            ]
          },
          "metaCategory": {
            "type": [
              "string",
              "null"
            ]
          },
          "suggestedCategory": {
            "type": [
              "string",
              "null"
            ]
          },
          "whatsappSubmitError": {
            "type": [
              "string",
              "null"
            ]
          },
          "whatsappResubmittable": {
            "type": "boolean"
          },
          "rejectionReason": {
            "type": [
              "string",
              "null"
            ]
          },
          "sourceLibraryName": {
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "_id",
          "name",
          "language",
          "body",
          "variables",
          "usableOn",
          "parameterFormat",
          "akedlyStatus",
          "metaStatus",
          "metaTemplateId",
          "metaCategory",
          "suggestedCategory",
          "whatsappSubmitError",
          "whatsappResubmittable",
          "rejectionReason",
          "sourceLibraryName",
          "createdAt",
          "updatedAt"
        ],
        "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
  }
}

json

{
  "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": {
    "NOT_FOUND": "Run akedly utilities templates list and check the template id.",
    "NOT_SUBMITTABLE": "Only draft or rejected templates can enter Akedly review. Check akedly utilities templates get <id>.",
    "TEMPLATE_NOT_READY": "Fix the blockers in details.issues, save with akedly utilities templates update <id> --file <path> --yes, then run akedly utilities templates submit <id> --yes. For akedly utilities templates lint --file <path>, use a copy containing only name, language, body, variables (string examples), header, footer and buttons."
  },
  "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
  }
}

Own recovery guidance

Code	Hint
NOT_FOUND	Run akedly utilities templates list and check the template id.
NOT_SUBMITTABLE	Only draft or rejected templates can enter Akedly review. Check akedly utilities templates get <id>.
TEMPLATE_NOT_READY	Fix the blockers in details.issues, save with akedly utilities templates update <id> `--file` <path> `--yes`, then run akedly utilities templates submit <id> `--yes`. For akedly utilities templates lint `--file` <path>, use a copy containing only name, language, body, variables (string examples), header, footer and buttons.

Common error guidance.

utilities templates resubmit-meta

retry Meta submission for an Akedly-approved WhatsApp template whose previous submission failed or is absent.

When to use

retry Meta submission for an Akedly-approved WhatsApp template whose previous submission failed or is absent.

How it works

Ask server to submit; Meta and staff notification may be involved, with server cooldown and potentially a successful HTTP result containing submitted:false.

Prerequisites

Authenticated account with utilities:update permission.
Writable owner account and explicit confirmation where required.
An owned Akedly-approved WhatsApp-enabled template without a Meta submission; no active 60-second resubmission cooldown.

Expected outcome

Returns Meta submission outcome and current template state; success does not guarantee Meta approval.

Next steps

Inspect whatsappSubmitError/metaStatus; no_active_waba means connect WABA, blocked_by_lint requires content changes, cooldown requires waiting.

Usage

akedly utilities templates resubmit-meta <id>

Inspect this command offline before preparing an operation:

akedly describe "utilities templates resubmit-meta" --output json

Positional	Grammar	Usage guidance
<id>	^[a-fA-F0-9]{24}$	Use the id from akedly utilities templates list.

Flags

Flag	Type	Enum / range	Description
`--ksa`	boolean switch	—	Select the KSA deployment.
`--yes`	boolean switch	—	Confirm this action where consent is required.
`--dry-run`	boolean switch	—	Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
`--help`	boolean switch	—	Show offline command help.
`--output`	enum	json \| human	Select JSON or human output.
`--fields`	dot-paths	—	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: utilities:update.

Server request: POST /utilities/templates/:id/resubmit-meta.

Shared server-guard guidance.

Consent

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

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

Retry a real Meta submission for an Akedly-approved, WhatsApp-enabled template that has no Meta submission, with --yes. This contacts Meta and may notify Akedly staff. Akedly automatically attempts Meta submission for WhatsApp-enabled templates on approval; use resubmit-meta to retry when that submission failed. The server enforces a 60-second attempt cooldown: inspect details.retryAfterSeconds on RESUBMIT_COOLDOWN. HTTP 200 can contain submitted:false, data.whatsappSubmitError and retryAfterSeconds; that is not Meta submission or approval. Inspect those fields and data.metaStatus before deciding what to do. For these customer templates, data.whatsappSubmitError no_active_waba means connect a WhatsApp Business Account first: check akedly whatsapp status, then use akedly whatsapp connect for the dashboard sign-up link. blocked_by_lint: <ruleIds> cannot be fixed by retrying; change the content with akedly utilities templates update <id> --file <path> --yes, then run akedly utilities templates submit <id> --yes. Other values report the Meta submission failure reason. Uses a 90-second request timeout. An ambiguous network or server failure is not retried; state or Meta may already have changed, so get the template before repeating. Read-only logins are refused. --dry-run validates and prints the request without contacting the server.

Worked examples

Synthetic CLI scenario

retry Meta submission for an Akedly-approved WhatsApp template whose previous submission failed or is absent.

akedly utilities templates resubmit-meta 64b000000000000000000001 --yes

Illustrative response (sensitive values omitted):

json

{
  "status": "success",
  "submitted": false,
  "retryAfterSeconds": 60,
  "data": {
    "_id": "64b000000000000000000002",
    "metaStatus": null,
    "whatsappSubmitError": "no_active_waba",
    "whatsappResubmittable": true
  }
}

Synthetic example only; do not execute against a live account.

Additional command forms

akedly utilities templates resubmit-meta <id> --yes

Input and file contracts

json

{
  "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 the id from akedly utilities templates 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": "yes",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "yes",
        "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": "yes",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "yes",
          "contributors": [
            "yes"
          ]
        }
      ]
    },
    {
      "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/templates/:id/resubmit-meta",
    "query": {},
    "body": {},
    "ownerParams": []
  }
}

Response contract

Response fields outside the modeled stable fields may be passed through from the server.

The API response envelope is preserved by the CLI; stable fields are modeled and other server fields remain extensible.

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "status": {
        "const": "success"
      },
      "data": {
        "type": "object",
        "properties": {
          "_id": {
            "type": "string"
          },
          "metaStatus": {
            "type": [
              "string",
              "null"
            ]
          },
          "whatsappSubmitError": {
            "type": [
              "string",
              "null"
            ]
          },
          "whatsappResubmittable": {
            "type": "boolean"
          }
        },
        "required": [],
        "additionalProperties": true
      },
      "submitted": {
        "type": "boolean"
      },
      "retryAfterSeconds": {
        "type": "integer",
        "minimum": 0
      }
    },
    "required": [
      "status",
      "data",
      "submitted"
    ],
    "additionalProperties": true
  },
  "variants": [
    {
      "when": "Meta accepted the submit request; this remains distinct from Meta approval.",
      "example": {
        "status": "success",
        "submitted": true,
        "data": {
          "_id": "64b000000000000000000002",
          "metaStatus": "PENDING",
          "whatsappSubmitError": null,
          "whatsappResubmittable": false
        }
      },
      "title": "Meta accepted the submit request; this remains distinct from Meta approval.",
      "notes": []
    },
    {
      "when": "Server refused this attempt during the cooldown but returned HTTP 200.",
      "example": {
        "status": "success",
        "submitted": false,
        "retryAfterSeconds": 42,
        "data": {
          "_id": "64b000000000000000000002",
          "metaStatus": null,
          "whatsappSubmitError": null,
          "whatsappResubmittable": true
        }
      },
      "title": "Server refused this attempt during the cooldown but returned HTTP 200.",
      "notes": []
    }
  ],
  "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
  }
}

json

{
  "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": {
    "NOT_FOUND": "Run akedly utilities templates list and check the template id.",
    "NOT_RESUBMITTABLE": "Check akedly utilities templates get <id>; resubmission requires Akedly approval, WhatsApp enabled and no Meta submission.",
    "RESUBMIT_COOLDOWN": "Wait for details.retryAfterSeconds, then check akedly utilities templates get <id> before another Meta submission."
  },
  "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
  }
}

Own recovery guidance

Code	Hint
NOT_FOUND	Run akedly utilities templates list and check the template id.
NOT_RESUBMITTABLE	Check akedly utilities templates get <id>; resubmission requires Akedly approval, WhatsApp enabled and no Meta submission.
RESUBMIT_COOLDOWN	Wait for details.retryAfterSeconds, then check akedly utilities templates get <id> before another Meta submission.

Common error guidance.

utilities templates dev-approve

bypass Akedly review for development by approving an owned non-approved template; server refuses production.

When to use

bypass Akedly review for development by approving an owned non-approved template; server refuses production.

How it works

Approve with explicit confirmation; WhatsApp approval may trigger Meta submission and notification emails.

Prerequisites

Authenticated account with utilities:update permission.
Writable owner account and explicit confirmation where required.
An owned non-approved template and development server environment; the server refuses production.

Expected outcome

Returns approval and Meta submission state, which are distinct.

Next steps

Inspect Meta status/error; use only development context, and resubmit-meta only after understanding failure/cooldown.

Usage

akedly utilities templates dev-approve <id>

Inspect this command offline before preparing an operation:

akedly describe "utilities templates dev-approve" --output json

Positional	Grammar	Usage guidance
<id>	^[a-fA-F0-9]{24}$	Use the id from akedly utilities templates list.

Flags

Flag	Type	Enum / range	Description
`--ksa`	boolean switch	—	Select the KSA deployment.
`--yes`	boolean switch	—	Confirm this action where consent is required.
`--dry-run`	boolean switch	—	Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
`--help`	boolean switch	—	Show offline command help.
`--output`	enum	json \| human	Select JSON or human output.
`--fields`	dot-paths	—	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: utilities:update.

Server request: POST /utilities/templates/:id/dev-approve.

Shared server-guard guidance.

Consent

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

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

Approve an owned non-approved template for development with --yes, bypassing the Akedly admin review queue. The server refuses production with DEV_ONLY; the CLI does not guess the server environment. This can make a real Meta submission for WhatsApp and schedules owner/consented-recipient notification emails. Akedly approval does not guarantee Meta submission or approval; inspect data.metaStatus and data.whatsappSubmitError. Akedly automatically attempts Meta submission for WhatsApp-enabled templates on approval; use resubmit-meta to retry when that submission failed. For these customer templates, data.whatsappSubmitError no_active_waba means connect a WhatsApp Business Account first: check akedly whatsapp status, then use akedly whatsapp connect for the dashboard sign-up link. blocked_by_lint: <ruleIds> cannot be fixed by retrying; change the content with akedly utilities templates update <id> --file <path> --yes, then run akedly utilities templates submit <id> --yes. Other values report the Meta submission failure reason. Uses a 90-second request timeout. An ambiguous network or server failure is not retried; state or Meta may already have changed, so get the template before repeating. Read-only logins are refused. --dry-run validates and prints the request without contacting the server.

Worked examples

Synthetic CLI scenario

bypass Akedly review for development by approving an owned non-approved template; server refuses production.

akedly utilities templates dev-approve 64b000000000000000000001 --yes

Illustrative response (sensitive values omitted):

json

{
  "status": "success",
  "data": {
    "_id": "64b000000000000000000002",
    "name": "Order update",
    "language": "en",
    "body": "Your order {{1}} is ready.",
    "header": {
      "text": "Order"
    },
    "buttons": [],
    "variables": [
      {
        "name": "1",
        "example": "ORD-17"
      }
    ],
    "usableOn": {
      "whatsapp": true,
      "sms": false
    },
    "parameterFormat": "POSITIONAL",
    "akedlyStatus": "approved",
    "metaStatus": null,
    "metaTemplateId": null,
    "metaCategory": null,
    "suggestedCategory": null,
    "whatsappSubmitError": null,
    "whatsappResubmittable": false,
    "rejectionReason": null,
    "sourceLibraryName": null,
    "createdAt": "2050-01-02T03:04:05.000Z",
    "updatedAt": "2050-01-02T03:04:05.000Z"
  }
}

Synthetic example only; do not execute against a live account.

Additional command forms

akedly utilities templates dev-approve <id> --yes

Input and file contracts

json

{
  "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 the id from akedly utilities templates 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": "yes",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "yes",
        "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": "yes",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "yes",
          "contributors": [
            "yes"
          ]
        }
      ]
    },
    {
      "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/templates/:id/dev-approve",
    "query": {},
    "body": {},
    "ownerParams": []
  }
}

Response contract

Response fields outside the modeled stable fields may be passed through from the server.

The API response envelope is preserved by the CLI; stable fields are modeled and other server fields remain extensible.

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "status": {
        "const": "success"
      },
      "data": {
        "type": "object",
        "properties": {
          "_id": {
            "type": "string",
            "pattern": "^[a-fA-F0-9]{24}$"
          },
          "name": {
            "type": "string"
          },
          "language": {
            "type": "string"
          },
          "body": {
            "type": "string"
          },
          "header": {
            "type": "object",
            "properties": {
              "text": {
                "type": "string"
              }
            },
            "required": [
              "text"
            ],
            "additionalProperties": true
          },
          "footer": {
            "type": "string"
          },
          "buttons": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "enum": [
                    "URL",
                    "PHONE_NUMBER",
                    "QUICK_REPLY"
                  ]
                },
                "text": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "phoneNumber": {
                  "type": "string"
                },
                "actionId": {
                  "type": "string"
                },
                "actionLabel": {
                  "type": "string"
                }
              },
              "required": [
                "type",
                "text"
              ],
              "additionalProperties": true
            }
          },
          "variables": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "example": {
                  "type": [
                    "string",
                    "number",
                    "boolean"
                  ]
                },
                "fallback": {
                  "type": "string"
                },
                "maxLength": {
                  "type": "integer",
                  "minimum": 1
                }
              },
              "required": [
                "name",
                "example"
              ],
              "additionalProperties": true
            }
          },
          "usableOn": {
            "type": "object",
            "properties": {
              "whatsapp": {
                "type": "boolean"
              },
              "sms": {
                "type": "boolean"
              }
            },
            "required": [
              "whatsapp",
              "sms"
            ],
            "additionalProperties": true
          },
          "parameterFormat": {
            "type": "string"
          },
          "akedlyStatus": {
            "type": "string"
          },
          "metaStatus": {
            "type": [
              "string",
              "null"
            ]
          },
          "metaTemplateId": {
            "type": [
              "string",
              "null"
            ]
          },
          "metaCategory": {
            "type": [
              "string",
              "null"
            ]
          },
          "suggestedCategory": {
            "type": [
              "string",
              "null"
            ]
          },
          "whatsappSubmitError": {
            "type": [
              "string",
              "null"
            ]
          },
          "whatsappResubmittable": {
            "type": "boolean"
          },
          "rejectionReason": {
            "type": [
              "string",
              "null"
            ]
          },
          "sourceLibraryName": {
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "_id",
          "name",
          "language",
          "body",
          "variables",
          "usableOn",
          "parameterFormat",
          "akedlyStatus",
          "metaStatus",
          "metaTemplateId",
          "metaCategory",
          "suggestedCategory",
          "whatsappSubmitError",
          "whatsappResubmittable",
          "rejectionReason",
          "sourceLibraryName",
          "createdAt",
          "updatedAt"
        ],
        "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
  }
}

json

{
  "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": {
    "ALREADY_APPROVED": "Check akedly utilities templates get <id> and inspect data.whatsappResubmittable; use resubmit-meta only when it is true.",
    "DEV_ONLY": "This server disables shortcut approval. Use akedly utilities templates submit <id> --yes for Akedly review."
  },
  "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
  }
}

Own recovery guidance

Code	Hint
ALREADY_APPROVED	Check akedly utilities templates get <id> and inspect data.whatsappResubmittable; use resubmit-meta only when it is true.
DEV_ONLY	This server disables shortcut approval. Use akedly utilities templates submit <id> `--yes` for Akedly review.

Common error guidance.

utilities templates delete

remove an owned draft or rejected template from Akedly; this does not remove anything from Meta.

When to use

remove an owned draft or rejected template from Akedly; this does not remove anything from Meta.

How it works

Delete one eligible owned template after checking its state; pending notification may block deletion. Requires confirmation.

Prerequisites

Authenticated account with utilities:delete permission.
Writable owner account and explicit confirmation where required.
An owned draft or rejected template with no pending status notification.

Expected outcome

Returns server deletion result.

Next steps

Verify with templates list; do not retry an ambiguous deletion before checking.

Usage

akedly utilities templates delete <id>

Inspect this command offline before preparing an operation:

akedly describe "utilities templates delete" --output json

Positional	Grammar	Usage guidance
<id>	^[a-fA-F0-9]{24}$	Use the id from akedly utilities templates list.

Flags

Flag	Type	Enum / range	Description
`--ksa`	boolean switch	—	Select the KSA deployment.
`--yes`	boolean switch	—	Confirm this action where consent is required.
`--dry-run`	boolean switch	—	Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
`--help`	boolean switch	—	Show offline command help.
`--output`	enum	json \| human	Select JSON or human output.
`--fields`	dot-paths	—	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: utilities:delete.

Server request: DELETE /utilities/templates/:id.

Shared server-guard guidance.

Consent

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

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

Delete an owned draft or rejected template from Akedly with --yes. A pending template-status notification can block deletion. This is local deletion, not deletion at Meta. An ambiguous network or server failure is not retried; get the template before repeating. Read-only logins are refused. --dry-run validates and prints the request without contacting the server.

Worked examples

Synthetic CLI scenario

remove an owned draft or rejected template from Akedly; this does not remove anything from Meta.

akedly utilities templates delete 64b000000000000000000001 --yes

Illustrative response (sensitive values omitted):

json

{
  "status": "success",
  "data": {
    "deleted": true
  }
}

Resource identifiers and records are fictional prerequisites, not claims that these resources exist.

Additional command forms

akedly utilities templates delete <id> --yes

Input and file contracts

json

{
  "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 the id from akedly utilities templates 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": "yes",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "yes",
        "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": "yes",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "yes",
          "contributors": [
            "yes"
          ]
        }
      ]
    },
    {
      "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": "DELETE",
    "route": "/utilities/templates/:id",
    "query": {},
    "body": {},
    "ownerParams": []
  }
}

Response contract

Response fields outside the modeled stable fields may be passed through from the server.

The API response envelope is preserved by the CLI; stable fields are modeled and other server fields remain extensible.

json

{
  "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": {
    "NOT_FOUND": "Run akedly utilities templates list and check the template id.",
    "NOT_DELETABLE": "Only draft or rejected templates without a pending status notification can be deleted. Check akedly utilities templates get <id>."
  },
  "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
  }
}

Own recovery guidance

Code	Hint
NOT_FOUND	Run akedly utilities templates list and check the template id.
NOT_DELETABLE	Only draft or rejected templates without a pending status notification can be deleted. Check akedly utilities templates get <id>.

Common error guidance.

utilities templates test-send

send a real chargeable one-channel template test to validate template rendering/provider acceptance; it does not exercise the production WhatsApp-to-SMS fallback path.

When to use

After an eligible approved template and active pipeline are configured, when checking that one selected channel accepts a test message.
Do not use this test to prove the production WhatsApp fallback path; test-send transactions are excluded from that fallback service.

How it works

The server chooses a usable account API key scoped to the target pipeline for admission/attribution; it refuses the send if no usable scoped key exists.
The server renders and sends only the explicitly selected channel (SMS or WhatsApp); test-send does not fall back from WhatsApp to SMS.
The real send may charge, obeys daily test-send, quota and spend-cap limits, and a provider acceptance is not proof of handset delivery.

Prerequisites

Authenticated account with utilities:send permission.
Writable owner account and explicit confirmation where required.
An owned approved/send-ready template; a valid destination; eligible WhatsApp or BYO-SMS setup; available quota/balance; --yes. Pipeline must be owned and active if specified.
The server must find a usable account API key scoped to the target pipeline for admission and attribution; if it cannot, the send is refused.

Expected outcome

A one-channel test-send transaction with provider acceptance state. It may charge and it does not prove handset delivery or exercise production WhatsApp-to-SMS fallback.

Next steps

On timeout retain same key and inputs; inspect messages list/get before recovery. Do not start a new operation.

Usage

akedly utilities templates test-send <id>

Inspect this command offline before preparing an operation:

akedly describe "utilities templates test-send" --output json

Positional	Grammar	Usage guidance
<id>	^[a-fA-F0-9]{24}$	Use the id from akedly utilities templates list.

Flags

Flag	Type	Enum / range	Description
`--ksa`	boolean switch	—	Select the KSA deployment.
`--phone-number`	text	—	Command-specific option; see the full command details below. Manifest body field: phone.
`--pipeline-id`	id	—	Command-specific option; see the full command details below. Manifest body field: pipelineId.
`--channel`	enum	sms \| whatsapp	Command-specific option; see the full command details below. Manifest body field: channel.
`--values-file`	text	—	Command-specific option; see the full command details below. Manifest body field: variableValues.
`--idempotency-key`	text	—	Command-specific option; see the full command details below. Manifest body field: idempotencyKey.
`--operation-fingerprint`	text	—	Command-specific option; see the full command details below. Manifest body field: operationFingerprint.
`--yes`	boolean switch	—	Confirm this action where consent is required.
`--dry-run`	boolean switch	—	Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
`--help`	boolean switch	—	Show offline command help.
`--output`	enum	json \| human	Select JSON or human output.
`--fields`	dot-paths	—	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: utilities:send.

Server request: POST /utilities/templates/:id/test-send.

Shared server-guard guidance.

Consent

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

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

Send a real, chargeable utility-template test with --yes; use only your own recipient number. --channel is sms or whatsapp (server default sms). Optional --phone-number must be E.164; omission uses the account phone. Optional --pipeline-id is a 24-hex active non-sandbox utility pipeline id; when omitted, the server selects one. A usable account API key selected by the server is required for that pipeline. --values-file is a regular JSON object at most 64 KiB mapping variable names to strings, finite numbers or booleans; 0, false and empty strings are preserved, but an empty string uses the stored fallback or fails rendering. SMS requires eligible BYO-SMS; WhatsApp requires the channel enabled, Akedly approval and Meta readiness. Region, suppression, quota and spend-cap rules remain server-owned. The account-wide daily limit is 10 persisted test-send transactions from server-local midnight, including failed attempts. Provider acceptance is not handset delivery; SMS bills immediately and WhatsApp billing is deferred, with possible later configured fallback. Uses a 60-second request timeout and no automatic ambiguous retry. A key is generated once per plan and included in the request and recovery error details; pass --idempotency-key to retain it. Supplied keys and optional --operation-fingerprint are separate trimmed 1-255-character values; no fingerprint is generated. Keep the same key and original inputs for recovery, and inspect akedly utilities messages list and akedly utilities messages get <transactionID> before retrying. Replay is bounded, not an unlimited safe-resend guarantee; unresolved dispatches may require support. Do not start a fresh operation merely because the CLI timed out. Read-only logins are refused. --dry-run validates and prints the planned key/body without credentials, consent or any request. TEST_SEND_LIMIT reports that the daily limit was reached but supplies no reset time; do not infer a retry timestamp from it.

Worked examples

Synthetic CLI scenario

exercise an approved utility template by sending a real message to a recipient; the operation may charge and fallback.

akedly utilities templates test-send 64b000000000000000000001 --phone-number +201234567890 --channel whatsapp --yes --idempotency-key utility-test-example-0001 --values-file values.json

Input file: values.json (json).

json

{}

Illustrative response (sensitive values omitted):

json

{
  "status": "success",
  "message": "Test WhatsApp sent",
  "data": {
    "transactionID": "txn_example_20500102",
    "status": "Pending",
    "channel": "whatsapp",
    "provider": "meta-cloud",
    "recipient": "+201234567890",
    "customerUserId": null,
    "wamid": "wamid.example.20500102",
    "billed": false,
    "billing": {
      "status": "deferred"
    }
  }
}

Synthetic example only; do not execute against a live account.

Additional command forms

akedly utilities templates test-send <id> --phone-number <number> --pipeline-id <id> --values-file <path> --yes

Input and file contracts

json

{
  "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 the id from akedly utilities templates 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": "phone-number",
      "schema": {
        "type": "string",
        "pattern": "^\\+[1-9]\\d{6,14}$"
      },
      "required": false,
      "wire": [
        {
          "path": "phone",
          "transform": "identity",
          "role": "body",
          "input": "phone-number",
          "contributors": [
            "phone-number"
          ]
        }
      ],
      "validation": {
        "syntax": "E.164: + followed by 7–15 digits, first digit nonzero."
      }
    },
    {
      "name": "pipeline-id",
      "schema": {
        "type": "string",
        "pattern": "^[a-fA-F0-9]{24}$"
      },
      "required": false,
      "wire": [
        {
          "path": "pipelineId",
          "transform": "identity",
          "role": "body",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "validation": {
        "syntax": "24-digit hexadecimal object ID."
      }
    },
    {
      "name": "channel",
      "schema": {
        "type": "string",
        "enum": [
          "sms",
          "whatsapp"
        ]
      },
      "required": false,
      "wire": [
        {
          "path": "channel",
          "transform": "identity",
          "role": "body",
          "input": "channel",
          "contributors": [
            "channel"
          ]
        }
      ]
    },
    {
      "name": "values-file",
      "schema": {
        "type": "string"
      },
      "required": false,
      "input": {
        "role": "input-file",
        "contract": "template-values",
        "requestTargets": [
          {
            "role": "body",
            "path": "variableValues",
            "transform": "json-object"
          }
        ],
        "schema": {
          "$schema": "https://json-schema.org/draft/2020-12/schema",
          "title": "Utility-template send-time values",
          "description": "JSON object mapping template variable names to string, finite number or boolean values. Variable keys depend on the selected template; the CLI rejects nested objects, arrays and non-finite numbers.",
          "type": "object",
          "additionalProperties": {
            "type": [
              "string",
              "number",
              "boolean"
            ]
          }
        },
        "localReaderSchema": {
          "$schema": "https://json-schema.org/draft/2020-12/schema",
          "type": "object",
          "additionalProperties": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              }
            ]
          }
        },
        "fileContract": {
          "format": "json-object",
          "maxBytes": 65536,
          "regularFile": true,
          "valueTypes": [
            "string",
            "finite-number",
            "boolean"
          ],
          "reader": "utilitytemplatesend.js:templates test-send",
          "type": "json-object",
          "exclusive": false,
          "mode": null,
          "trim": false,
          "writer": null,
          "minBytes": 0,
          "detectChanges": true,
          "fieldMappings": {}
        },
        "semanticSchema": {
          "$schema": "https://json-schema.org/draft/2020-12/schema",
          "title": "Utility-template send-time values",
          "description": "JSON object mapping template variable names to string, finite number or boolean values. Variable keys depend on the selected template; the CLI rejects nested objects, arrays and non-finite numbers.",
          "type": "object",
          "additionalProperties": {
            "type": [
              "string",
              "number",
              "boolean"
            ]
          }
        },
        "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": "values-file",
          "inputRole": "input-file",
          "transform": "identity",
          "fileContract": "template-values",
          "contributors": [
            "values-file"
          ]
        },
        {
          "role": "body",
          "path": "variableValues",
          "transform": "json-object",
          "input": "values-file",
          "contributors": [
            "values-file"
          ],
          "fileContract": "template-values"
        }
      ]
    },
    {
      "name": "idempotency-key",
      "schema": {
        "type": "string",
        "pattern": "^\\s*\\S(?:[\\s\\S]{0,253}\\S)?\\s*$"
      },
      "required": false,
      "input": {
        "role": "handler-built",
        "targets": [
          {
            "role": "body",
            "path": "idempotencyKey",
            "transform": "trim"
          }
        ],
        "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": "body",
          "path": "idempotencyKey",
          "transform": "trim",
          "input": "idempotency-key",
          "contributors": [
            "idempotency-key"
          ]
        }
      ],
      "validation": {
        "syntax": "After trimming, length must be 1–255 characters."
      }
    },
    {
      "name": "operation-fingerprint",
      "schema": {
        "type": "string",
        "pattern": "^\\s*\\S(?:[\\s\\S]{0,253}\\S)?\\s*$"
      },
      "required": false,
      "input": {
        "role": "handler-built",
        "targets": [
          {
            "role": "body",
            "path": "operationFingerprint",
            "transform": "trim"
          }
        ],
        "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": "body",
          "path": "operationFingerprint",
          "transform": "trim",
          "input": "operation-fingerprint",
          "contributors": [
            "operation-fingerprint"
          ]
        }
      ],
      "validation": {
        "syntax": "After trimming, length must be 1–255 characters."
      }
    },
    {
      "name": "yes",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "yes",
        "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": "yes",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "yes",
          "contributors": [
            "yes"
          ]
        }
      ]
    },
    {
      "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": "template-values",
      "contract": {
        "format": "json-object",
        "maxBytes": 65536,
        "regularFile": true,
        "valueTypes": [
          "string",
          "finite-number",
          "boolean"
        ],
        "reader": "utilitytemplatesend.js:templates test-send",
        "type": "json-object",
        "exclusive": false,
        "mode": null,
        "trim": false,
        "writer": null,
        "minBytes": 0,
        "detectChanges": true,
        "fieldMappings": {}
      },
      "schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "additionalProperties": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "number"
            },
            {
              "type": "boolean"
            }
          ]
        }
      },
      "uses": [
        {
          "flag": "values-file",
          "role": "input-file",
          "purpose": null,
          "semanticSchema": {
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "title": "Utility-template send-time values",
            "description": "JSON object mapping template variable names to string, finite number or boolean values. Variable keys depend on the selected template; the CLI rejects nested objects, arrays and non-finite numbers.",
            "type": "object",
            "additionalProperties": {
              "type": [
                "string",
                "number",
                "boolean"
              ]
            }
          }
        }
      ]
    }
  ],
  "wire": {
    "method": "POST",
    "route": "/utilities/templates/:id/test-send",
    "query": {},
    "body": {
      "phone-number": [
        {
          "path": "phone",
          "transform": "identity",
          "role": "body",
          "input": "phone-number",
          "contributors": [
            "phone-number"
          ]
        }
      ],
      "pipeline-id": [
        {
          "path": "pipelineId",
          "transform": "identity",
          "role": "body",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "channel": [
        {
          "path": "channel",
          "transform": "identity",
          "role": "body",
          "input": "channel",
          "contributors": [
            "channel"
          ]
        }
      ]
    },
    "ownerParams": []
  }
}

Response contract

Response fields outside the modeled stable fields may be passed through from the server.

The API response envelope is preserved by the CLI; stable fields are modeled and other server fields remain extensible.

This command never verifies the production WhatsApp failure-to-SMS fallback: the fallback service skips utility.testSend transactions.

The successful API data carries string transactionID/status plus selected channel/provider and channel-specific acceptance/billing fields. It is not a production fallback test.

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "status": {
        "const": "success"
      },
      "data": {
        "type": "object",
        "properties": {
          "transactionID": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "channel": {
            "enum": [
              "sms",
              "whatsapp"
            ]
          },
          "provider": {
            "type": "string"
          },
          "recipient": {
            "type": "string"
          },
          "customerUserId": {
            "type": [
              "string",
              "null"
            ]
          },
          "wamid": {
            "type": "string"
          },
          "segments": {
            "type": "integer"
          },
          "encoding": {
            "type": "string"
          },
          "billed": {
            "type": "boolean"
          },
          "billing": {
            "type": "object",
            "properties": {},
            "required": [],
            "additionalProperties": true
          },
          "billingPending": {
            "type": "boolean"
          },
          "submissionStatus": {
            "type": "string"
          },
          "providerSmsId": {
            "type": [
              "string",
              "null"
            ]
          },
          "submittedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ]
          },
          "failureReason": {
            "type": [
              "string",
              "null"
            ]
          },
          "certainty": {
            "type": "string"
          },
          "operationReplayable": {
            "type": "boolean"
          }
        },
        "required": [
          "transactionID",
          "status",
          "channel",
          "provider",
          "recipient"
        ],
        "additionalProperties": true
      },
      "message": {
        "type": "string"
      }
    },
    "required": [
      "status",
      "data"
    ],
    "additionalProperties": true
  },
  "variants": [
    {
      "when": "SMS provider accepted the send; no WhatsApp-to-SMS production fallback is exercised by this test-send path.",
      "example": {
        "status": "success",
        "message": "Test SMS accepted by provider",
        "data": {
          "transactionID": "txn_example_20500103",
          "status": "Successful",
          "channel": "sms",
          "provider": "own-sms",
          "recipient": "+201234567890",
          "customerUserId": null,
          "segments": 1,
          "encoding": "GSM-7",
          "billed": true,
          "billing": {
            "status": "success"
          }
        }
      },
      "title": "SMS provider accepted the send; no WhatsApp-to-SMS production fallback is exercised by this test-send path.",
      "notes": []
    }
  ],
  "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
  }
}

json

{
  "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": {
    "TEMPLATE_NOT_FOUND": "Run akedly utilities templates list and check the template id.",
    "INVALID_PHONE": "Pass --phone-number with your own valid E.164 number; omit it only when the account has a verified phone. If the saved phone is missing, complete your profile in the dashboard or ask Akedly support to correct it.",
    "NO_UTILITY_PIPELINE": "Create a utility pipeline with akedly pipelines create --product utility --name <name>, activate it with akedly pipelines update <id> --status active --yes, then supply --pipeline-id.",
    "TEMPLATE_NOT_APPROVED": "Check akedly utilities templates get <id>; submit the stored draft or rejected template for Akedly review before sending.",
    "TEMPLATE_NOT_SMS": "Check data.usableOn in akedly utilities templates get <id>; the template must allow SMS.",
    "TEMPLATE_NOT_WHATSAPP_READY": "Check akedly utilities templates get <id> for Akedly approval, WhatsApp usability and data.metaStatus. Use resubmit-meta only when data.whatsappResubmittable is true.",
    "WHATSAPP_NOT_ENABLED": "Check the utility pipeline and enable WhatsApp with akedly utilities pipelines channels set <id> --file <path>.",
    "TEMPLATE_MISSING_VARIABLE": "Supply the missing values through --values-file; use akedly utilities templates get <id> to inspect variables and fallbacks.",
    "RECIPIENT_SUPPRESSED": "Check akedly utilities suppressions list and respect the recipient opt-out; do not repeat the send to bypass suppression.",
    "UTILITY_SMS_REQUIRES_BYO": "Check akedly byo-sms list, active tested integration coverage and the pipeline byoSms setting; utility SMS requires eligible BYO-SMS.",
    "UTILITY_SMS_COUNTRY_NOT_ROUTED": "Check the selected BYO-SMS integration coverage for this destination with akedly byo-sms get <id>.",
    "UTILITY_SMS_PROVIDER_NOT_READY": "Check akedly byo-sms get <id> and complete the selected provider setup before sending.",
    "IDEMPOTENCY_KEY_REUSE": "Keep the original idempotency key with exactly the original template id and flags (--pipeline-id, --channel, --phone-number, --values-file and --operation-fingerprint, each supplied or omitted as before). Inspect akedly utilities messages list before deciding on a different operation.",
    "IDEMPOTENCY_IN_PROGRESS": "The existing operation is still processing. Keep its key and inputs; inspect akedly utilities messages list before retrying.",
    "IDEMPOTENCY_OUTCOME_UNKNOWN": "Keep the key and inputs. Inspect akedly utilities messages list and get <transactionID>, then contact Akedly support before retrying; do not start a new operation.",
    "TEMPLATE_VAR_MISSING": "No message was sent. Fill every required variable in --values-file; inspect variables and fallbacks with akedly utilities templates get <id>.",
    "no_active_waba": "No message was sent. An active connected WhatsApp Business Account is required; use --channel sms if ready, or run akedly whatsapp connect for the dashboard connection link."
  },
  "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
  }
}

Own recovery guidance

Code	Hint
TEMPLATE_NOT_FOUND	Run akedly utilities templates list and check the template id.
INVALID_PHONE	Pass `--phone-number` with your own valid E.164 number; omit it only when the account has a verified phone. If the saved phone is missing, complete your profile in the dashboard or ask Akedly support to correct it.
NO_UTILITY_PIPELINE	Create a utility pipeline with akedly pipelines create `--product` utility `--name` <name>, activate it with akedly pipelines update <id> `--status` active `--yes`, then supply `--pipeline-id`.
TEMPLATE_NOT_APPROVED	Check akedly utilities templates get <id>; submit the stored draft or rejected template for Akedly review before sending.
TEMPLATE_NOT_SMS	Check data.usableOn in akedly utilities templates get <id>; the template must allow SMS.
TEMPLATE_NOT_WHATSAPP_READY	Check akedly utilities templates get <id> for Akedly approval, WhatsApp usability and data.metaStatus. Use resubmit-meta only when data.whatsappResubmittable is true.
WHATSAPP_NOT_ENABLED	Check the utility pipeline and enable WhatsApp with akedly utilities pipelines channels set <id> `--file` <path>.
TEMPLATE_MISSING_VARIABLE	Supply the missing values through `--values-file`; use akedly utilities templates get <id> to inspect variables and fallbacks.
RECIPIENT_SUPPRESSED	Check akedly utilities suppressions list and respect the recipient opt-out; do not repeat the send to bypass suppression.
UTILITY_SMS_REQUIRES_BYO	Check akedly byo-sms list, active tested integration coverage and the pipeline byoSms setting; utility SMS requires eligible BYO-SMS.
UTILITY_SMS_COUNTRY_NOT_ROUTED	Check the selected BYO-SMS integration coverage for this destination with akedly byo-sms get <id>.
UTILITY_SMS_PROVIDER_NOT_READY	Check akedly byo-sms get <id> and complete the selected provider setup before sending.
IDEMPOTENCY_KEY_REUSE	Keep the original idempotency key with exactly the original template id and flags (`--pipeline-id`, `--channel`, `--phone-number`, `--values-file` and `--operation-fingerprint`, each supplied or omitted as before). Inspect akedly utilities messages list before deciding on a different operation.
IDEMPOTENCY_IN_PROGRESS	The existing operation is still processing. Keep its key and inputs; inspect akedly utilities messages list before retrying.
IDEMPOTENCY_OUTCOME_UNKNOWN	Keep the key and inputs. Inspect akedly utilities messages list and get <transactionID>, then contact Akedly support before retrying; do not start a new operation.
TEMPLATE_VAR_MISSING	No message was sent. Fill every required variable in `--values-file`; inspect variables and fallbacks with akedly utilities templates get <id>.
no_active_waba	No message was sent. An active connected WhatsApp Business Account is required; use `--channel` sms if ready, or run akedly whatsapp connect for the dashboard connection link.

Common error guidance.