@scrapeatlas/cli 0.1.0

package/README.md

@@ -0,0 +1,99 @@
+# ScrapeAtlas CLI
+
+The official terminal client for the [ScrapeAtlas API](https://scrapeatlas.com/docs/).
+Requires Node.js 22 or newer and a ScrapeAtlas customer API key.
+
+```sh
+npm install -g @scrapeatlas/cli
+scrapeatlas auth login
+scrapeatlas bluesky profile --handle bsky.app --pretty
+```
+
+Or run without a global installation:
+
+```sh
+npx @scrapeatlas/cli list
+```
+
+## Discover and call endpoints
+
+```sh
+scrapeatlas list
+scrapeatlas list reddit
+scrapeatlas bluesky profile --help
+scrapeatlas list bluesky --json
+scrapeatlas bluesky posts --handle bsky.app --limit 10
+scrapeatlas call blueskyProfile --input '{"handle":"bsky.app"}'
+scrapeatlas reddit search --input @request.json
+```
+
+Commands and request schemas are generated from the API's gateway/MCP catalog.
+`list <platform> --json` includes operation IDs, paths, JSON Schemas and availability.
+Only cataloged operations are included. A catalog entry does not guarantee the
+provider is available on a particular deployment; inspect its availability and the
+actual response. API validation remains authoritative for cross-field rules and
+URL refinements.
+
+Use `scrapeatlas <platform> <action>`. Parameter flags accept the API's original
+camelCase/snake_case name and its kebab-case spelling (`--user-id`). Boolean
+parameters use `--flag` / `--no-flag`; explicit booleans, arrays and nested objects
+can be passed through `--input '<JSON object>'` or `--input @file.json`. Required
+parameters, types and structural bounds are checked locally before a request.
+Duplicate parameters and unknown options are rejected.
+
+## Authentication
+
+Get a customer API key from [your dashboard](https://scrapeatlas.com/dashboard/keys/).
+`auth login` reads a hidden key and verifies it through the gateway before saving.
+For noninteractive login, pipe a key to `scrapeatlas auth login --stdin`.
+
+```sh
+scrapeatlas auth status
+scrapeatlas auth logout
+```
+
+Credential priority is `--api-key`, then `SCRAPEATLAS_API_KEY`, then stored login.
+Prefer the environment variable in CI; a flag can appear in shell history and
+process lists. `auth status` reports the credential source without printing the
+key; it does not make a live verification request. Logout removes the stored key;
+it does not revoke the key in your account or clear an environment variable.
+
+Config is stored in `$XDG_CONFIG_HOME/scrapeatlas/config.json`, defaulting to
+`~/.config/scrapeatlas/config.json`. Override with `SCRAPEATLAS_CONFIG_DIR`.
+The config directory is mode 0700 and the file is mode 0600 on POSIX. The file
+contains a plaintext key protected by those permissions; it is not a keychain.
+
+The default API origin is `https://api.scrapeatlas.com`. `--base-url` overrides
+`SCRAPEATLAS_BASE_URL`, the saved origin, then the default. HTTPS origins are
+supported; HTTP is allowed only on loopback for local development. Stored keys
+are used only for their saved origin. An explicit flag/environment key can be
+used with a custom gateway. No cookies or provider worker secrets are required.
+
+## Output and failures
+
+```sh
+scrapeatlas bluesky profile --handle bsky.app | jq '.followersCount'
+scrapeatlas bluesky profile --handle bsky.app --pretty
+scrapeatlas bluesky profile --handle bsky.app --output profile.json
+scrapeatlas bluesky profile --handle bsky.app --envelope
+```
+
+Default stdout is the complete compact gateway JSON. `--pretty` indents it.
+`--envelope` wraps it as `{httpStatus, body, requestId?, retryAfter?}`.
+`--output` writes a new file and prints only its absolute path; existing files
+are never overwritten. Diagnostics are structured JSON on stderr and never
+include request parameters, credentials, or retrieved content.
+
+Nulls, failed lookups, partial coverage, ordering and pagination tokens are
+preserved. A usable partial response exits 0; inspect `status` and `coverage`
+before treating results as complete. HTTP errors or explicit `success: false`,
+`status: failed` and `status: challenged` exit 1 while keeping the full API body
+on stdout. Local argument/config/file errors exit 2. Ctrl-C during login exits 130.
+
+Each call makes one gateway request, with no retries, automatic pagination,
+redirect following or media downloads. Pass the returned cursor explicitly for
+another page. Requests are capped at 64 KiB and responses at 16 MiB. The deadline
+covers headers and body: 90 seconds by default, configurable using
+`--timeout <milliseconds>` from 1 to 120000. Failures never masquerade as empty
+successes. This version exports JSON only and does not install agent configs,
+run an MCP server, perform browser signup, or supply a TypeScript SDK.

package/bin/scrapeatlas.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.mjs';
+process.stdout.on('error', (error) => {
+  if (error.code === 'EPIPE') process.exit(0);
+  else process.exit(1);
+});
+process.exitCode = await run(process.argv.slice(2));