@sourcescape/external

A small CLI for calling external service APIs behind a single, uniform interface. It has no runtime dependencies — just Node's standard library and fetch.

Install

npm install -g @sourcescape/external
# or run without installing
npx @sourcescape/external <service> <command> [args]

The installed binary is stc-ext.

Configure

Each service reads its credentials from environment variables. Copy .env.example and fill in only the services you need, or export the vars in your shell. A command errors clearly if a required var is missing.

Usage

stc-ext <service> <command> [args]
stc-ext help            # list all services and commands
stc-ext <service> help  # commands for one service

Rich services (named commands)

| Service | Commands | |---------|----------| | gemini | search | | grafana | query, dashboards, folders, alerts | | axiom | query | | sentry | issue, event, tags, list | | vercel | deploy, deployments, projects, api | | mabang | order, orders-by-status, raw | | zendesk-customer | tickets, brand-tickets | | zendesk-creator | sender, search | | brandfetch | svg, search, brand | | etsy | oauth, api, refresh, status |

stc-ext gemini search "What is Fourthwall?"
stc-ext grafana dashboards list
stc-ext axiom query '["my-dataset"] | limit 10' --start now-1h
stc-ext vercel projects list
stc-ext brandfetch svg supabase.com > supabase.svg

Generic HTTP services

Raw <METHOD> <path> against a preconfigured base URL + auth.

stc-ext <service> <METHOD> <path> [--body <json>] [--headers <json>]

| Service | Base URL | Auth env | |---------|----------|----------| | github | https://api.github.com | GITHUB_API_TOKEN | | gitlab | $GITLAB_BASE_URL | GITLAB_API_TOKEN | | atlassian | $ATLASSIAN_BASE_URL | ATLASSIAN_EMAIL + ATLASSIAN_API_TOKEN | | cloudflare | https://api.cloudflare.com/client/v4 | CLOUDFLARE_API_TOKEN | | digitalocean | https://api.digitalocean.com/v2 | DIGITALOCEAN_API_TOKEN |

stc-ext github GET /user
stc-ext github POST /repos/owner/repo/issues --body '{"title":"Bug report"}'
stc-ext cloudflare GET /zones

Etsy OAuth note

etsy oauth runs a PKCE flow that needs a public HTTPS callback. It shells out to frpc (brew install frpc) and tunnels through a self-hosted relay. Tokens are stored at $XDG_CONFIG_HOME/stc-external/etsy-tokens.json (override with ETSY_TOKEN_STORE).

Programmatic use

import { routeCommand, SERVICES, RICH_SERVICES, makeRequest } from "@sourcescape/external";

Develop

npm run build   # tsc -> dist/