site-resolver hangs / returns no matches when API returns 0 sites for per_page=100

[melvin-adame]

Summary

instawp wp <site> and instawp exec <site> hang indefinitely at "Resolving site…" on accounts where the active team has more than zero sites visible via instawp sites list. The root cause is in dist/lib/site-resolver.js line 25, which hardcodes per_page: 100 when listing sites. The InstaWP /api/v2/sites endpoint returns an empty data array for any per_page value above ~20, so the resolver receives 0 sites, finds no match for the user's identifier, and falls into a state where the spinner never resolves.

Environment

• @instawp/cli version: 0.0.1-beta.1
• Node: v22.22.0
• Platform: Linux (also reproducible on macOS based on user reports)
• API endpoint: https://app.instawp.io/api/v2

Reproduction

1. Log in with a token whose active team contains real sites:

   instawp login --token "$INSTAWP_TOKEN"

2. Confirm sites are visible to the API at default pagination:

   instawp sites list

Returns the expected list. 3. Run any command that calls resolveSite:

   instawp wp <site-name-or-id> --api option get siteurl
   instawp exec <site-name-or-id> --api ls -la

The command hangs at "Resolving site…" indefinitely (eventually times out at the shell level).

Expected behaviour

resolveSite finds the identifier in the API response and returns the matching site object, allowing instawp wp / instawp exec to proceed.

Actual behaviour

resolveSite receives { data: [], meta: { last_page: 1 } } from the API and cannot match. The spinner never advances.

Root cause

dist/lib/site-resolver.js:25:

js

const res = await client.get('/sites', { params: { per_page: 100 } });

Confirmed via direct API testing:

per_page value | Sites returned -- | -- 20 (default) | 3–9 (actual count) 25 | 0 50 | 0 100 | 0

The /api/v2/sites endpoint has an undocumented hard cap (somewhere between 20 and 25) above which it returns an empty data array — possibly silently capping per_page to a smaller value internally and the cap doesn't match the requested page size, or rejecting the parameter without an error. Either way, the CLI relying on per_page: 100 is brittle.

This is technically an API bug (the endpoint should either honour the requested per_page or return an error), but the CLI can avoid it entirely by paginating with safe page sizes.

Suggested fix

Either:

A. Simple — change per_page: 100 to per_page: 20 in site-resolver.js:25. Most accounts have fewer than 20 sites, so a single call still works for the common case.

B. Robust — paginate using per_page: 20 and walk meta.last_page to fetch all pages, so the resolver works for accounts with 20+ sites:

js

async function fetchAllSites(client) {
  const all = [];
  let page = 1;
  while (true) {
    const res = await client.get('/sites', { params: { per_page: 20, page } });
    const items = res.data?.data ?? [];
    all.push(...items);
    if (page >= (res.data?.meta?.last_page ?? page)) break;
    page++;
  }
  return all;
}

Option B is what instawp sites list effectively already does at default pagination — applying the same approach in resolveSite keeps behaviour consistent.

Workaround (until fixed)

Call the API directly:

bash

curl -X POST \
  -H "Authorization: Bearer $INSTAWP_TOKEN" \
  -H "Content-Type: application/json" \
  "https://app.instawp.io/api/v2/sites/<site_id>/run-cmd" \
  -d '{"commands":["wp option get siteurl"],"timeout_seconds":25}'

Note: instawp sites list works because it uses the API's default pagination (per_page=20); only resolveSite is affected because of its hardcoded per_page=100.

Additional context (optional, can drop if too much)

Discovered while diagnosing a WP Mail SMTP migration issue on a freshly-migrated v3 site. Token was scoped to a team that had recently been emptied (sites moved to a new "V3" team via the v2→v3 migration tool). After switching the active team in the dashboard, instawp sites list started returning the V3 sites correctly, but instawp wp continued to hang — which is what surfaced this bug as separate from the v3 migration itself.

[vikasiwp]

Fixed in v0.0.1-beta.13 (npm i -g @instawp/cli@beta).

What we changed: resolveSite no longer does a single per_page=100 fetch — it now paginates the /sites endpoint (per_page=20, walking meta.last_page), the same way instawp sites list does. This resolves the symptom regardless of the endpoint's per-page behavior and also fixes resolution for accounts with 100+ sites.

One note on the root-cause theory: we couldn't reproduce the "empty data array for per_page above ~20" on app.instawp.io — a direct sweep there returned the full set at every size:

per_page	data.length (total=53)
20	20
25	25
50	50
100	53

So the hard cap may be specific to your environment (a proxy/WAF, an older API deployment, or a region). Either way the CLI shouldn't depend on a large single page, so pagination is the right fix on our end. If you still hit it on beta.13, please reopen with the output of instawp sites list --json | head and we'll dig into the API side.

Thanks for the detailed write-up and the spot-on suggested fix (Option B) — made this an easy one. 🙏