Webcentive CLI

A small, read-only shell script for the Webcentive API. It only uses curl. It is not published to npm, PyPI or Homebrew, and it has no dependencies. You don't have to download anything: the complete script is shown below, and the plain curl commands do the same job.

What it does

• webcentive categories prints the list of news categories as JSON.
• webcentive news firewalls prints today's news for one category as JSON.
• webcentive version prints the version.

What it will never do

• It only sends read-only GET requests to https://www.webcentive.com. That address is fixed in the script and cannot be changed.
• HTTPS only (TLS 1.2 or newer), no redirects followed, a 30 second time limit and a 2 MB size limit.
• It sends no personal data, writes no files, needs no root or sudo, and never runs anything it downloads.
• Category names are checked first: only a-z, 0-9 and hyphens, up to 30 characters. Anything else is refused.

The complete script (version 1.1)

This is exactly what /cli/webcentive contains. That link opens as plain text in your browser.

#!/bin/sh
# webcentive - official dependency-free CLI for the Webcentive API (curl only).
# Not an npm, PyPI or Homebrew package. Read every line at https://www.webcentive.com/cli/
#
# Usage:
#   webcentive categories     list news categories (JSON)
#   webcentive news <cat>     today's news for one category, e.g. firewalls (JSON)
#   webcentive version        show the version
#
# Safety: read-only GET requests to https://www.webcentive.com only. It sends no
# personal data, writes no files, needs no root, and never runs anything it downloads.
set -eu

BASE='https://www.webcentive.com'   # fixed on purpose: cannot be pointed at another server
UA='webcentive-cli/1.1 (+https://www.webcentive.com/cli/)'

usage() {
  echo "Usage: webcentive categories | news <cat> | version" >&2
  exit 2
}

# HTTPS only (TLS 1.2+), no redirects, 30 second limit, 2 MB response limit.
get() {
  curl --fail --silent --show-error --proto '=https' --tlsv1.2 \
       --max-redirs 0 --max-time 30 --max-filesize 2000000 \
       -A "$UA" "$BASE$1"
  echo
}

[ $# -ge 1 ] || usage
cmd=$1
shift

case $cmd in
  version)
    echo "webcentive-cli 1.1"
    echo "base $BASE"
    ;;
  categories)
    get /api/v1/categories
    ;;
  news)
    [ $# -eq 1 ] || usage
    cat=$1
    # Only a-z, 0-9 and hyphen, 1-30 characters; anything else is refused.
    case $cat in
      *[!a-z0-9-]*|'') echo "webcentive: invalid cat (use a-z, 0-9 and -)" >&2; exit 2 ;;
    esac
    [ ${#cat} -le 30 ] || { echo "webcentive: cat too long (max 30)" >&2; exit 2; }
    get "/api/v1/news?cat=$cat"
    ;;
  *) usage ;;
esac

Check it before you run it

SHA-256: b3dd43e5a9479f8c8a17c387b71fc424f3df4998ac0f6363e96ca8b5a74b97d3

curl -fsSO https://www.webcentive.com/cli/webcentive
echo 'b3dd43e5a9479f8c8a17c387b71fc424f3df4998ac0f6363e96ca8b5a74b97d3  webcentive' | sha256sum -c -
less webcentive          # read it yourself
chmod +x webcentive
./webcentive news firewalls

On macOS use shasum -a 256 -c - instead of sha256sum -c -. Never pipe it straight into sh. Download it, check it, read it, then run it.

No download needed

The script only wraps these two requests, which you can run yourself:

curl -fsS --proto '=https' https://www.webcentive.com/api/v1/categories
curl -fsS --proto '=https' 'https://www.webcentive.com/api/v1/news?cat=firewalls'

Webcentive API docs | openapi.json | webcentive.com home