floww

Category: Tools & Productivity | Uploader: usefloww | Downloads: 0 | Version: v1.0（Latest）
Write, test, and deploy workflow automations using the Floww SDK. Use when the user wants to create automations, build workflows, set up triggers (cron, webhook, GitHub, Slack, Discord, etc.), deploy code with Floww, edit existing workflows, or mentions the Floww SDK.
Changelog: Source: GitHub https://github.com/usefloww/floww
Directory Structure

Current level: skills/floww/
📄 examples.md 7.5 KB
📄 SKILL.md 11.9 KB
SKILL.md

---
name: floww
description: Write, test, and deploy workflow automations using the Floww SDK. Use when the user wants to create automations, build workflows, set up triggers (cron, webhook, GitHub, Slack, Discord, etc.), deploy code with Floww, edit existing workflows, or mentions the Floww SDK.
allowed-tools: Bash(floww *), Bash(npx floww *), Bash(npm *), Bash(pnpm *), WebFetch(https://raw.githubusercontent.com/usefloww/floww/main/packages/sdk/providers/*)
---

# Floww SDK

Floww is a code-first workflow automation platform. You write automations in TypeScript using provider classes, then deploy them with the CLI.

## Quick Start

### New project

```bash
npx floww init
```

This scaffolds: `floww.yaml`, `main.ts`, `package.json` (and optionally `Dockerfile` for custom builds).

### Edit an existing workflow

To modify a workflow that's already deployed, use the pull-edit-deploy loop:

```bash
# 1. Pull the deployed source code into an empty directory
mkdir my-workflow && cd my-workflow
npx floww pull <workflow-id-or-name>

# 2. Read and edit the files (the entrypoint and other source files are now local)
# 3. Redeploy
npx floww deploy
```

`floww pull` downloads all source files from the active deployment and creates a `floww.yaml` with the correct `workflowId`, `entrypoint`, and provider mappings. After editing, `floww deploy` pushes the changes back.

**Directory rules for `floww pull`:**
- **Empty directory + workflow arg**: Pulls files and creates `floww.yaml` (clone use case)
- **Directory with `floww.yaml` + no arg**: Pulls from the configured workflow (update use case)
- **Directory with `floww.yaml` + workflow arg**: Error (use `floww pull` without arguments)
- **Non-empty directory without `floww.yaml`**: Error (use an empty directory)

**JSON output** (for programmatic/agent use):
```bash
npx floww pull <workflow-id-or-name> --json
```

Returns `{ workflowId, workflowName, deploymentId, entrypoint, files, directory }`.

### Development (local with hot-reload)

```bash
npx floww dev
```

Runs locally, watches files, provides webhook URLs for testing. If providers aren't configured yet, the CLI prompts interactively.

### Deploy to production

```bash
npx floww deploy
```

If no Dockerfile is present, uses a pre-built default runtime (no Docker needed). If a Dockerfile exists, builds a custom image.

## Core Pattern

Every automation follows this pattern:

1. Import and instantiate providers
2. Register triggers with handlers
3. Call actions inside handlers

```typescript
import { Builtin, GitHub, Slack } from "floww";

const builtin = new Builtin();
const github = new GitHub();
const slack = new Slack();

github.triggers.onPush({
  owner: "my-org",
  repository: "my-repo",
  handler: async (ctx, event) => {
    await slack.actions.sendMessage({
      channel: "#deployments",
      text: `New push to ${event.body.repository.name}`,
    });
  },
});
```

Key rules:
- Triggers register themselves when instantiated -- no default export needed
- Handler signature is always `(ctx, event) => { ... }`
- For webhook/provider triggers, event data is in `event.body`
- For cron triggers, use `event.scheduledTime`
- Actions are async: always `await provider.actions.actionName({ ... })`

## Project Structure

### `floww.yaml`

```yaml
name: my-workflow
version: 1.0.0
entrypoint: main.ts
workflowId: <auto-generated-uuid>
# Optional - only needed for custom Docker builds:
# build:
#   type: docker
#   context: .
#   dockerfile: ./Dockerfile
```

- `entrypoint`: The TypeScript file containing your triggers (default: `main.ts`)
- `workflowId`: Auto-assigned during `floww init` or `floww pull`, links to the workflow in the dashboard
- `build`: Optional. Only needed if you have a custom Dockerfile. Omit to use the default runtime.
- `providers`: Auto-populated provider mappings (maps code aliases to provider IDs)

### `main.ts`

Your automation code. All trigger registrations happen at the top level (not inside functions).

### `package.json`

Must include `"floww"` as a dependency. The `"type": "module"` field is required.

```json
{
  "type": "module",
  "dependencies": {
    "floww": "*"
  }
}
```

## Available Providers

The following providers are available in the Floww SDK (all imported from `"floww"`):

**Event Sources & Triggers:**
- `Builtin` - Cron schedules, webhooks, manual triggers
- `GitHub` - Repository events (push, pull requests, issues, releases, etc.)
- `Slack` - Message and reaction events
- `Discord` - Message, reaction, and member events
- `Gitlab` - Merge request events
- `Jira` - Issue and comment events
- `GoogleCalendar` - Calendar events

**Actions & Integrations:**
- `GitHub` - Issue, PR, file, branch, release, workflow operations
- `Slack` - Messages, channels, users, reactions, files
- `Discord` - Messages, channels, roles, members
- `Jira` - Issue management, comments, transitions
- `Todoist` - Task operations (create, update, complete, move)
- `KVStore` - Persistent key-value storage
- `Secret` - Typed secret access via Zod schema

**AI Models:**
- `AI` - Unified AI provider. Access models via `ai.models.*` (gpt4o, claude35Sonnet, gemini15Pro, etc.). The specific AI service (OpenAI, Anthropic, Google) is configured in the dashboard.

AI utilities (`generateText`, `streamText`, `generateObject`, `streamObject`) are imported from `"floww/ai"`.

### Multiple credentials

Pass a credential name to use a specific configured credential:

```typescript
const github = new GitHub("my-work-account");
const slack = new Slack("team-workspace");
```

## Writing Automations

### Step 1: Identify what to automate

Determine which providers you need based on the trigger source and the actions to perform.

### Step 2: Write the code

Create `main.ts` with provider imports, instantiation, and trigger registration. Every trigger needs a `handler` function.

### Step 3: Test locally

Run `npx floww dev`. The CLI will:
- Watch your entrypoint for changes and hot-reload
- Provide webhook URLs for testing webhook triggers
- Prompt for any missing provider configurations
- Support debugging with `--debug` flag (attaches Node.js inspector on port 9229)

### Step 4: Deploy

Run `npx floww deploy`. The CLI will:
- Execute your code to discover triggers and providers
- Validate all providers are configured
- If no Dockerfile: use the default runtime (no Docker build needed)
- If Dockerfile present: build and push a custom Docker image
- Create the runtime and register triggers

## Editing Existing Workflows

To modify a workflow that's already deployed, follow the pull-edit-deploy loop:

### Step 1: Pull the deployed code

```bash
# Into an empty directory:
mkdir my-workflow && cd my-workflow
npx floww pull <workflow-id-or-name>

# Or with --json for machine-readable output:
npx floww pull <workflow-id-or-name> --json
```

This downloads all source files from the active deployment and creates `floww.yaml` with the correct configuration.

### Step 2: Read and understand the code

Read the entrypoint file (usually `main.ts`) and any other source files to understand the current workflow logic.

### Step 3: Edit the code

Make your changes to the source files. The same rules apply as writing new automations — triggers at top level, handlers with `(ctx, event)` signature, etc.

### Step 4: Redeploy

```bash
npx floww deploy
```

The `floww.yaml` already has the correct `workflowId`, so the deploy targets the same workflow. The updated code replaces the previous deployment.

### Pulling into an existing project

If you already have a `floww.yaml` (e.g., from a previous pull), just run:

```bash
npx floww pull
```

This pulls the latest deployed code for the workflow configured in `floww.yaml`, overwriting local files with the deployed versions.

## AI Integration

Use AI models from OpenAI, Anthropic, or Google via the Vercel AI SDK pattern:

```typescript
import { AI } from "floww";
import { generateText, stepCountIs } from "floww/ai";
import { z } from "zod";

const ai = new AI();

const result = await generateText({
  model: ai.models.gpt4o,
  system: "You are a helpful assistant.",
  prompt: "Summarize this data...",
  tools: {
    myTool: {
      description: "Tool description",
      inputSchema: z.object({ query: z.string() }),
      execute: async ({ query }) => { /* ... */ },
    },
  },
  stopWhen: stepCountIs(5),
});
```

Available models (depends on configured AI provider):
- OpenAI: `gpt4o`, `gpt4oMini`, `gpt4Turbo`, `o1`, `o1Mini`
- Anthropic: `claude35Sonnet`, `claude35SonnetLatest`, `claude3Opus`, `claude35Haiku`
- Google: `gemini2Flash`, `gemini15Pro`, `gemini15Flash`

## Key-Value Store

Persist data across workflow executions:

```typescript
import { KVStore } from "floww";

const kv = new KVStore();

// Direct access
await kv.set("my-table", "key", { some: "data" });
const val = await kv.get("my-table", "key");
await kv.delete("my-table", "key");

// Table handle
const table = kv.getTable<MyType>("my-table");
await table.set("key", value);
const item = await table.get("key");
```

## Typed Secrets

Access secrets with Zod schema validation:

```typescript
import { Secret } from "floww";
import { z } from "zod";

const mySecret = new Secret("my-api-key", z.object({
  apiKey: z.string(),
  baseUrl: z.string().optional(),
}));

// In a handler:
const { apiKey } = mySecret.value();
```

## CLI Reference

| Command | Description |
|---------|-------------|
| `floww init` | Scaffold a new project or link an existing directory |
| `floww pull [workflow]` | Pull deployed source code for an existing workflow |
| `floww dev` | Run locally with hot-reload |
| `floww deploy` | Deploy to production (uses default runtime or custom Docker) |
| `floww login` | Authenticate with Floww |
| `floww logout` | Log out |
| `floww whoami` | Show current user |
| `floww list workflows` | List workflows |
| `floww list namespaces` | List namespaces |
| `floww list deployments` | List deployments |
| `floww list providers` | List configured providers |
| `floww manage providers` | Interactively manage provider configs |

`floww pull` and all `floww list` commands support `--json` for machine-readable output:

```bash
floww pull <workflow> --json
floww list providers --json
floww list workflows --json
floww list namespaces --json
floww list deployments --json
floww list deployments --workflow <id> --json
```

This outputs raw API data as JSON — full IDs (not truncated), ISO dates (not formatted), all fields (not just table columns).

## Dynamic Provider Documentation

When users ask for detailed information about specific providers (triggers, actions, method signatures, types), use the WebFetch tool to fetch the latest provider implementation from GitHub:

**URL Pattern:**
```
https://raw.githubusercontent.com/usefloww/floww/main/packages/sdk/providers/<provider-name>/index.ts
```

**Available Providers:**
- `builtin` - Cron, webhook, manual triggers
- `github` - GitHub integration
- `slack` - Slack integration
- `discord` - Discord integration
- `gitlab` - GitLab integration
- `jira` - Jira integration
- `todoist` - Todoist integration
- `kvstore` - Key-value storage
- `secret` - Secret management
- `ai` - AI models (OpenAI, Anthropic, Google)
- `google_calendar` - Google Calendar integration

**What to Extract from TypeScript Files:**

1. **Triggers** - Found in the `triggers = { ... }` object:
   - Method names (e.g., `onPush`, `onMessage`)
   - Parameter types and required fields
   - Handler signature: `(ctx, event) => { ... }`
   - Event body structure

2. **Actions** - Found in the `<Provider>Actions` class:
   - All public methods (e.g., `sendMessage`, `createIssue`)
   - Method parameters and types
   - Return types
   - JSDoc comments if present

3. **Types** - Found in exports:
   - Exported interfaces and types
   - Event payloads
   - Configuration options

**Example Usage:**
When user asks: "How do I use GitHub triggers?" → Fetch from `https://raw.githubusercontent.com/usefloww/floww/main/packages/sdk/providers/github/index.ts` and extract the triggers object.

## Additional Resources

- For complete working examples: see [examples.md](examples.md)
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
floww

Directory Structure

SKILL.md

Report

Notice
