Recipes

Scriptable pipe patterns, profile sections and navigation, markdown conversion internals, backdating, and known limitations.

Pipe patterns

# Upload then embed in markdown
URL=$(floggy upload screenshot.png)
echo "![screenshot]($URL)" | floggy posts create --title "Demo" --stdin --status draft

# Bulk export drafts
floggy posts export ./drafts --status draft

# Find post slugs by status
floggy posts list --json | jq -r '.[] | select(.status=="draft") | .slug'

# Show task IDs due this week
floggy tasks list --json | jq -r '.[] | select(.dueDate) | [.id, .title] | @tsv'

# Mass mark a set of tasks done
for id in $(floggy tasks list --json | jq -r '.[] | select(.title | test("CLI")) | .id'); do
  floggy tasks done "$id"
done

Sections (profile)

floggy sections list
floggy sections create --title "Talks" --type list
floggy sections delete <id>

Section types: list | gallery | timeline | cards | text | work-experience.

sections list shows each section header plus its existing items. Item create/edit is intentionally not exposed in the CLI - those flows are easier in the dashboard.

floggy nav list
floggy nav settings
floggy nav add "Docs" docs.example.com           # https:// auto-prefixed
floggy nav add "Buy" /pricing --cta              # internal path + CTA flag
floggy nav add "External" https://x.com --external
floggy nav delete <id>

URLs without a scheme that look like a host get https:// auto-prefixed (project rule). Paths starting with / are kept as-is.

Profile

floggy profile show
floggy profile show --json
floggy profile update --bio "Builder" --display-name "Pedro"
floggy profile update --avatar https://... --cv-url https://...

Markdown -> Tiptap (create / edit)

posts create --file foo.md runs:

  1. marked.parse(md) -> HTML
  2. @tiptap/html generateJSON(html, [StarterKit, Image, Link, CodeBlockLowlight]) -> Tiptap JSON

The extensions match the editor minus interactive-only nodes (Video, Audio, Embed, etc.) which standard markdown does not produce. To bypass conversion entirely, pass --json <path> with a raw Tiptap document.

Tiptap -> markdown (export)

posts export is best-effort. The walker handles:

  • Paragraphs, headings (h1-h6)
  • Bold, italic, code, strike, links
  • Bullet and ordered lists (with one level of nesting)
  • Code blocks (with language hint)
  • Blockquotes, horizontal rules, hard breaks
  • Inline and block images

It does NOT round-trip:

  • Custom embeds, video, audio, social embeds
  • Tables (rendered as plain text, structure lost)
  • Custom block nodes (Callout, Spotify, etc.)
  • Mark attributes beyond the common ones above

The CLI does not attempt to remap image URLs - your exported markdown still references the original /upload/... URLs.

Backdated posts

The web editor sets publishedAt = Date.now() on publish. The CLI lets you set any ISO timestamp:

floggy posts create --title "Vintage" --file old.md --status published \
  --published-at 2023-08-12T10:00:00Z

# Or backdate at publish time:
floggy posts publish <id> --at 2023-08-12T10:00:00Z

# Re-publishing a backdated draft from the CLI keeps its date by default
# (the CLI re-sends the existing publishedAt before patching status).

Limitations

  • API keys cannot manage other API keys. Create or revoke them in the dashboard.
  • posts get by slug only resolves slugs you own.
  • No project-local config file - only ~/.floggy/config.json (or env vars).
  • Section item CRUD is not in the CLI by design - use the dashboard.
  • Co-author requests can be listed but not yet accepted or rejected from the CLI.
  • Analytics are available once enabled on your account.