# Floggy Documentation
> Full documentation corpus for Floggy. Each section below is one page, in sidebar order, separated by a horizontal rule.

## For coding agents: install the Floggy skill

If you are an AI coding agent (Claude Code, Codex, Cursor, and friends) setting up Floggy for a user, install the Floggy skill first so you keep the knowledge of how to publish to and read from their blog:

1. Find the user's agent config directory. It is a `.claude/` or `.agents/` folder, either in the project root (project-local, preferred) or in their home directory (global).
2. Inside it, make sure a `skills/` folder exists. Create it if missing.
3. Inside `skills/`, create a `floggy/` folder.
4. Fetch `/skills/floggy/SKILL.md` and save it verbatim as `skills/floggy/SKILL.md`.

Resulting layout:

```
.claude/skills/floggy/SKILL.md
```

That is all. The skill loads as `floggy` on your next run. It teaches the `floggy` CLI (publish and manage posts, notes, tasks, uploads) and the `@floggy/cms` library (read published content into any site), and points back to these docs for exact commands.

Every action is scoped by an API key the user creates in the dashboard (Settings then Developer), so a key only ever has the access they grant it.

---

# Getting started / Introduction
Source: /docs/introduction

Floggy is your corner of the internet. One place to publish writing, show your work, keep your notes and tasks, and let people book time with you - all under a domain and identity you own.

Most tools make you choose: a blog here, a portfolio there, a scheduling link somewhere else. Floggy puts them together so your readers meet one coherent version of you, and you keep control of your address and your data.

## What Floggy is

Floggy is a hosted platform for building an independent presence on the web:

- **A blog** written in a full-screen editor, not a cramped text box.
- **A portfolio** with custom sections for projects, experience, links, galleries, and more.
- **Notes and tasks** that live right beside your writing.
- **Bookings** so readers can grab time on your calendar.
- **Your own address**, either a free `you.floggy.xyz` subdomain or a custom domain you already own.

Your content is yours. You can export everything to a single JSON file at any time.

## Who it's for

Floggy fits anyone building a personal, independent tech identity: writers, engineers, designers, founders, and freelancers who want a real home online instead of a profile on someone else's platform.

If you can write a document, you can run a Floggy site. Nothing here needs code. There is also a developer path (SDK and CLI) for people who want to pull their content into other apps, but that is entirely optional.

## What you can build

- A writing-first blog with tags, drafts, and scheduled posts.
- A portfolio homepage that leads with who you are and what you've shipped.
- A newsletter your readers can subscribe to, sent straight from your posts.
- A booking page where people schedule calls against your real availability.
- A private workspace of notes and tasks that only you see.

## Free and Pro

Floggy has a Free tier and a Pro tier. Free covers the core: your blog, portfolio, subdomain, and recent analytics. Pro unlocks premium themes, a custom domain, the newsletter, calendar bookings, notes, tasks, full analytics history, and the headless CMS. You can see the current plan details and pricing in **Settings > Billing**.

## Map of the docs

Start here, then branch out:

| Guide | What it covers |
|-------|----------------|
| [Quickstart](/docs/getting-started/quickstart) | Signup to a live blog in a few minutes |
| [Your blog](/docs/getting-started/your-blog) | Subdomain, custom domain, profile, sections, navigation |
| [Writing](/docs/getting-started/writing) | The editor, drafts, publishing, visibility, images |
| [Custom domain](/docs/getting-started/custom-domain) | Connecting a domain you own |
| [Themes](/docs/getting-started/themes) | Choosing and customizing your look |
| [Calendar](/docs/getting-started/calendar) | Connecting a calendar and taking bookings |
| [Analytics](/docs/getting-started/analytics) | Who's reading, and how you'd know |

Building something on top of Floggy? The [CMS SDK](/docs/cms) (`@floggy/cms`) and the [CLI](/docs/cli) (`@floggy/cli`) have their own docs.

---

# Getting started / Quick start
Source: /docs/quickstart

This is the fastest path from a fresh signup to a live blog you can share. Plan for a few minutes. You don't need any technical setup.

## 1. Create your account

Go to the signup page and create an account. Once you're in, Floggy takes you straight into onboarding.

## 2. Pick your username

Your username becomes your web address. Whatever you choose here, your blog goes live at:

```
https://your-username.floggy.xyz
```

Pick something short and recognizable. You can connect a custom domain later without losing this address.

## 3. Fill in your profile

Onboarding walks you through a few short steps. Add:

- A **display name** and a one or two line **bio**.
- A **profile photo**.
- Your **work status** (hidden, "Open to opportunities", or "Currently employed" with your role and company).
- **Social links** to the places people can find you.

Every step is skippable. You can change all of it later in **Settings > Profile**.

## 4. Add sections and choose a theme

Still in onboarding, you can add portfolio **sections** (like Projects or Experience), set up your **navigation** menu, and choose a **theme**. The live preview on the side updates as you go. Skip anything you're not ready for.

## 5. Write your first post

From your dashboard, open **Posts** and click **New Post**. This opens the full-screen editor. Give the post a title, write your content, and optionally add a cover image and a short excerpt.

For the full tour of the editor, see [Writing](/docs/getting-started/writing).

## 6. Publish it

In the editor, set the post's **Status** to **Published** and its **Visibility** to **Public**. That's it - the post is live.

## 7. View your public site

Open your blog in a new tab:

```
https://your-username.floggy.xyz
```

You'll see your profile, your sections, and your new post exactly as visitors do. Copy that link and share it anywhere.

## Where to go next

- Shape your public presence in [Your blog](/docs/getting-started/your-blog).
- Use a domain you own in [Custom domain](/docs/getting-started/custom-domain).
- Change your look in [Themes](/docs/getting-started/themes).

---

# Getting started / Create your blog
Source: /docs/your-blog

Your Floggy site is your public presence: your address, your profile, your portfolio sections, and your navigation. This guide covers what visitors see and how you shape it.

## Your address

Every account gets a free subdomain:

```
https://your-username.floggy.xyz
```

This is live from day one and never expires. On the Pro tier you can also connect a domain you already own, like `yourname.com`, and it becomes your blog's main address. See [Custom domain](/docs/getting-started/custom-domain) for the setup.

You'll find your address any time in **Settings > Domain**, which shows both your subdomain and any custom domain you've added.

### Preview vs public

There are two ways to look at your site:

- **Public view** is what everyone sees, at your subdomain or custom domain.
- **Preview** is the owner-only editor and admin view at `/preview/your-username`. Only you can open it. If someone else tries, they're sent to your public site instead.

