Skip to content

feat(api): add --verbose, --paginate, --no-auth flags + log resolved URL to apify api#1251

Draft
DaveHanns wants to merge 1 commit into
masterfrom
api-verbose-paginate-no-auth-log-url
Draft

feat(api): add --verbose, --paginate, --no-auth flags + log resolved URL to apify api#1251
DaveHanns wants to merge 1 commit into
masterfrom
api-verbose-paginate-no-auth-log-url

Conversation

@DaveHanns

Copy link
Copy Markdown
Contributor

Summary

apify api is a great REST escape hatch, but when an agent (or a human) uses it to
debug, three things are painful: the resolved outbound URL is invisible, walking a
paginated endpoint requires a manual offset loop, and hitting an auth-less resource
(e.g. the actor-templates manifest on raw GitHub) requires reaching for curl
instead of the same command. This PR adds three additive, independent flags —
--verbose, --paginate (+ --paginate-max), and --no-auth — to close those
gaps without changing any existing behavior.

Refs internal findings F31 + EF8.

What changes

src/commands/api.ts only. All flags default to off; omitting them yields
byte-identical behavior to today.

  • --verbose / -v — logs -> METHOD URL to stderr before the fetch and
    <- STATUS statusText (content-type) after. Payload still goes to stdout, so
    apify api ... --verbose | jq . keeps working.
  • --paginate — for responses shaped like { data: { items, total, offset, limit } } (the Apify pagination envelope), advances offset until total is
    exhausted and emits all collected items as a single JSON array on stdout.
    Errors loudly with a clear message if the response isn't paginated instead of
    silently truncating. --paginate restricted to GET.
  • --paginate-max N — cap items collected across pagination.
  • --no-auth — skips the Authorization header. Also lets the endpoint
    argument be an absolute https://... URL so the same command can hit
    raw.githubusercontent.com etc. When --no-auth is set we do not require a
    logged-in client (so this works out of the box in fresh environments).

Also adds four apify api --help examples covering the new flags.

Test plan

  • apify api users/me --verbose prints the resolved GET https://api.apify.com/v2/users/me line and status line to stderr; payload still lands on stdout.
  • apify api acts --paginate walks all pages and emits one JSON array; the array length equals data.total of the first page.
  • apify api acts --paginate --paginate-max 5 returns exactly 5 items.
  • apify api POST acts --paginate errors out with "can only be used with GET requests".
  • apify api users/me --paginate errors out with "expected a { data: { items } } response shape".
  • apify api --no-auth https://raw.githubusercontent.com/apify/actor-templates/master/templates/manifest.json fetches the file without an Authorization header, even when not logged in.
  • All three flags compose: apify api acts --paginate --verbose --paginate-max 10 prints request/response lines per page and returns 10 items.
  • pnpm exec oxlint --type-aware src/commands/api.ts passes.
  • pnpm exec tsc --noEmit -p . passes.

`apify api` is the escape-hatch REST tool but agents debugging with it currently
have no way to see the resolved outbound URL, no shortcut for walking a
paginated endpoint, and no way to hit auth-less resources through the same
command. This adds three additive, independent flags:

- --verbose (-v): logs "-> METHOD URL" to stderr before the fetch and
  "<- STATUS (content-type)" after, so callers can see exactly what the CLI
  sent and what came back.
- --paginate: for endpoints returning { data: { items, total, offset, limit } },
  automatically advances offset until exhausted and emits all items as a single
  JSON array on stdout. Pair with --paginate-max N to cap. Fails loudly if the
  response is not paginated (never silently truncates).
- --no-auth: skips the Authorization header. Accepts absolute URLs verbatim so
  the same escape hatch can reach public resources like raw.githubusercontent.com
  (e.g. actor-templates manifest) without requiring a login.

None of the flags change existing behavior when omitted; all three compose.

Refs internal findings F31 + EF8.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants