@wahlu/cli

Safe command-line access to the Wahlu public API. The CLI is a thin adapter over @wahlu/api-client; it does not call private routes, databases, social providers, or storage providers directly.

Release status: the CLI intentionally supports a ten-operation subset of the 15-operation public API: three discovery commands, remote media import, single-media readiness, explicit reviewed repair derivatives, draft creation, write-free preflight, and Schedule creation and reading. Receipt lookup and exact provider cleanup remain available through the REST/API-client and production MCP surfaces, not this CLI subset. Version 0.3.3 is published on npm. The executable requires Node.js 20+; its optional programmatic export is ESM-only.

Installation

npm install --global @wahlu/[email protected]

The source executable accepts API keys only through WAHLU_API_KEY. There is intentionally no --api-key option, which avoids putting credentials into shell history or process listings. Use a least-privilege, brand-restricted key where possible and never commit it to a project file.

Supported CLI subset inventory

wahlu auth status
wahlu targets list --brand BRAND_ID
wahlu platforms capabilities
wahlu media import \
  --brand BRAND_ID \
  --url https://assets.example.com/campaign/hero.jpg \
  --idempotency-key KEY
wahlu media get \
  --brand BRAND_ID \
  --media MEDIA_ID
wahlu media repair \
  --brand BRAND_ID \
  --media MEDIA_ID \
  --integration INTEGRATION_ID \
  --platform instagram \
  --post-type GRID_POST \
  --mode centre_crop \
  --repair-option REPAIR_OPTION_ID \
  --policy-version 2026-08-05.1 \
  --idempotency-key KEY
wahlu drafts create \
  --brand BRAND_ID \
  --input-file ./draft.json \
  --idempotency-key KEY
wahlu drafts preflight \
  --brand BRAND_ID \
  --content-item CONTENT_ITEM_ID \
  --integration INTEGRATION_ID \
  [--scheduled-at 2026-07-20T09:00:00Z]
wahlu schedules create \
  --brand BRAND_ID \
  --content-item CONTENT_ITEM_ID \
  --scheduled-at 2026-07-20T09:00:00Z \
  --integration INTEGRATION_ID \
  --approval-status pending_review \
  --idempotency-key KEY
wahlu schedules get \
  --brand BRAND_ID \
  --schedule SCHEDULE_ID

drafts validate is a stable alias for drafts preflight. Both names perform the same write-free readiness check.

drafts create accepts the complete strict snake_case public draft body from exactly one source:

• --input-file ./draft.json reads a bounded UTF-8 file and keeps draft content out of the process argument list;
• --input-json - < draft.json reads bounded UTF-8 JSON from stdin; or
• --input-json '{...}' accepts inline JSON for convenience, but exposes that content to shell history and process inspection.

Supplying both input options, or neither, is a usage error. --input-file - is rejected so stdin has one unambiguous spelling. Every draft input is limited to 1 MiB; invalid UTF-8, unreadable files, oversized input, and invalid JSON fail before the API client is constructed. The idempotency key must be supplied separately so retries have one explicit caller-owned source. Creating a draft never schedules or publishes it. drafts preflight (also available as drafts validate) is write-free and reports blockers, warnings, repairs, and next actions. Repeat --integration to evaluate several intended accounts together; omit --scheduled-at when you want the API to report schedule-time readiness as a repairable blocker.

schedules create requires the approval decision to be explicit. pending_review creates a held Schedule and does not publish. approved may lead to publication and requires the API key to have publish:execute permission. The caller must also provide one stable idempotency key; the CLI never invents one. schedules get reads one Schedule once and does not poll, execute, or modify it.

Held Schedule golden workflow

This executable Bash example uses JSON output plus jq to carry every returned identifier into the next command. It imports one Instagram grid image, reads media readiness once, and stops if processing is not complete; it does not create a polling loop.

set -euo pipefail

CONTEXT_JSON=$(wahlu auth status --json)
BRAND_ID=$(jq -er '.data.brands[0].id' <<<"$CONTEXT_JSON")

TARGETS_JSON=$(wahlu targets list --brand "$BRAND_ID" --json)
INTEGRATION_ID=$(jq -er \
  '[.data.targets[] | select(.platform == "instagram" and .schedulable and .integration_id != null) | .integration_id][0]' \
  <<<"$TARGETS_JSON")

MEDIA_IMPORT_JSON=$(wahlu media import \
  --brand "$BRAND_ID" \
  --url "https://assets.example.com/campaign/instagram-grid.jpg" \
  --filename "instagram-grid.jpg" \
  --idempotency-key "media-instagram-grid-v1" \
  --json)
MEDIA_ID=$(jq -er '.data.id' <<<"$MEDIA_IMPORT_JSON")

