CLI reference

Every command answers --help; this page is that output, generated from the CLI at build time. Success prints exactly one line on stdout — the URL — or one JSON object with --json; everything else goes to stderr, and a failure exits non-zero.

handbill

DESCRIPTION
  Hand someone a page: publish one self-contained HTML file, or a markdown file rendered to one, at an unguessable, immutable URL.

USAGE
  handbill <subcommand> [flags] <file>

ARGUMENTS
  file string    HTML or markdown file to publish, or - to read stdin

FLAGS
  --endpoint string    Base URL of the deployment; beats HANDBILL_ENDPOINT and the config file
  --json               Print the result as one JSON object on stdout
  --markdown           Render the input as markdown, whatever it is named — needed for stdin
  --open               Open the printed URL in the default browser
  --qr                 Also print a scannable QR code for the URL to stderr; skipped when stderr is not a terminal

GLOBAL FLAGS
  --help, -h                                                          Show help information
  --version, -v                                                       Show version information
  --wizard                                                            Start wizard mode for a command
  --completions <bash|zsh|fish|sh>                                    Print shell completion script (choices: bash, zsh, fish, sh)
  --log-level <all|trace|debug|info|warn|warning|error|fatal|none>    Sets the minimum log level (choices: all, trace, debug, info, warn, warning, error, fatal, none)

SUBCOMMANDS
  update         Replace a published page: publish the new file, re-point every alias that named the old one, and unpublish it. Same bytes, same hash: nothing happens.
  list           List the pages you have published, newest first.
  remove         Unpublish a page. Idempotent: removing it twice is not an error.
  alias          Point a name at a page: https://<name>.<zone> serves it until the name is pointed elsewhere. Names are guessable, and the deployment has to switch aliases on.
  login          Sign in with GitHub and store the key it mints. The browser opens on a code to type; the key goes in ~/.config/handbill/config.json.
  logout         Revoke the key this machine uses and remove it from the config file. Idempotent: a key that is already revoked is not an error.
  account        Show what the key in hand is: its owner, its tier, and the quotas it has spent today. --upgrade prints a checkout URL for the paid tier instead, and is the only form --open applies to; --web opens the same account in the browser, on the site that belongs to the endpoint's zone.
  doctor         Check the configuration, which endpoint and mode it reaches, whether the key is accepted, and the wildcard certificate.
  admin          Operator commands for whoever runs the deployment.
  completions    Print a shell completion script for bash, zsh or fish.
EXAMPLES
  # Publish a file and print its URL
  handbill plan.html

  # Render markdown to a page and publish that
  handbill notes.md

  # Publish markdown from stdin
  handbill - --markdown

  # Publish, then open the URL in the browser
  handbill plan.html --open

  # Publish, and print a scannable code for the URL to stderr
  handbill plan.html --qr

  # Print { hash, url, created } instead
  handbill plan.html --json

handbill update

DESCRIPTION
  Replace a published page: publish the new file, re-point every alias that named the old one, and unpublish it. Same bytes, same hash: nothing happens.

USAGE
  handbill update [flags] <target> <file>

ARGUMENTS
  target string    The URL of the page being replaced, or its 12-character hash
  file string      HTML or markdown file to publish in its place, or - to read stdin

FLAGS
  --alias string       Also re-point this name, whether or not the listing reports it yet; repeatable
  --endpoint string    Base URL of the deployment; beats HANDBILL_ENDPOINT and the config file
  --json               Print the result as one JSON object on stdout
  --markdown           Render the input as markdown, whatever it is named — needed for stdin
  --open               Open the printed URL in the default browser

EXAMPLES
  # Publish the revision, move the names, drop the old page
  handbill update https://a3f9c1d4e2b8.example.dev plan.html

  # The same by hash: { hash, url, created, removed, aliases }
  handbill update a3f9c1d4e2b8 notes.md --json

  # Move a name too new for the listing to report yet
  handbill update a3f9c1d4e2b8 plan.html --alias plan

handbill list

DESCRIPTION
  List the pages you have published, newest first.

USAGE
  handbill list [flags]

FLAGS
  --endpoint string    Base URL of the deployment; beats HANDBILL_ENDPOINT and the config file
  --json               Print the result as one JSON object on stdout

handbill remove

DESCRIPTION
  Unpublish a page. Idempotent: removing it twice is not an error.

USAGE
  handbill remove [flags] <target>

ARGUMENTS
  target string    The URL of a published page, or its 12-character hash

FLAGS
  --endpoint string    Base URL of the deployment; beats HANDBILL_ENDPOINT and the config file
  --json               Print the result as one JSON object on stdout

handbill alias

DESCRIPTION
  Point a name at a page: https://<name>.<zone> serves it until the name is pointed elsewhere. Names are guessable, and the deployment has to switch aliases on.

USAGE
  handbill alias <subcommand> [flags] <name> <target>

ARGUMENTS
  name string      The name, one DNS label: served at https://<name>.<zone>
  target string    The URL of a published page, or its 12-character hash

FLAGS
  --endpoint string    Base URL of the deployment; beats HANDBILL_ENDPOINT and the config file
  --json               Print the result as one JSON object on stdout
  --open               Open the printed URL in the default browser
  --qr                 Also print a scannable QR code for the URL to stderr; skipped when stderr is not a terminal

SUBCOMMANDS
  remove    Remove an alias. Idempotent, and the page it pointed at stays published.
  list      List your aliases by name: the URL and the hash it points at.