You'll use preview to write posts and customize your theme, and the public URL to share.

## Your profile

Your profile is the top of your homepage. Edit it in **Settings > Profile**:

- **Profile picture**, **display name**, and **bio**.
- **Work status**: choose "Don't display", "Open to opportunities" (shows a badge), or "Currently employed" (shows your role and company, with an optional company logo and website).
- **Social links** to your other accounts.

There's also a **Co-authoring** toggle here. When it's on, other Floggy users can invite you to co-author their posts.

## Portfolio sections

Sections are the custom blocks that make up your homepage below your profile - things like Projects, Experience, Skills, or a gallery. Manage them in **Settings > Sections**.

Sections come in a few shapes so you can present different kinds of content:

| Layout | Good for |
|--------|----------|
| Text | An about blurb or any prose |
| List | Links, roles, or simple line items |
| Cards | Projects or featured work |
| Timeline | Experience or a history |
| Gallery | Images and visual work |

Add as many as you like and reorder them to control how your homepage reads.

## Navigation

Your navigation menu is the set of links at the top of your site. Edit it in **Settings > Navigation** to add links to your own pages or to external sites. This is how visitors move between your homepage, your blog, and anywhere else you want to point them.

## Your blog page and homepage layout

In **Settings > Blog** you control how your posts appear:

- **Blog layout** sets how posts show on your homepage.
- **Posts section title** is the heading above them (default is "Latest" - try "Writing", "Posts", or "Articles").
- **Blog page layout** sets how posts look on your full blog page, as a **List**, **Grid**, or **Compact** view.

## What visitors see

Put together, a visitor landing on your site sees:

1. Your profile - photo, name, bio, and status.
2. Your portfolio sections in the order you set.
3. Your posts, in the layout you chose.
4. Your navigation menu to reach everything else.

To change the overall style and colors, head to [Themes](/docs/getting-started/themes).

---

# Getting started / Writing posts
Source: /docs/writing

Writing on Floggy happens in a full-screen editor, not a small box wedged into the dashboard. This guide covers writing, publishing, and managing your posts.

## The editor

From your dashboard, open **Posts** and click **New Post**. This opens the full-view editor, built on a rich (Tiptap) writing surface. You get a clean, distraction-light page with room to actually write.

A post has these parts:

- **Cover image** - an optional image shown at the top of the post.
- **Title** - required.
- **Excerpt** - an optional short summary used in listings and previews.
- **Content** - your main writing, with rich formatting (headings, lists, quotes, links, images, and more).

Your work is saved as you go, so you can leave and come back.

## Drafts vs published

Every post has a **Status**:

- **Draft** - only you can see it. This is where posts start.
- **Published** - live on your site (subject to visibility, below).

You can flip a post between draft and published at any time from the editor, or in bulk from the posts list.

## Visibility

Separate from status, each post has a **Visibility** setting that controls who can reach it once published:

| Visibility | Who can see it |
|------------|----------------|
| Public | Anyone. Shows up on your blog and in listings. |
| Link only | Anyone with the direct link, but it's not listed publicly. |
| Private | Only you. |

Use **Link only** for something you want to share with a few people without putting it on your homepage.

## Images and uploads

Add a **cover image** at the top of the editor, and drop images directly into your content while writing. Uploads are hosted for you - no separate image host needed.

## Publishing and promoting

When you create a post, you can opt into a **publishing flow** that automatically creates a small set of linked tasks (draft, edit, publish, promote) so you can track a post from idea to launch. This is optional and off unless you turn it on.

The first time you publish a public post, Floggy can offer to send it to your newsletter subscribers, if you have the newsletter set up. See the newsletter section in **Settings** for details.

## Scheduling and backdating

Posts can be **scheduled**: a published post with a future date shows up in your posts list with a "scheduled" badge until its time comes. In the posts list you can filter by **All**, **Published**, **Scheduled**, and **Draft** to keep track.

Setting a specific future publish time or backdating a post to an earlier date is handled through the [CLI](/docs/cli), which gives you precise control over publish dates.

## Managing your posts

The **Posts** page is your control center:

- **Search** posts by title.
- **Filter** by status (all, published, scheduled, draft).
- **Sort** by date, title, or views.
- **Bulk actions**: select multiple posts to publish, unpublish, or delete them at once.
- **Copy URL** to grab a post's public link, or open it in a new tab.
- **Views** show next to each post so you can see what's landing.

Tags help you group related posts together and are carried with your content when you export. If you invite collaborators, co-authored posts appear under the **Co-Authored** tab.

---

# Getting started / Custom domain
Source: /docs/custom-domain

Your blog lives at `your-username.floggy.xyz` by default. On the Pro tier you can point a domain you own at it instead, so your site loads at your own address. This guide walks through it.

## Before you start

- Connecting a custom domain is a **Pro** feature. You can check your plan in **Settings > Billing**.
- You need a domain you already own, and access to its DNS settings (at your registrar or DNS provider, like Cloudflare, Namecheap, or GoDaddy).

## 1. Add your domain

Go to **Settings > Domain**. You'll see your Floggy subdomain listed, and a **Custom Domain** field below it.

Type in the domain you want to use and click **Save**. You don't need to include `https://` - just the domain itself:

```
yourdomain.com
```

## 2. Add the DNS record

After you save, Floggy shows the exact DNS record to add. Copy it into your DNS provider. It's a **CNAME** record that points your domain at Floggy's hosting:

| Type | Name | Value |
|------|------|-------|
| CNAME | your domain | (shown in the dashboard) |

Always use the exact value shown in **Settings > Domain** - that screen is the source of truth. DNS providers word their fields slightly differently, but you're looking for "Type: CNAME", the host/name set to your domain, and the target value pasted in.

## 3. Verify

Back in **Settings > Domain**, click **Verify**. Floggy checks whether your DNS record is live and pointing the right way.

DNS changes can take a little time to spread across the internet - sometimes minutes, occasionally longer. Floggy also re-checks automatically in the background while you're on the Domain tab, so if it doesn't verify immediately, leave it a bit and check again. Once it succeeds, you'll see a "Domain verified and active" confirmation.

## 4. You're live

Once verified, your custom domain becomes your blog's main address. Everything - your homepage, posts, booking page, and links - now uses it.

## Managing your domain

- To stop using a custom domain, open **Settings > Domain** and click **Remove**. Your `your-username.floggy.xyz` subdomain keeps working as always.
- Your subdomain never goes away, even with a custom domain connected. It stays available as a fallback.

## Troubleshooting

- **Verify keeps failing.** Double-check the record against what the dashboard shows, and confirm you added it to the correct domain. Newly added records can take time to propagate.
- **The domain loads the wrong site.** Make sure there isn't an older conflicting record (for example an existing A or CNAME on the same name) at your DNS provider.

---

# Getting started / Themes
Source: /docs/themes

A theme sets the overall look of your site - its layout, typography, and feel. Floggy ships with a handful of themes, and you can fine-tune colors and details on top of any of them. This guide covers choosing and customizing your theme.

## Choosing a theme

Go to **Settings > Theme**. You'll see a card for each available theme with a small preview. Click one to select it, then click **Save Theme**. Your site reloads with the new look.

The built-in themes:

| Theme | Style |
|-------|-------|
| Floggy | Clean, minimal blog theme (the default) |
| Void | Dark, focused, typography-first |
| Snow | Light, warm, minimal portfolio (Pro) |
| Memento | Dark editorial, typographic, compact |

**Floggy** is the default and a safe starting point. Some themes are marked **Pro** and show a lock until you upgrade.

## Customizing your theme

Choosing a theme sets the foundation. To adjust colors, typography, and spacing, you customize on the live blog itself rather than inside the dashboard.

From **Settings > Theme**, click **Open Blog & Customize**. This opens your blog in customize mode (the owner-only preview) where you can tweak the details and see changes on your real content as you make them.

## Blog layout options

Separate from the visual theme, you control how your posts are laid out in **Settings > Blog**:

- **Blog layout** - how posts appear on your homepage.
- **Blog page layout** - how posts appear on your full blog page: **List**, **Grid**, or **Compact**.

These work with any theme, so you can mix a theme's style with the post layout you prefer.

## Favicon

While you're in **Settings > Theme**, you can upload a custom **favicon** - the small icon shown in browser tabs and bookmarks. A 32x32 or 64x64 PNG works well. Leave it blank to use the default.

## Premium themes

Premium themes are part of **Pro**. Beyond the Pro themes shown in the picker, some themes unlock with a code: on the Theme tab, use **Import Theme** and enter a theme code to add it to your account.

## Exporting your look

Your theme choice, colors, and favicon are included when you export your data from **Settings > Export/Import**, so you can back them up or move them between accounts.

---

# Getting started / Calendar & bookings
Source: /docs/calendar

Floggy can turn your site into a booking page. Connect your calendar, set your availability, and visitors can grab time with you against your real schedule. This guide covers the setup.

## Before you start

Calendar booking is a **Pro** feature. You can check your plan in **Settings > Billing**. You manage everything from the **Calendar** section of your dashboard, which is organized into tabs: Connection, Availability, Meeting, Anti-Spam, and Bookings.

## 1. Connect your calendar

Open **Calendar > Connection** and click **Connect Google Calendar**. You'll be sent to Google to grant access, then returned to Floggy. Once connected, your account and email show here, and you can disconnect at any time.

Google Calendar is supported today. Microsoft is marked "Coming Soon".

## 2. Turn on bookings

With a calendar connected, flip on **Accept Bookings**. Floggy shows your public booking page URL, which lives at:

```
https://your-username.floggy.xyz/catchup
```

If you've connected a custom domain, it uses that instead. Share this link, or let visitors reach it from your site.

## 3. Set your availability

In the **Availability** tab:

- **Timezone** - Floggy auto-detects yours; you can search and change it. Visitors see times converted to their own timezone automatically.
- **Weekly schedule** - enable the days you're available and set start and end times for each. Use "Copy to all active days" to apply the same hours across your open days quickly.

## 4. Configure the meeting

In the **Meeting** tab:

| Setting | Options |
|---------|---------|
| Duration | 15, 30, 45, 60, 90, or 120 minutes |
| Buffer between meetings | None, 5, 10, 15, or 30 minutes |
| Minimum notice | None up to 1 day |
| Maximum advance | 1 week up to 3 months |

Add a **meeting title** and optional **description**, then pick how video calls are handled:

- **Google Meet** - a Meet link is generated automatically for each booking.
- **Custom link** - use your own Zoom, Around, or other meeting link.
- **No video call** - for phone or in-person meetings.

## 5. Keep spam out

The **Anti-Spam** tab covers protection. Floggy has built-in safeguards (rate limiting, a bot honeypot, and input validation) always on. You can also block specific email domains by listing them, one per line, to keep throwaway addresses out.

## Managing bookings

When someone books, the event lands on your connected calendar and the attendee gets the details. The **Bookings** tab shows your booking history - each with the booker's name, email, date and time, and status. You can cancel a confirmed booking from here, and the attendee is notified.

## Where it appears for visitors

Visitors book at your `/catchup` page. They pick a slot from your available times (shown in their own timezone), enter their details, and confirm. That's it - the meeting shows up on both calendars.

---

# Getting started / Analytics
Source: /docs/analytics

Floggy has built-in analytics so you can see who's reading without adding a tracking script or wiring up a third-party dashboard. This guide covers what's tracked and where to find it.

## Where to find it

Open **Analytics** from your dashboard. If tracking is still being set up for your site, you'll see a short "not configured yet" note; otherwise your numbers load right in.

## The headline numbers

At the top you get four stat cards, each compared against the previous period:

| Metric | What it means |
|--------|---------------|
| Visitors | Unique people who came to your site |
| Pageviews | Total pages loaded |
| Bounce rate | Share of visits that left after one page |
| Avg. time | Average time spent per visit |

Below that, a chart plots visitors and pageviews over time so you can spot trends.

## Real-time

When people are on your site right now, a live **"X online"** badge appears at the top. It refreshes automatically every 30 seconds.

## Digging in

Tabs break your traffic down further:

- **Overview** - top pages and top referrers side by side.
- **Pages** - your most-visited pages, including individual posts.
- **Referrers** - where visitors came from (search, social, direct, other sites).
- **Devices** - browsers, operating systems, and device types.
- **Countries** - where your readers are in the world.

There's also a quick insights strip that surfaces highlights from your data.

## Time ranges and tiers

Use the period selector (top right) to change the window. **Free** accounts see the last **7 days**. **Pro** unlocks the longer ranges: 30 days, 90 days, 6 months, 1 year, and all-time. You can check your plan in **Settings > Billing**.

## Privacy-friendly by design

Floggy's analytics are privacy-first. They focus on aggregate traffic - views, sources, rough location and device - rather than tracking individuals across the web, so you get what you need to understand your audience without invasive profiling.

## If your numbers look empty

- **Brand-new site?** Data appears as you start getting traffic. Give it time.
- **Everything reads zero or fails to load?** An ad blocker or privacy extension in your own browser may be blocking the analytics request. Try disabling it for your site, or check from another browser.

---

# CMS SDK / Overview
Source: /docs/cms

`@floggy/cms` is the single dependency you install to build a blog on [Floggy](https://floggy.xyz). It returns your content fully typed and ready to render - html, markdown, SEO metadata, JSON-LD, and feeds - so you drop it straight into your pages. Zero runtime dependencies.

## Install

```install
npm install @floggy/cms
pnpm add @floggy/cms
bun add @floggy/cms
yarn add @floggy/cms
```

## Quickstart

A working blog index plus a post page, with SEO, in about 15 lines.

```ts
import { createClient } from "@floggy/cms";

const floggy = createClient({ project: "projecta" });

// Blog index
const { posts, pageInfo } = await floggy.posts.list({ page: 1, perPage: 10 });
for (const post of posts) {
  console.log(post.title, "/" + post.slug);
}

// Post page (rendered HTML + adjacent nav + SEO block + JSON-LD)
const post = await floggy.posts.get("hello-world", { format: "html" });
console.log(post.rendered);          // ready-to-inject HTML string
console.log(post.adjacent.prev);     // { slug, title } | null
const metadata = floggy.seo.meta(post); // plain Next.js-compatible Metadata object
```

## Configuration

```ts
createClient({
  project: "projecta",                 // required: the Floggy username/project
  key: process.env.FLOGGY_KEY,         // optional: flg_ key for drafts/private content
  site: {                              // optional: used by feeds.*
    url: "blog.example.com",           // public origin (protocol auto-added)
    name: "Example",                   // defaults to project name
    description: "My blog",            // defaults to "<name>'s blog"
    locale: "en",                      // defaults to "en"
  },
  fetch: customFetch,                  // optional: custom fetch implementation
});
```

## Auth

Public reads need no key. Pass an `flg_` key only to read drafts or private content. Use a Read-only key in any frontend - a leaked read key only exposes content that is already public. Never embed a Full-access key in a frontend.

```ts
const floggy = createClient({ project: "projecta", key: process.env.FLOGGY_KEY });
```

## Methods at a glance

The client exposes four namespaces:

- `posts` - `list`, `get`, `search`
- `tags` - `list`
- `seo` - `meta`, `jsonLd`
- `feeds` - `sitemap`, `rss`, `robots`

See the [SDK reference](/docs/cms/sdk) for full signatures, options, and return shapes.

## Errors

Every non-2xx response throws a typed error.

```ts
import { FloggyError, RateLimitError } from "@floggy/cms";

try {
  await floggy.posts.get("missing");
} catch (err) {
  if (err instanceof RateLimitError) {
    console.log("retry after", err.retryAfter, "seconds");
  } else if (err instanceof FloggyError) {
    console.log(err.status, err.message, err.code);
  }
}
```

`FloggyError` carries `status`, `message`, `code`, and `url`. `RateLimitError` (status 429) adds `retryAfter` (seconds, parsed from the Retry-After header).

## Next

- [Quickstart](/docs/cms/quickstart) - list, fetch, render, and add SEO in about 15 lines.
- [SDK reference](/docs/cms/sdk) - every `@floggy/cms` method, with Next.js and TanStack Start examples.
- [Authentication](/docs/cms/authentication) - creating `flg_` keys, the scope table, presets, and key-safety rules.
- [Webhooks](/docs/cms/webhooks) - subscribe to `post.published` / `post.updated` and verify signatures.

---

# CMS SDK / Quickstart
Source: /docs/cms/quickstart

A blog index, a rendered post, and SEO metadata. About 15 lines.

## Install

```install
npm install @floggy/cms
pnpm add @floggy/cms
bun add @floggy/cms
yarn add @floggy/cms
```

## The loop: list, fetch, render, describe

```ts
import { createClient } from "@floggy/cms";

// No key needed for published, public content.
const floggy = createClient({ project: "projecta" });

// Blog index
const { posts, pageInfo } = await floggy.posts.list({ page: 1, perPage: 10 });
for (const post of posts) {
  console.log(post.title, "/" + post.slug);
}
console.log(`page ${pageInfo.page}, hasMore: ${pageInfo.hasMore}`);

// One post, rendered to HTML, with SEO ready to drop in
const post = await floggy.posts.get("hello-world", { format: "html" });
console.log(post.rendered);        // ready-to-inject HTML string
const metadata = floggy.seo.meta(post); // Next.js-compatible Metadata object
```

That is the whole loop: list, fetch, render, describe.

## Next.js App Router

A complete post page with metadata, rendered HTML, and JSON-LD.

```tsx
// app/[slug]/page.tsx
import { createClient } from "@floggy/cms";

const floggy = createClient({ project: "projecta" });

export async function generateMetadata({ params }: { params: { slug: string } }) {
  const post = await floggy.posts.get(params.slug);
  return floggy.seo.meta(post); // title, description, openGraph, twitter, alternates.canonical, robots
}

export default async function PostPage({ params }: { params: { slug: string } }) {
  const post = await floggy.posts.get(params.slug, { format: "html" });
  return (
    <article>
      <h1>{post.title}</h1>
      {floggy.seo.jsonLd(post).map((node, i) => (
        <script
          key={i}
          type="application/ld+json"
          dangerouslySetInnerHTML={{ __html: JSON.stringify(node) }}
        />
      ))}
      <div dangerouslySetInnerHTML={{ __html: post.rendered ?? "" }} />
    </article>
  );
}
```

## Drop-in feed routes

```ts
// app/sitemap.xml/route.ts
import { createClient } from "@floggy/cms";

const floggy = createClient({
  project: "projecta",
  site: { url: "blog.example.com", name: "Example", description: "My blog" },
});

export async function GET() {
  return new Response(await floggy.feeds.sitemap(), {
    headers: { "Content-Type": "application/xml" },
  });
}
```

The same pattern works for `floggy.feeds.rss()` (`application/rss+xml`) and `floggy.feeds.robots()` (`text/plain`).

## Next steps

- Build a real page (`generateMetadata`, JSON-LD, feeds): [SDK reference](/docs/cms/sdk)
- Need drafts or private content? Add a key: [Authentication](/docs/cms/authentication)
- Revalidate your frontend on publish: [Webhooks](/docs/cms/webhooks)

---

# CMS SDK / SDK reference
Source: /docs/cms/sdk

`@floggy/cms` is a thin, fully typed client for your Floggy content. It fetches your posts, tags, SEO metadata, JSON-LD, and feeds and returns them fully typed. Zero runtime dependencies - it uses the platform `fetch`.

```install
npm install @floggy/cms
pnpm add @floggy/cms
bun add @floggy/cms
yarn add @floggy/cms
```

## `createClient(config)`

```ts
import { createClient } from "@floggy/cms";

const floggy = createClient({
  project: "projecta",                 // required: the Floggy username / project
  key: process.env.FLOGGY_API_KEY,     // optional: flg_ key for drafts / private content
  site: {                              // optional: used by feeds.*
    url: "blog.example.com",           // public origin; protocol auto-added if missing
    name: "Example",                   // defaults to the project name
    description: "My blog",            // defaults to "<name>'s blog"
    locale: "en",                      // defaults to "en"
  },
  fetch: customFetch,                  // optional: custom fetch implementation
});
```

`project` is required. `key` is only needed for non-public content; leave it out for a purely public blog. Returns a `FloggyClient` with four namespaces: `posts`, `tags`, `seo`, `feeds`.

## `posts`

### `posts.list(options?)` -> `Promise<{ posts, pageInfo }>`

Lists published posts. Always paginated (the SDK always sends `page`/`perPage`, so you always get the envelope).

| Option | Type | Default |
|--------|------|---------|
| `page` | `number` | `1` |
| `perPage` | `number` | `10` (capped at 50) |
| `tag` | `string` | - |
| `sort` | `"publishedAt:desc" \| "publishedAt:asc"` | `"publishedAt:desc"` |
| `format` | `"tiptap" \| "html" \| "markdown"` | `"tiptap"` |

`pageInfo` is `{ total, page, perPage, hasMore }`.

### `posts.get(slug, options?)` -> `Promise<PostDetail>`

Fetches one post. `PostDetail` is the post fields plus:

- `rendered` - html/markdown string when `format` is not `tiptap`, else `null`
- `content` - always the raw Tiptap JSON
- `adjacent` - `{ prev, next }`, each `{ slug, title } | null`
- `seo` - server-computed SEO block
- `jsonLd` - array of JSON-LD nodes

Options: `{ format?: "tiptap" | "html" | "markdown" }`.

### `posts.search(query, options?)` -> `Promise<Post[]>`

Full-text search across published posts (title + excerpt). Returns a flat array. Options: `{ format? }`.

## `tags`

### `tags.list()` -> `Promise<TagWithCount[]>`

Returns `[{ name, slug, count }]`, sorted by count descending.

## `seo`

### `seo.meta(post)` -> `Metadata`

Reshapes a post's `seo` block into a plain object compatible with Next.js `Metadata` and TanStack head builders: `title`, `description`, `keywords`, `alternates.canonical`, `robots`, `openGraph`, `twitter`. Framework-agnostic, no framework import. Synchronous.

### `seo.jsonLd(post)` -> `JsonLd[]`

Returns the post's JSON-LD nodes, ready to inject as `<script type="application/ld+json">`. Synchronous.

## `feeds`

Driven by `site` in the client config.

### `feeds.sitemap()` -> `Promise<string>`

Fetches all published posts and returns a sitemap.xml string.

### `feeds.rss()` -> `Promise<string>`

Returns an RSS 2.0 feed string (most recent 20 posts).

### `feeds.robots()` -> `string`

Returns a robots.txt string pointing at the sitemap and feed. Synchronous.

## Errors

Every non-2xx response throws a typed error.

```ts
import { FloggyError, RateLimitError } from "@floggy/cms";

try {
  await floggy.posts.get("missing");
} catch (err) {
  if (err instanceof RateLimitError) {
    console.log("retry after", err.retryAfter, "seconds");
  } else if (err instanceof FloggyError) {
    console.log(err.status, err.message, err.code);
  }
}
```

`FloggyError` carries `status`, `message`, `code`, `url`. `RateLimitError` (status 429) adds `retryAfter` (seconds, parsed from the `Retry-After` header).

## Next.js (App Router)

A complete post page with metadata, rendered HTML, and JSON-LD.

```tsx
// app/[slug]/page.tsx
import { createClient } from "@floggy/cms";

const floggy = createClient({ project: "projecta" });

export async function generateMetadata({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const post = await floggy.posts.get(slug);
  return floggy.seo.meta(post); // title, description, openGraph, twitter, alternates.canonical, robots
}

export default async function PostPage({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const post = await floggy.posts.get(slug, { format: "html" });

  return (
    <article>
      <h1>{post.title}</h1>
      {floggy.seo.jsonLd(post).map((node, i) => (
        <script
          key={i}
          type="application/ld+json"
          dangerouslySetInnerHTML={{ __html: JSON.stringify(node) }}
        />
      ))}
      <div dangerouslySetInnerHTML={{ __html: post.rendered ?? "" }} />
    </article>
  );
}
```

### Drop-in feed routes

```ts
// app/sitemap.xml/route.ts
import { createClient } from "@floggy/cms";

const floggy = createClient({
  project: "projecta",
  site: { url: "blog.example.com", name: "Example", description: "My blog" },
});

export async function GET() {
  return new Response(await floggy.feeds.sitemap(), {
    headers: { "Content-Type": "application/xml" },
  });
}
```

```ts
// app/rss.xml/route.ts
import { floggy } from "@/lib/floggy"; // a shared client with `site` set

export async function GET() {
  return new Response(await floggy.feeds.rss(), {
    headers: { "Content-Type": "application/rss+xml" },
  });
}
```

```ts
// app/robots.txt/route.ts
import { floggy } from "@/lib/floggy";

export function GET() {
  return new Response(floggy.feeds.robots(), {
    headers: { "Content-Type": "text/plain" },
  });
}
```

Reuse one client across routes by exporting it from `lib/floggy.ts` with `site` configured, so the feed builders know your public origin.

## TanStack Start

`seo.meta` returns a plain object, so it slots straight into a route's `head`.

```tsx
// src/routes/$slug.tsx
import { createFileRoute } from "@tanstack/react-start";
import { createClient } from "@floggy/cms";

const floggy = createClient({ project: "projecta" });

export const Route = createFileRoute("/$slug")({
  loader: ({ params }) => floggy.posts.get(params.slug, { format: "html" }),
  head: ({ loaderData: post }) => {
    const meta = floggy.seo.meta(post);
    return {
      meta: [
        { title: meta.title },
        { name: "description", content: meta.description },
        { property: "og:title", content: meta.openGraph.title },
        { property: "og:image", content: meta.openGraph.images[0]?.url },
      ],
      links: [{ rel: "canonical", href: meta.alternates.canonical }],
    };
  },
  component: Post,
});

function Post() {
  const post = Route.useLoaderData();
  return <article dangerouslySetInnerHTML={{ __html: post.rendered ?? "" }} />;
}
```

Feed routes work the same way: a server route handler that returns `await floggy.feeds.sitemap()` / `rss()` / `floggy.feeds.robots()` with the right `Content-Type`.

---

# CMS SDK / Authentication
Source: /docs/cms/authentication

Public reads need no auth. You only need a key to read drafts and private content, or to write (create, update, delete posts) and manage webhooks.

Keys are `flg_` tokens, hashed at rest, scoped, revocable, and not expiring. Up to 5 per account.

## Creating a key

1. Open your Floggy dashboard.
2. Go to **Settings -> Developer**.
3. Create a key, pick its scopes (or a preset), and copy it.

The full key (`flg_` followed by 32 characters) is shown once at creation. Floggy stores only a hash, so it cannot show you the key again. If you lose it, revoke and create a new one.

## Using a key

Keys are created in the Dashboard (**Settings -> Developer**) and used by the SDK and CLI automatically. With the SDK, pass it as `key`:

```ts
import { createClient } from "@floggy/cms";

const floggy = createClient({
  project: "projecta",
  key: process.env.FLOGGY_API_KEY, // only needed for drafts / private content
});
```

## Scopes

A request succeeds when the key carries every scope the endpoint requires. The `*` scope satisfies all of them. A scoped key that is missing a required scope returns `403 {"error":"Insufficient scope","required":[...]}`.

| Scope | Grants |
|-------|--------|
| `posts:read` | Read your own posts, including drafts and private posts. |
| `posts:write` | Create and update posts, bulk publish/unpublish. |
| `posts:delete` | Delete posts (and bulk delete). |
| `uploads:write` | Upload media. |
| `notes:read` | Read notes. |
| `notes:write` | Create and update notes. |
| `tasks:read` | Read tasks. |
| `tasks:write` | Create and update tasks. |
| `profile:read` | Read profile / account settings. |
| `profile:write` | Update profile / account settings. |
| `analytics:read` | Read analytics. |
| `newsletter:read` | Read newsletter subscribers and data. |
| `newsletter:write` | Manage newsletter subscribers and sends. |
| `webhooks:read` | List webhook endpoints. |
| `webhooks:write` | Create, update, delete webhook endpoints. |
| `*` | Full access to everything above. Trusted automation only. |

## Presets

The create-key UI offers three presets so you do not have to hand-pick scopes:

| Preset | Scopes | Use it for |
|--------|--------|-----------|
| **Read-only** | all `*:read` (`posts:read`, `notes:read`, `tasks:read`, `profile:read`, `analytics:read`, `newsletter:read`, `webhooks:read`) | Anything a frontend touches. Safe to expose. |
| **Editor** | Read-only plus `posts:write`, `posts:delete`, `uploads:write` | CMS authoring tools, CI that publishes posts. |
| **Full access** | `*` | Your own trusted CLI and agents only. Never in a frontend. |

For a blog frontend that only consumes published content you usually need **no key at all**. Add a Read-only key only if the frontend must also fetch drafts or private posts (for example a preview build).

## Key safety and disclosure

The keys that leak in practice are the ones embedded in frontends. Minimize the blast radius before that happens.

- **Never commit keys.** Keep them out of git, source, and client bundles. Use a `.gitignore`d `.env`.
- **Use environment variables.** The convention across Floggy tooling is `FLOGGY_API_KEY`.
  ```bash
  export FLOGGY_API_KEY="flg_xxxxxxxx..."
  ```
- **Use a Read-only key for anything a browser can see.** If a Read-only key leaks, the holder can read content that is already public anyway, plus your drafts and private posts. They cannot write, delete, or change settings.
- **Never ship a Full-access (`*`) or Editor key to a frontend.** A leaked Editor key can publish and delete your posts. A leaked `*` key is a full account compromise.
- **Prefer server-side fetching.** Call the API from your server (server components, route handlers, build steps) so the key never reaches the client. A purely public blog frontend can skip the key entirely.
- **Rotate by revoke + recreate.** There is no expiry and no in-place rotation. To rotate: create the new key, deploy it, then revoke the old one in Settings -> Developer.
- **Audit usage.** Each key records a `lastUsedAt`. If a key shows unexpected activity, revoke it immediately.

### What a leaked Read-only key can and cannot do

| Can | Cannot |
|-----|--------|
| Read your published posts (already public) | Create, edit, or delete posts |
| Read your drafts and private posts | Upload media |
| Read analytics, notes, tasks, profile, newsletter data (read scopes) | Change any account settings |
| List webhook endpoints | Manage webhooks, manage subscribers, or anything `*:write` |

This is why Read-only is the right default for exposed surfaces: the worst case is read access to content you mostly publish anyway. Keep write and delete power in keys that never leave your servers.

---

# CMS SDK / Webhooks
Source: /docs/cms/webhooks

Webhooks let an external frontend revalidate when your content changes. Floggy POSTs a small payload to your endpoint whenever a post is published or updated, so you can purge a cache or trigger an ISR revalidation instead of polling.

Delivery is best-effort and fire-and-forget: it never blocks your publish, and a failed delivery is recorded on the endpoint (last status, last fired) but not retried.

## Events

| Event | Fires when |
|-------|-----------|
| `post.published` | A post goes from draft to published, or is created already published. |
| `post.updated` | An already-published post is edited. |

Notes:

- Drafts never fire anything.
- Switching a post back to draft fires nothing.
- **Known limitation:** scheduled (future-dated) posts do not fire at write time. The event only fires when the post is live now, so a post scheduled for next week will not emit `post.published` when that date arrives.

## Managing endpoints

You create and manage webhook endpoints in the Dashboard (**Settings -> Developer**). Add an endpoint URL (the scheme auto-adds `https://` when omitted), pick the events to subscribe to, and toggle delivery on or off. Up to 10 endpoints per account.

When you create an endpoint, the signing secret (`whsec_...`) is shown once. **Store it now** - it is used to verify deliveries and is not shown again. Keep it in an env var such as `FLOGGY_WEBHOOK_SECRET` on the app that receives the webhook.

## Delivery payload

Floggy POSTs JSON to your endpoint:

```json
{
  "event": "post.published",
  "post": {
    "id": "V1StGXR8_Z5jdHi6B-myT",
    "slug": "launch-day",
    "title": "Launch Day",
    "publishedAt": "2026-06-29T10:00:00.000Z",
    "updatedAt": "2026-06-29T10:00:00.000Z",
    "url": "https://projecta.floggy.xyz/launch-day"
  },
  "timestamp": "2026-06-29T10:00:00.123Z"
}
```

Headers on the request:

- `Content-Type: application/json`
- `User-Agent: Floggy-Webhooks/1.0`
- `X-Floggy-Signature: sha256=<hex>`

## Verifying the signature

`X-Floggy-Signature` is `sha256=` followed by the HMAC-SHA256 of the **raw request body**, keyed with your endpoint secret, lowercase hex. Recompute it over the exact bytes you received (do not re-serialize the parsed JSON) and compare in constant time.

```ts
// Web Crypto. Works in Workers, Deno, Bun, Node 18+, and the browser.
// Pass the RAW request body string and the X-Floggy-Signature header value.
export async function verifyFloggySignature(
  rawBody: string,
  signatureHeader: string | null,
  secret: string,
): Promise<boolean> {
  if (!signatureHeader) return false;

  const expectedHex = signatureHeader.startsWith("sha256=")
    ? signatureHeader.slice("sha256=".length)
    : signatureHeader;

  const enc = new TextEncoder();
  const key = await crypto.subtle.importKey(
    "raw",
    enc.encode(secret),
    { name: "HMAC", hash: "SHA-256" },
    false,
    ["sign"],
  );
  const sigBuf = await crypto.subtle.sign("HMAC", key, enc.encode(rawBody));
  const actualHex = [...new Uint8Array(sigBuf)]
    .map((b) => b.toString(16).padStart(2, "0"))
    .join("");

  return timingSafeEqual(actualHex, expectedHex);
}

// Constant-time string compare: never short-circuit on the first mismatch.
function timingSafeEqual(a: string, b: string): boolean {
  if (a.length !== b.length) return false;
  let diff = 0;
  for (let i = 0; i < a.length; i++) {
    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
  }
  return diff === 0;
}
```

### Next.js route handler example

```ts
// app/api/floggy-webhook/route.ts
import { verifyFloggySignature } from "@/lib/floggy-webhook";
import { revalidatePath } from "next/cache";

export async function POST(req: Request) {
  const raw = await req.text(); // read raw body BEFORE JSON.parse
  const ok = await verifyFloggySignature(
    raw,
    req.headers.get("X-Floggy-Signature"),
    process.env.FLOGGY_WEBHOOK_SECRET!,
  );
  if (!ok) return new Response("invalid signature", { status: 401 });

  const { event, post } = JSON.parse(raw) as {
    event: string;
    post: { slug: string };
  };

  revalidatePath(`/${post.slug}`);
  revalidatePath("/");
  return new Response("ok");
}
```

Reject any request whose signature does not match. The signature is the only proof the request came from Floggy and not a spoofed POST to your public endpoint.

---

# For agents / SKILL.md
Source: /docs/skill

A ready-made skill that teaches a coding agent (Claude Code, Codex, Cursor, and friends) how to publish to and read from a Floggy blog with the `floggy` CLI and the `@floggy/cms` library. Install it once and your agent knows how to create posts, upload media, and pull your content into a site.

## Install this skill

Skills live in a `skills/<name>/` folder under your agent's config directory, each with its own `SKILL.md`. Create one for Floggy:

```bash
# Claude Code / Claude agents
mkdir -p ~/.claude/skills/floggy

# Other agents (adjust the config dir to your tool, e.g. ~/.agents)
mkdir -p ~/.agents/skills/floggy
```

Then click **Copy skill** above and paste into a new `SKILL.md` inside that folder:

```
~/.claude/skills/floggy/
└── SKILL.md
```

That is it. Your agent loads it as the `floggy` skill on the next run. Prefer a project-local skill? Put the same folder under your repo's `.claude/skills/floggy/` instead.

## What the skill teaches

- **`floggy` CLI** - publish and manage posts, notes, tasks, uploads, and profile from the terminal. Read commands support `--json` for piping.
- **`@floggy/cms`** - a thin, fully typed library to read your published content (posts, tags, SEO, feeds) into any site.
- **Where to look things up** - it points the agent at the machine-readable docs below so it fetches exact commands instead of guessing.

Every action is scoped by an API key you create in the dashboard (**Settings > Developer**), so a key only ever has the access you grant it.

## Machine-readable docs

Feed these to any agent for full context. Every docs page is also available as raw markdown by appending `.md` to its URL.

- **Everything, in one file:** [`/docs/llms-full.txt`](/docs/llms-full.txt) - the entire documentation set concatenated for LLM ingestion.
- **Index:** [`/docs/llms.txt`](/docs/llms.txt) - a short table of contents linking every page.
- **Any page as markdown:** e.g. [`/docs/cli/posts.md`](/docs/cli/posts.md), [`/docs/cms/sdk.md`](/docs/cms/sdk.md).

## Where to go deeper

- [Getting started](/docs/introduction) - the product, end to end.
- [CLI overview](/docs/cli) - install, keys, scopes, every command.
- [CMS overview](/docs/cms) - the library, config, and feeds.
- [Authentication](/docs/cms/authentication) - keys, scopes, and safety.

---

# CLI / Overview
Source: /docs/cli

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:

```install
npm i -g @floggy/cli
pnpm add -g @floggy/cli
bun add -g @floggy/cli
yarn global add @floggy/cli
```

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:

```bash
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:

```bash
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

```bash
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

```bash
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](/docs/cli/posts) - create, edit, publish, export, and upload.
- [Notes](/docs/cli/notes) - notes, folders, and labels.
- [Tasks](/docs/cli/tasks) - tasks, projects, and labels.
- [Analytics](/docs/cli/analytics) - metrics and co-authors.
- [Recipes](/docs/cli/recipes) - pipe patterns, sections, navigation, profile, and conversion notes.

---

# CLI / Posts & uploads
Source: /docs/cli/posts

Manage blog posts from the terminal: list, get, search, create, edit, publish, delete, and export. Includes CLI-only backdating and image uploads.

## Posts

### list

```bash
floggy posts list
floggy posts list --status draft --limit 10
floggy posts list --json
```

```
ID            STATUS     PUBLISHED   TITLE
6N5VcqPdwU41i…published  2026-04-02  Another test post  /another-test-post
```

### get

```bash
floggy posts get <id|slug>
floggy posts get my-slug --json
```

### search

Searches your posts by title and content, including drafts.

```bash
floggy posts search "blockchain" --limit 10
floggy posts search "blockchain" --json | jq '.[].slug'
```

### create

```bash
floggy posts create --title "Hello world" --file post.md --status published
echo "# hi" | floggy posts create --title "Quick" --stdin --status draft
floggy posts create --title "Raw" --json content.json   # skip markdown conversion
```

Flags: `--title` (required), `--slug`, `--file`, `--stdin`, `--json <path>`, `--status draft|published`, `--published-at <iso>`, `--tags a,b,c`, `--visibility public|unlisted|private`, `--excerpt`.

Backdating works only via the CLI. `--published-at 2024-03-01T10:00:00Z` is preserved through publish.

