Overview

Headless access to your Floggy blog, notes, tasks, profile, and analytics. Everything you can do in the dashboard plus a few things you cannot (backdated posts, bulk export, scriptable pipes).

What it is

A Bun-powered CLI in cli/ of the Floggy repo. It talks to the Floggy API over HTTPS using a personal API key. Read commands support --json for piping into jq. Write commands print human output to stdout and informational noise to stderr so they compose with shell pipelines.

Install

Install the CLI globally with your package manager of choice:

This puts a floggy binary on your PATH, so every command below runs as floggy <cmd>.

Generating an API key

  1. Open the dashboard, go to Settings, then Developer.
  2. Create a new key. Pick the scopes you need (table below). The key is shown once; copy it now.
  3. Run floggy login and paste the key when prompted, or export it as an env var:
export FLOGGY_API_KEY=flg_xxxxxxxxxxxxxxxxxx

Env vars override ~/.floggy/config.json if both are set.

Scopes

Command group Required scope(s)
whoami, profile show profile:read
profile update profile:write
posts list/get/search/export posts:read
posts create/edit/publish/delete posts:write
upload uploads:write
notes list/get/search notes:read
notes create/edit/delete/restore/empty-trash notes:write
folders list, note-labels list notes:read
folders create/edit/delete, note-labels create/edit/delete notes:write
tasks list/get tasks:read
tasks create/edit/done/reopen/delete tasks:write
projects list, labels list tasks:read
projects create/edit/delete, labels create/edit/delete tasks:write
analytics * analytics:read
coauthors list/search/requests posts:read
coauthors add/remove posts:write
sections list/create/delete profile:read / profile:write
nav list/settings/add/delete profile:read / profile:write

A 403 names the missing scope so you can regenerate the key.

Configuration

Config lives at:

  • macOS / Linux: ~/.floggy/config.json
  • Windows: %USERPROFILE%\.floggy\config.json

Show it from the CLI:

floggy config              # pretty (key shown as prefix only, never full)
floggy config show --json  # raw json
floggy config path         # print the file path

Env var overrides:

  • FLOGGY_API_KEY - takes precedence over saved key (good for CI)

Auth

floggy login                       # paste key, validates your key
floggy logout                      # remove ~/.floggy/config.json
floggy whoami                      # cached user from config
floggy whoami --refresh            # fetch fresh account info
floggy whoami --json

Output (whoami --refresh):

alex <alex@example.com>
id: aBcD1234EfGh5678IjKl

Version

floggy version
floggy --version

Output conventions

  • Pretty colored output by default (kleur). Disable colors by setting NO_COLOR=1.
  • --json on every read command emits raw JSON to stdout.
  • upload puts only the URL on stdout. Info goes to stderr so URL=$(floggy upload ...) works.

Errors

Status Message Cause
401 key invalid or revoked, run \floggy login`` Missing or revoked key. Re-run login or fix FLOGGY_API_KEY.
403 key missing scope <x>, regenerate with that scope Generate a new key with the listed scope.
404 (analytics) Error: HTTP 404 Analytics are not enabled on your account yet.
Network Network error: <reason> One automatic retry with 500 ms backoff before failing.

Next

  • Posts - create, edit, publish, export, and upload.
  • Notes - notes, folders, and labels.
  • Tasks - tasks, projects, and labels.
  • Analytics - metrics and co-authors.
  • Recipes - pipe patterns, sections, navigation, profile, and conversion notes.