The frwrd command-line tool

frwrd is a thin client over the API. It reads from standard input and writes to standard output, prints the API's JSON as it came, and exits with 1 on an error, so it works in a shell script and in an agent's tool call.

Install

Release binaries for macOS and Linux (arm64 and amd64) are attached to each tagged release of the source repository. The repository is private for now, so there is no public download address yet; one will follow here. Until then, with Go 1.27 or newer and a checkout of the source:

go build -o frwrd ./cmd/frwrd

Set up

export FRWRD_KEY=fw_...

FRWRD_KEY: your workspace key. Creating and recovering a workspace need no key.
FRWRD_API: the API address, https://api.frwrd.to unless you set it. It must be https; plain http is accepted for localhost only, so the key never travels in the clear.

Run frwrd alone to print every command.

Links

frwrd link create https://example.com/a/long/address -title "Example"
frwrd link list
frwrd link show aB3xZ9
frwrd link stats aB3xZ9 -since 2026-10-01
frwrd link stats aB3xZ9 -range 7d
frwrd link update aB3xZ9 -title "New title" -tags launch,2026
frwrd link archive aB3xZ9
frwrd link qr aB3xZ9 -png -size 512 > code.png

link create also takes -hash for your own hash on a verified workspace. link update takes -url, -title, -tags and -archived true|false. link qr writes SVG unless you pass -png.

Pages

A page path is - for the root page, hello for another page, and de/hilfe for a page in another language.

frwrd page list
frwrd page pull hello > hello.md
frwrd page push hello < hello.md
frwrd page push hello -version 3 < hello.md
frwrd page stats hello -since 2026-10-01
frwrd page stats hello -range 1d
frwrd page versions hello
frwrd page delete hello

page pull prints the version it read on standard error. Pass it to page push as -version, and the push fails if someone changed the page meanwhile.

Workspace

frwrd workspace create acme.com
frwrd workspace show
frwrd workspace stats -range 7d
frwrd workspace verify
frwrd workspace handle acme
frwrd workspace language de
frwrd workspace utm -source newsletter -medium email
frwrd workspace domains
frwrd workspace domain add links.acme.com
frwrd workspace domain remove links.acme.com
frwrd workspace recover acme.com
frwrd workspace recover-confirm acme.com
frwrd workspace delete --confirm acme.com

workspace stats prints the numbers of all your links at once: the clicks of the range (-range 1d, 7d, the default, or 30d) as buckets, the all-time total (null when it could not be counted right now) and the ten most clicked links. The numbers may be up to 5 minutes old.

workspace utm sets the UTM defaults that every new link gets (-source, -medium, -campaign, -term, -content; the flags are the whole new set, -clear empties it). workspace delete deletes the workspace and only runs with the workspace's own domain as --confirm. Deleting a workspace stops its key and takes its pages offline at once; after 7 days the pages and settings are deleted. Short links keep working. Proving the domain (key recovery) within 7 days restores everything; up to 60 days, the links. After 60 days the domain is free and the links keep working without an owner. Browsers may keep cached copies of a page, its QR code and images for up to an hour after the delete.

workspace create prints the key once. recover-confirm reads the recovery secret from FRWRD_RECOVERY_SECRET or from standard input, so it never shows up in your shell history. The workspace key page explains both recovery steps.