### edit

```bash
floggy posts edit <id> --title "New title" --file updated.md
floggy posts edit <id> --tags "rust,systems"
```

Same flags as create, all optional. Pass `--tags ""` to clear tags.

### publish

```bash
floggy posts publish <id>
floggy posts publish <id> --at 2024-01-15T09:00:00Z
```

Backdating gotcha: Floggy sets the publish date to now on first publish. The CLI preserves a backdated draft's date by re-sending it, so a backdated draft keeps its date when published. To override explicitly, pass `--at`.

### delete

```bash
floggy posts delete <id>
```

### export

```bash
floggy posts export ./out
floggy posts export ./out --status published
```

Writes one `<slug>.md` per post into `./out` with YAML frontmatter (`title`, `slug`, `status`, `publishedAt`, `tags`, `excerpt`) and a markdown body converted from the Tiptap JSON. See [Recipes](/docs/cli/recipes) for markdown conversion notes and limits.

## Upload

```bash
floggy upload pic.png                 # URL printed to stdout, info to stderr
floggy upload pic.png --folder posts
floggy upload pic.png --json          # full JSON (key + url)
URL=$(floggy upload pic.png)
echo "![alt]($URL)"
```

Allowed: `image/jpeg`, `image/png`, `image/gif`, `image/webp`. PDFs allowed when `--folder cv`. Max 10 MB.

