--- name: wba-cli description: Use the WhatBuyersAsk wba CLI to sign in, inspect clients and research progress, start or manage requested research, and download saved reports or AEO bundles. Use for WhatBuyersAsk account operations through its existing APIs, not generic web research or website AEO audits. --- # WhatBuyersAsk CLI Use the installed `wba` command. Research executes on WhatBuyersAsk's servers; the CLI is a client for the existing APIs. Prefer `--json` when interpreting results. Run `wba --help` to check the installed version's commands rather than inventing flags or API endpoints. ## Connection and scope 1. Check `command -v wba` and `wba --version`. If needed, also check `~/.local/bin/wba`; the current process may not have the installer's PATH update. 2. Run `wba status --json` (v0.1.1+) to verify the saved session, then `wba whoami --json` for account/workspace details. Status exits 0 with `connected:true`, 1 with `connected:false`, or 2 with `connected:null` when verification is unavailable. A network/service error is not proof of logout; keep the saved configuration and retry the read when available. Confirm the active workspace (`activeTenantId`) and account match the user's task before accessing or changing client data. `wba guide` provides an offline usage walkthrough. 3. With v0.1.6+, `wba login` verifies and reuses an active saved session without opening a browser or changing its expiry. A service error keeps the session. Use `wba login --force` only when an early renewal is requested. If signed out or expired, run `wba login`. It opens the existing Google sign-in and workspace-selection flow, then displays a pairing code in both browser and terminal. The user completes account authentication and approves **Connect this terminal**. `--no-browser` prints the URL for a browser on the same machine. Do not bypass this flow by reading another browser's cookies or minting a session. 4. Use `wba clients list --json` and, when needed, `wba clients show CLIENT_ID --json` to resolve the actual client ID. Ask only if the intended client/workspace remains ambiguous. If installation is part of the user's request and the CLI is absent, the official installer is: ```sh curl -fsSL https://whatbuyersask.com/install.sh | bash ``` The v0.1.5+ installer does not open login by default. For an immediate public check use `curl -fsSL https://whatbuyersask.com/install.sh | bash -s -- --check https://example.com`. For workspace access run `wba login` explicitly; --login is an optional installer flag. For agent-driven setup without changing shell files, pass `bash -s -- --skip-login --no-modify-path`, then invoke `~/.local/bin/wba login`. Installation supports macOS/Linux x64/ARM64, requires curl and a SHA-256 utility, and installs a private verified Node runtime if Node 22+ is absent. Use `--origin` only when the user/task intentionally selects a different portal; production is `https://app.whatbuyersask.com`. A session lasts seven days and retains the account's current workspace/client permissions. `wba logout` revokes the CLI session. Configuration and saved request histories are private under `~/.config/whatbuyersask` (or `WBA_CONFIG_DIR`). Do not read, print, upload, or place session tokens in prompts, command arguments, artifacts or URLs. Use whoami for identity checks. With v0.1.2+, use `wba doctor --json` to inspect runtime/platform, installation integrity, PATH, private config permissions, server connection and current release. Doctor is read-only: 0 means all checks passed, 1 means a failed check, and 2 means warnings or unavailable checks. Signed out is a warning, not a broken install. Do not automatically chmod, delete files or log in merely because doctor reports a problem. `wba update --check --json` checks the official release without installing. When the user requests an update, `wba update` installs the latest verified release into the existing managed prefix and atomically switches its launcher. Saved login and request history remain unchanged. It refuses downgrades, changed checksums for an existing version, unsafe installation files, redirects and mismatched artifacts. It does not update Node itself; follow the printed installer guidance if a future version requires a newer runtime. Versions before v0.1.2 need the official installer once to gain these commands. Do not bypass an update lock without establishing that no update is active. ## Test whether AI bots can reach a public website With v0.1.7+, expanded audits are available: ```bash wba example.com --all-bots wba example.com --platforms claude,google,perplexity wba example.com --all-bots --json --out audit.json ``` The default remains three agents; --all-bots selects 20 crawler/control identifiers. Platforms: openai, claude, google, perplexity, microsoft, meta, apple, amazon, commoncrawl, bytedance, grok. Aliases: chatgpt, anthropic, gemini, copilot, bing, xai. Never combine --all-bots and --platforms. Scope is bound to the saved request ID; use a new ID to change scope. Google-Extended and Applebot-Extended are content-use controls, with no separate HTTP request. GrokBot/xAI-Grok and Bytespider are experimental identifiers; do not present them as verified provider crawlers. Each agent's response has its own readability finding; real bot access stays not_verified until independent log evidence exists. Neutral HTML canonical/JSON-LD/robots-meta signals require review and are not a citation score. Training opt-outs are separate from search eligibility. With v0.1.4+, use the shorthand the user requested: ```sh wba https://whatbuyersbuy.com wba whatbuyersbuy.com --json wba access check https://whatbuyersbuy.com --out access-check.json wba https://whatbuyersbuy.com --open ``` This checks the homepage through the same public WhatBuyersAsk API as the website. It does not require login, read the saved account session, start research, use research credits or make AI model calls. URL format is checked locally before any API call. The server saves before/after findings and sends the existing full-results notification to dm@whatbuyersask.com. Human output explains bot access, robots instructions, readable page text and manual Cloudflare review. Bot labels do not establish a verified crawler visit or guaranteed AI visibility. Use --json for structured results. Check records are saved privately under access-checks in the CLI configuration directory. The result contains a private AI-help link with a fragment handoff key; do not publish the key or full link in logs or shared artifacts. --open opens the same website helper; its existing sign-in protects the conversation. Links expire after48hours. A normal invocation creates a fresh check. If an address cannot be found, correct it and run a fresh check. After an uncertain result, reuse the printed --request-id UUID and the exact same website; do not generate repeated checks automatically. A completed local result is reused without another request or email. Exit0 means the check completed, not that every finding passed. Exit1 means input or service failure. Never present a missing/unreachable check as proof the website is blocked. ## Read research and progress ```sh wba research list --json wba research list --running --json wba research list --status failed --json wba research list --query "Client name" --json wba research show RUN_ID --json wba research outputs RUN_ID --out outputs.json --json ``` Use IDs returned by the API. Inspect `status`, `progressPercent`, `stageProgress`, stage `metrics` and saved errors. Several stages can be active; report what is actually returned. Never treat unavailable evidence as a zero score or a failed stage as complete. For agents, prefer bounded `show` snapshots. For an interactive terminal, `wba research watch RUN_ID --interval 5` follows progress; `--json` emits one JSON snapshot per line. Ctrl+C stops watching only. Watch exits 0 on completion, 2 on failed/paused work, and 3 on cancellation; command/API errors exit 1. Do not resume, rerun or create a recurring monitor merely because a read shows a failure. The research list shows current research for accessible clients, currently capped at 100 rows. It is not an exhaustive historical export. Do not infer that a missing row was deleted or that the account has no older work. ## Start or manage requested research A request to start research for a resolved client authorizes that operation; avoid redundant permission questions. A request only to list, inspect, download or estimate research does not authorize a start. Research uses normal workspace credits. Do not purchase credits or expand the selected competitor/client scope without user authorization. ```sh wba research draft CLIENT_ID --out draft.json --json wba research start --file draft.json --dry-run --json wba research start --file draft.json --json # Alternatively, use the saved setup or server-provided defaults: wba research start --client CLIENT_ID --json wba research cancel RUN_ID --json wba research resume RUN_ID --json ``` Review/edit the canonical draft when the user specifies scope or preferences. Keep its required configuration and validated client identity. `--dry-run` displays exact input without starting work; it is not a credit reservation or a guarantee of server acceptance. Cancellation fetches the current version before submitting; do not bypass a conflict. Resume retains the existing run/checkpoints and the server's credit checks. ### Interrupted submissions The CLI durably records the exact input, workspace, origin and idempotency UUID before submitting a start. It prints the request UUID and saved request path to stderr. If the result is unknown, inspect current research first. Retry that same saved request, not a new start: ```sh wba research start --file /absolute/path/to/requests/REQUEST_UUID.json --json ``` This reuses the original UUID automatically. `--request-id UUID` is also supported; reuse must retain exactly the same input/workspace/origin. Do not generate a new UUID, change a saved intent, or switch accounts to evade a conflict. No mutation is automatically retried by the CLI. If the outcome remains uncertain, report the request ID and stop further starts until it is resolved. ## Saved reports and AEO downloads ```sh wba reports list --json wba reports show REPORT_ID --json wba reports download REPORT_ID --format json --out report.json --json wba reports download REPORT_ID --format md --out report.md --json wba aeo info RUN_ID --json wba aeo download RUN_ID --out website-aeo-bundle.zip --json ``` Reports export existing saved data, including returned evidence/provenance; these commands do not generate a report. Formats are JSON and Markdown. PDF remains the portal's Print/save PDF action; do not promise a CLI PDF flag. Check AEO availability for the exact run. The CLI downloads saved bundles only. New research includes the AEO generation stage; historical runs and runs whose bundle stage has not completed may legitimately have no bundle. If unavailable, explain that condition; do not start research, generate files independently, or claim a placeholder ZIP is the client's result. Output directories must exist. Downloads are private and atomic; existing files are protected. Use `--force` only when replacing the selected file is within the user's request. AEO downloads validate ZIP content type/signature and have a 100 MB limit. Return a usable local file link after verifying command success and the output path. Do not upload or publish downloaded research unless requested. ## Report the outcome Distinguish started/queued/running/completed, saved versus unavailable outputs, and local versus production tests. Include the useful run/report IDs, current stage or blocker, and file paths. Never include session tokens or imply that installing, logging in or reading status started research. ## Create a client with AI With v0.1.8, supply a website and a short description of the research requirements: ```sh wba clients create --url example.com --requirements "Local dental services in Fort Collins; compare nearby practices" --json wba clients create --url example.com --requirements "Buyer research for local customers" --dry-run --json wba clients create --file /absolute/path/to/client-requests/REQUEST_UUID.json --json ``` The existing portal website study prepares the verified business name, offer, buyer audience, outcomes, market, country, service areas and supported competitors. Perplexity then selects B2B or Local business AEO using the completed business brief. Requirements are context, not permission to invent facts or change website identity. No questionnaire is needed. Review unsupported or missing fields in the portal. Creation saves a client only. It does not start research or reserve research credits. `--dry-run` calls AI setup and saves a private prepared request without creating the client. Normal authenticated account/workspace access applies. Existing domains are reopened without overwriting their profile. The exact intent and prepared profile are saved privately before submission; use `--file` to continue it. An unknown AI study stays held. An unknown client save is reconciled by its exact domain and is never automatically sent again. Do not use a new ID or another account to work around an uncertain save. `--out` saves the returned result; `--request-id` accepts a UUID.