MEDIA_JSON=$(wahlu media get --brand "$BRAND_ID" --media "$MEDIA_ID" --json)
if [[ $(jq -r '.data.status' <<<"$MEDIA_JSON") != "completed" ]]; then
  echo "Media $MEDIA_ID is not ready; run this workflow again later with the same idempotency keys."
  exit 1
fi

DRAFT_INPUT=$(jq -cn \
  --arg integration_id "$INTEGRATION_ID" \
  --arg media_id "$MEDIA_ID" \
  '{
    name: "Held Instagram launch",
    copy_mode: "single",
    single_copy: {caption: "Our launch is ready for review.", hashtags: ["launch"]},
    instagram_settings: {
      media_ids: [$media_id],
      post_type: "GRID_POST",
      collaborators: []
    },
    intended_integration_ids: [$integration_id]
  }')
DRAFT_JSON=$(wahlu drafts create \
  --brand "$BRAND_ID" \
  --input-json - \
  --idempotency-key "draft-instagram-launch-v1" \
  --json <<<"$DRAFT_INPUT")
CONTENT_ITEM_ID=$(jq -er '.data.content_item.id' <<<"$DRAFT_JSON")

SCHEDULED_AT="2026-08-01T10:00:00+10:00"
PREFLIGHT_JSON=$(wahlu drafts preflight \
  --brand "$BRAND_ID" \
  --content-item "$CONTENT_ITEM_ID" \
  --integration "$INTEGRATION_ID" \
  --scheduled-at "$SCHEDULED_AT" \
  --approval-status pending_review \
  --json)
jq -e '.data.can_schedule == true' <<<"$PREFLIGHT_JSON" >/dev/null

SCHEDULE_JSON=$(wahlu schedules create \
  --brand "$BRAND_ID" \
  --content-item "$CONTENT_ITEM_ID" \
  --integration "$INTEGRATION_ID" \
  --scheduled-at "$SCHEDULED_AT" \
  --approval-status pending_review \
  --idempotency-key "schedule-instagram-launch-v1" \
  --json)
SCHEDULE_ID=$(jq -er '.data.schedule.id' <<<"$SCHEDULE_JSON")

wahlu schedules get \
  --brand "$BRAND_ID" \
  --schedule "$SCHEDULE_ID" \
  --json

The final Schedule remains held for review with no publication effect. The variables BRAND_ID, INTEGRATION_ID, MEDIA_ID, CONTENT_ITEM_ID, and SCHEDULE_ID are all sourced from canonical command output rather than guessed.

Global options

The following work consistently across commands and may appear before or after the command:

• --json emits one stable JSON success or failure document.
• --timeout <milliseconds> sets a positive finite logical-request timeout.
• --base-url <url> overrides the Wahlu API origin for staging or local development.
• --media-base-url <url> overrides the branded-media origin used to validate media responses.

platforms capabilities returns the canonical public post types, media and text rules, settings fields, implementation status, and agent rules. JSON mode returns the complete typed registry; human mode gives a compact publishing/scheduling overview.

Successful JSON preserves the API's canonical metadata exactly and keeps transport facts separate:

{
  "ok": true,
  "command": "auth.status",
  "data": {},
  "meta": { "request_id": "request-id" },
  "transport": { "status": 200, "idempotency_replayed": false }
}

The CLI does not reconstruct pagination or request identity from deprecated aliases.

Production defaults remain https://api.wahlu.com and https://media.wahlu.com. Plain HTTP custom origins are rejected by the shared client except for explicit loopback development addresses.

Mutation safety

• Media import and draft creation require a caller-supplied idempotency key. The CLI never invents one. media get returns the canonical current processing status without starting a polling loop.
• Draft preflight is write-free. It cannot create a schedule, enqueue work, or publish content.
• A pending_review Schedule is held and cannot publish. An approved Schedule may lead to an external publication and requires explicit publish:execute permission.
• --dry-run deliberately returns a non-zero DRY_RUN_UNSUPPORTED result without calling the API. Wahlu does not yet expose a server-backed preview contract, so the CLI will not fake success.
• API failures stay failures and map to stable exit codes.

| Exit code | Meaning | | ---: | --- | | 0 | Success | | 2 | Usage, configuration, unsupported dry-run, or confirmation failure | | 3 | Authentication | | 4 | Permission | | 5 | Not found | | 6 | Validation | | 7 | Conflict | | 8 | Rate limit | | 9 | Timeout or cancellation | | 10 | Network, redirect, oversized, or malformed response | | 11 | Server or unknown failure |

Current intentional gaps

• Direct byte upload and media listing remain deferred. The canonical media surface intentionally covers only remote import and one-item readiness.
• Schedule listing, polling, execution, cancellation, rescheduling, receipt lookup, exact provider cleanup, and repair commands remain deferred in the CLI subset.