---

# CLI / Notes
Source: /docs/cli/notes

Manage notes, folders, and labels from the terminal. Notes support views, trash, and restore, and organize into folders and colored labels.

## Notes

```bash
floggy notes list
floggy notes list --view pinned --json
floggy notes get <id>
floggy notes create --title "Idea" --content "raw text"
floggy notes create --title "Quick" --stdin
floggy notes edit <id> --title "New title"
floggy notes search "todo" --limit 10
floggy notes delete <id>           # trashes then permanently deletes
floggy notes restore <id>          # un-trash
floggy notes empty-trash
```

Note content is stored as a string. The dashboard editor stores serialized Tiptap JSON; passing raw text is also accepted.

`notes list --view`: `all | pinned | archived | trash | recent`.

## Note folders

```bash
floggy folders list
floggy folders create --name "Reading" --icon "📚"
floggy folders edit <id> --name "Reading list"
floggy folders delete <id>
```

Folders nest at most one level deep.

## Note labels

```bash
floggy note-labels list
floggy note-labels create --name research --color "#0ea5e9"
floggy note-labels edit <id> --color "#22c55e"
floggy note-labels delete <id>
```

---

# CLI / Tasks
Source: /docs/cli/tasks

Manage tasks, projects, and labels from the terminal. Tasks support statuses, priorities, due dates, and project or label assignment.

