---
name: floggy
description: Publish to and read from a Floggy blog with the `floggy` CLI and the `@floggy/cms` library. Use when the user wants to create, edit, or publish posts, manage notes/tasks, upload media, or pull their published content into a site or app.
---

# Floggy

Floggy is a hosted platform for an independent web presence - a blog, portfolio, notes, tasks, and bookings under your own domain. Two interfaces matter to an agent:

- **`floggy` CLI** - publish and manage posts, notes, tasks, uploads, and profile from the terminal.
- **`@floggy/cms`** - a thin, fully typed library to read published content (posts, tags, SEO, feeds) into any site.

## Documentation

Each page is a small markdown file. Fetch only the one that matches the task instead of loading everything - it saves tokens.

**Getting started**

- Introduction: https://floggy.xyz/docs/introduction.md
- Quick start: https://floggy.xyz/docs/quickstart.md
- Create your blog: https://floggy.xyz/docs/your-blog.md
- Writing posts: https://floggy.xyz/docs/writing.md
- Custom domain: https://floggy.xyz/docs/custom-domain.md
- Themes: https://floggy.xyz/docs/themes.md
- Calendar and bookings: https://floggy.xyz/docs/calendar.md
- Analytics: https://floggy.xyz/docs/analytics.md

**CMS library (`@floggy/cms`)**

- Overview: https://floggy.xyz/docs/cms.md
- Quickstart: https://floggy.xyz/docs/cms/quickstart.md
- SDK reference (every method): https://floggy.xyz/docs/cms/sdk.md
- Authentication and keys: https://floggy.xyz/docs/cms/authentication.md
- Webhooks: https://floggy.xyz/docs/cms/webhooks.md

**CLI (`floggy`)**

- Overview (install, keys, scopes): https://floggy.xyz/docs/cli.md
- Posts and uploads: https://floggy.xyz/docs/cli/posts.md
- Notes: https://floggy.xyz/docs/cli/notes.md
- Tasks: https://floggy.xyz/docs/cli/tasks.md
- Analytics and co-authors: https://floggy.xyz/docs/cli/analytics.md
- Recipes and pipelines: https://floggy.xyz/docs/cli/recipes.md

**Full view** - the entire docs set in one file: https://floggy.xyz/docs/llms-full.txt (index at https://floggy.xyz/docs/llms.txt)

## Set up the CLI

1. Create an API key in the dashboard under **Settings > Developer**. For publishing, grant `posts:read`, `posts:write`, `uploads:write`.
2. Authenticate:
   ```bash
   floggy login                 # paste the key when prompted
   # or, for CI / non-interactive use:
   export FLOGGY_API_KEY=flg_xxxxxxxxxxxxxxxxxx
   ```
3. Verify: `floggy whoami`

## Publish a post

```bash
floggy posts create --title "My post" --file post.md --status published
echo "# Hi" | floggy posts create --title "Quick note" --stdin --status draft

# Upload an image and embed it
URL=$(floggy upload cover.png)
echo "![cover]($URL)"

floggy posts list --status draft
floggy posts edit <id> --tags "rust,systems"
floggy posts publish <id>
```

Backdating is CLI-only: pass `--published-at 2024-03-01T10:00:00Z`.

## Read content into a site

```bash
bun add @floggy/cms
```

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

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

const { posts } = await floggy.posts.list({ page: 1, perPage: 10 });
const post = await floggy.posts.get("hello-world", { format: "html" });
const metadata = floggy.seo.meta(post); // Next.js-compatible Metadata
```

Public reads need no key. Pass a read-only key only to read drafts or private content.

## Guidance

- Use the CLI for writing and publishing; use `@floggy/cms` for rendering content in a site.
- Never embed a full-access key in a frontend. Use a read-only key there.
- When unsure about a command, flag, or method, fetch the relevant `.md` page or `llms-full.txt` above instead of guessing.