EXAMPLES
  # plan.example.dev now serves that page
  handbill alias plan https://a3f9c1d4e2b8.example.dev

  # The same by hash, then open it
  handbill alias plan a3f9c1d4e2b8 --open

  # Every alias: its URL and the hash it points at
  handbill alias list

  # The name stops answering; the page stays
  handbill alias remove plan

handbill alias remove

DESCRIPTION
  Remove an alias. Idempotent, and the page it pointed at stays published.

USAGE
  handbill alias remove [flags] <name>

ARGUMENTS
  name string    The alias to remove

FLAGS
  --endpoint string    Base URL of the deployment; beats HANDBILL_ENDPOINT and the config file
  --json               Print the result as one JSON object on stdout

handbill alias list

DESCRIPTION
  List your aliases by name: the URL and the hash it points at.

USAGE
  handbill alias list [flags]

FLAGS
  --endpoint string    Base URL of the deployment; beats HANDBILL_ENDPOINT and the config file
  --json               Print the result as one JSON object on stdout

DESCRIPTION
  Sign in with GitHub and store the key it mints. The browser opens on a code to type; the key goes in ~/.config/handbill/config.json.

USAGE
  handbill login [flags]

FLAGS
  --endpoint string    Base URL of the deployment; beats HANDBILL_ENDPOINT and the config file
  --json               Print the result as one JSON object on stdout

EXAMPLES
  # Sign in to the hosted deployment
  handbill login

  # Sign in to another deployment that runs accounts
  handbill login --endpoint https://api.example.dev

handbill logout

DESCRIPTION
  Revoke the key this machine uses and remove it from the config file. Idempotent: a key that is already revoked is not an error.

USAGE
  handbill logout [flags]

FLAGS
  --endpoint string    Base URL of the deployment; beats HANDBILL_ENDPOINT and the config file
  --json               Print the result as one JSON object on stdout

handbill account

DESCRIPTION
  Show what the key in hand is: its owner, its tier, and the quotas it has spent today. --upgrade prints a checkout URL for the paid tier instead, and is the only form --open applies to; --web opens the same account in the browser, on the site that belongs to the endpoint's zone.

USAGE
  handbill account [flags]

FLAGS
  --endpoint string    Base URL of the deployment; beats HANDBILL_ENDPOINT and the config file
  --json               Print the result as one JSON object on stdout
  --open               Open the printed URL in the default browser
  --upgrade            Print a checkout URL for the paid tier instead of the account
  --web                Open the account page on handbill.dev with this key, instead of printing

EXAMPLES
  # Owner, tier and quota usage
  handbill account

  # Print a checkout URL that pays for this account
  handbill account --upgrade

  # The same, opened in the browser after it is printed
  handbill account --upgrade --open

  # Open the account page on the endpoint's site with this key
  handbill account --web

handbill doctor

DESCRIPTION
  Check the configuration, which endpoint and mode it reaches, whether the key is accepted, and the wildcard certificate.

USAGE
  handbill doctor [flags]

FLAGS
  --endpoint string    Base URL of the deployment; beats HANDBILL_ENDPOINT and the config file
  --json               Print the result as one JSON object on stdout

handbill admin

DESCRIPTION
  Operator commands for whoever runs the deployment.

USAGE
  handbill admin <subcommand> [flags]

SUBCOMMANDS
  takedown    Take a page down: it stops being served and is removed from its owner's list. Needs the deployment's ADMIN_TOKEN in HANDBILL_ADMIN_TOKEN. Idempotent.
  tier        Set what an account may spend: `paid` for the hosted paid tier, `free` for everyone else. Needs the deployment's ADMIN_TOKEN in HANDBILL_ADMIN_TOKEN. Idempotent.

handbill admin takedown

DESCRIPTION
  Take a page down: it stops being served and is removed from its owner's list. Needs the deployment's ADMIN_TOKEN in HANDBILL_ADMIN_TOKEN. Idempotent.

USAGE
  handbill admin takedown [flags] <target>

ARGUMENTS
  target string    The URL of a published page, or its 12-character hash

FLAGS
  --endpoint string    Base URL of the deployment; beats HANDBILL_ENDPOINT and the config file
  --json               Print the result as one JSON object on stdout

EXAMPLES
  # The reported URL stops answering within seconds
  handbill admin takedown https://a3f9c1d4e2b8.handbill.dev

  # The same, by hash
  handbill admin takedown a3f9c1d4e2b8

handbill admin tier

DESCRIPTION
  Set what an account may spend: `paid` for the hosted paid tier, `free` for everyone else. Needs the deployment's ADMIN_TOKEN in HANDBILL_ADMIN_TOKEN. Idempotent.

USAGE
  handbill admin tier [flags] <owner> <tier>

ARGUMENTS
  owner string    The account as the deployment names it: `gh:<numeric id>`
  tier choice     The tier that account is on from now on

FLAGS
  --endpoint string    Base URL of the deployment; beats HANDBILL_ENDPOINT and the config file
  --json               Print the result as one JSON object on stdout

EXAMPLES
  # Every live key that account holds moves to the paid quotas
  handbill admin tier gh:4242 paid

  # And back, when it lapses
  handbill admin tier gh:4242 free

handbill completions

DESCRIPTION
  Print a shell completion script for bash, zsh or fish.

USAGE
  handbill completions [flags] <shell>

ARGUMENTS
  shell choice

FLAGS
  --json    Print the result as one JSON object on stdout