## Tasks

```bash
floggy tasks list
floggy tasks list --status todo,in_progress --limit 20
floggy tasks get <id>
floggy tasks create --title "Ship CLI" --priority high --due-date 2026-06-01T00:00:00Z
floggy tasks edit <id> --status in_progress --priority urgent
floggy tasks edit <id> --project <projectId> --labels lbl1,lbl2
floggy tasks edit <id> --due ""        # clear due date
floggy tasks edit <id> --project ""    # clear project
floggy tasks done <id>
floggy tasks reopen <id>
floggy tasks delete <id>
```

Statuses: `backlog | todo | in_progress | done | archived` (the CLI also accepts `in-progress` and rewrites it to `in_progress`).

Priorities: `urgent | high | medium | low`.

`--labels` replaces all label links on the task. Pass `--labels ""` to clear.

## Task projects

```bash
floggy projects list
floggy projects list --status active
floggy projects create --name "Q3 launch" --description "..." --target-date 2026-09-30T00:00:00Z
floggy projects edit <id> --status done
floggy projects delete <id>
```

Project statuses: `active | paused | done | archived`. Deleting a project sets `projectId = NULL` on its tasks.

## Task labels

```bash
floggy labels list
floggy labels create --name bug --color "#ef4444"
floggy labels edit <id> --name "bug-fix"
floggy labels delete <id>
```

---

# CLI / Analytics
Source: /docs/cli/analytics

Read blog metrics and manage co-authors from the terminal. Analytics are available on your account automatically.

## Analytics

Read your blog metrics - views, top posts, realtime - straight from the terminal. If analytics are not enabled on your account yet, these commands return a 404.

```bash
floggy analytics overview                    # totals for default 7d
floggy analytics overview --period 30d
floggy analytics top-posts --limit 5         # top pages by views
floggy analytics post my-slug                # views for /my-slug
floggy analytics post <postId>               # resolves id -> slug, then queries
floggy analytics realtime                    # active visitors right now
```

`--period` accepts: `7d | 30d | 90d | 6m | 1y | all`. `--json` is supported on all.

`top-posts` filters out non-content paths (`/dashboard`, `/api`, `/login`, `/signup`).

## Co-authors

```bash
floggy coauthors list                        # posts where you are a co-author
floggy coauthors search alex                  # find Floggy users (>= 80% of name needed)
floggy coauthors requests                    # pending invites
floggy coauthors add <postId> <userId>       # owner only
floggy coauthors remove <postId> <coauthorId>
```

`coauthors search` enforces privacy: short usernames (<= 4 chars) require an exact match; longer ones require >= 80% of the username typed.

---

# CLI / Recipes
Source: /docs/cli/recipes

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

## Pipe patterns

```bash
# 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)

```bash
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.

## Navigation

```bash
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

```bash
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:

```bash
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.

---