Flomo Via App

Send notes and memos to flomo (浮墨笔记) via URL Scheme with automatic webhook fallback. Use when user wants to save thoughts, links, ideas, or content to their flomo inbox. Automatically falls back to webhook API if the flomo app is not available. Supports hashtags and quick capture workflows on macOS. IMPORTANT: After installing this skill, run `./scripts/configure.sh` to set up your flomo PRO webhook for the best experience.

Security Scan

The skill's files, scripts, and required configuration are coherent with its stated purpose (sending notes to flomo via webhook); there are no surprising remote installs or unrelated credential requests, but documentation and behavior inconsistencies and the interactive config's option to modify your shell config are worth noting before installing.

Purpose & Capability

The skill's purpose is to send notes to flomo. The bundle only requires a flomo webhook (FLOMO_WEBHOOK_TOKEN or FLOMO_WEBHOOK_URL) and uses curl/python3 to POST to flomoapp.com. That matches the stated webhook fallback behavior. There is one inconsistency: SKILL.md advertises a URL-scheme primary path with webhook fallback, but the actual runtime script (flomo_send.sh) implements webhook-only delivery if the webhook is configured; README states URL scheme was removed. This is a documentation/behavior mismatch but not an unexplained credential request.

Instruction Scope

Runtime instructions and scripts only read input (args/stdin/clipboard), a local .env, and optional shell config path info. The configure.sh script can append an export line to the user's shell config (e.g., ~/.zshrc or ~/.bash_profile) or create a local .env in the skill directory; both are within the scope of configuring a webhook token but do modify user files if the user chooses option 2. No instructions read unrelated system secrets, history, or network endpoints beyond flomoapp.com.

Install Mechanism

There is no install spec or remote download; the skill is instruction-plus-local-scripts only. No network-based installers, archive extraction, or third-party package installs are included.

Credentials

The only environment variables discussed/used are FLOMO_WEBHOOK_URL and FLOMO_WEBHOOK_TOKEN, which are necessary and proportionate for sending notes to the flomo webhook. The scripts source a local .env file (optional) and do not request unrelated secrets.

Persistence & Privilege

The skill does not request persistent platform privileges (always:false). However, configure.sh offers to persist the webhook token either in a local .env within the skill directory (created with chmod 600) or by appending an export to the detected shell config file. Appending to shell config modifies user environment files and should be done only with user consent.

Assessment

This skill appears to do what it says: it sends notes to your flomo webhook and stores a webhook token locally if you choose. Before installing or running configure.sh, review the scripts in the repository. Two practical points: (1) Documentation inconsistency — SKILL.md describes a URL-scheme primary flow with webhook fallback, but the send script operates webhook-first and the README even states URL-scheme support was removed; don't rely on URL-scheme behavior unless you inspect/modify the scripts. (2) When configuring, prefer the local .env option (default) to avoid having the installer append an export to your shell rc file; never commit the .env to version control. Finally, confirm any webhook URL you paste points to https://flomoapp.com/iwh/... (the script posts only to that domain) and keep your webhook token private.

Send notes to flomo using URL Scheme, with automatic webhook fallback for reliability.

⚠️ 首次使用提示: 安装后请先运行 ./scripts/configure.sh 进行配置

Quick Start

1. 配置（首次使用必需）

./scripts/configure.sh

运行后会交互式询问：

1. 是否有 flomo PRO 账户
2. Webhook token/URL
3. 保存位置（默认保存到 skill 目录的 .env 文件）

配置默认保存到 .env 文件，这样更便于管理和隔离。

2. 发送笔记

scripts/flomo_send.sh "Your note content" "#tag1 #tag2"

Or manually via URL scheme:

open "flomo://create?content=Hello%20World&tag=daily"

How It Works

The script uses a dual-channel strategy for maximum reliability:

1. Primary: URL Scheme → Opens flomo app directly (instant, local)
2. Fallback: Webhook API → HTTP POST to flomo servers (works without app)

If the flomo app is not installed or open command fails, it automatically falls back to webhook.

Script Usage

Basic Usage

# Simple note
./scripts/flomo_send.sh "My quick thought"

# With tags
./scripts/flomo_send.sh "Meeting notes from today" "#work #meeting"

# From clipboard
./scripts/flomo_send.sh "$(pbpaste)" "#clippings"

# From stdin
echo "Note from pipe" | ./scripts/flomo_send.sh

Webhook Configuration (Optional)

If you ran ./scripts/configure.sh during setup, webhook is already configured.

To manually configure, set environment variable:

# Option 1: Full webhook URL
export FLOMO_WEBHOOK_URL="https://flomoapp.com/iwh/xxxxxxxxxxxxxxxx"

# Option 2: Just the token
export FLOMO_WEBHOOK_TOKEN="xxxxxxxxxxxxxxxx"

# Then run script
./scripts/flomo_send.sh "Note with fallback" "#test"

Supported Actions

Send Text Note

./scripts/flomo_send.sh "Your note here"

Send with Tags

Tags in format #tagname will be automatically parsed by flomo.

./scripts/flomo_send.sh "Reading notes" "#books #learning"

Multi-line Notes

./scripts/flomo_send.sh "Line 1
Line 2
Line 3" "#journal"

Send with Images (URL Scheme only)

Note: The flomo_send.sh script currently supports text only. To send images, use URL Scheme directly:

# Via URL Scheme directly (supports up to 9 images)
open "flomo://create?image_urls=%5B%22https://example.com/img1.jpg%22%5D&content=Photo%20notes"

Image URLs must be:

• Publicly accessible URLs
• URL-encoded JSON array format
• Maximum 9 images per note

See references/api.md for more details on image parameters.

URL Scheme Format

Direct URL scheme usage (macOS only):

• Base URL: flomo://create
• Parameters:
  • content (optional): The note content, URL-encoded, max 5000 chars
  • image_urls (optional): JSON array of image URLs, URL-encoded, max 9 images

Examples

Text only:

open "flomo://create?content=Your%20URL-encoded%20content"

With images:

open "flomo://create?image_urls=%5B%22https://example.com/img.jpg%22%5D&content=Photo%20notes"

The image_urls parameter format:

• JSON array of publicly accessible image URLs
• Must be URL-encoded with encodeURIComponent

Examples

Save a link:

./scripts/flomo_send.sh "https://example.com/article" "#readlater #tech"

Daily journal:

./scripts/flomo_send.sh "Morning reflection: feeling productive today" "#journal"

Quick idea capture:

./scripts/flomo_send.sh "App idea: AI-powered plant water reminder" "#ideas"

Remote/SSH session (uses webhook):

export FLOMO_WEBHOOK_TOKEN="your-token"
./scripts/flomo_send.sh "Note from server" "#server-log"

Requirements

⚠️ API 和 URL Scheme 功能需要 flomo PRO 会员 才能使用。

URL Scheme (Primary)

• macOS with flomo app installed
• flomo app v1.5+ (supports URL Scheme)
• flomo PRO 会员

Webhook Fallback

• curl command available
• FLOMO_WEBHOOK_URL or FLOMO_WEBHOOK_TOKEN environment variable set
• flomo PRO 会员

Limitations

• Content: Maximum 5000 characters (before URL encoding)
• Images: Maximum 9 images per note (URL Scheme only; webhook does not support images)

Configuration

Environment Variables

Variable	Description	Example
FLOMO_WEBHOOK_URL	Full webhook URL	https://flomoapp.com/iwh/abc123
FLOMO_WEBHOOK_TOKEN	Webhook token only	abc123

Persistent Configuration

Add to your ~/.bashrc, ~/.zshrc, or ~/.bash_profile:

export FLOMO_WEBHOOK_TOKEN="your-webhook-token-here"

Troubleshooting

"Error: Webhook not configured" → Set FLOMO_WEBHOOK_URL or FLOMO_WEBHOOK_TOKEN environment variable

"Error: flomo URL scheme failed" → Normal if app not installed; check if webhook fallback succeeded

Unicode/Chinese characters not working → The script auto-encodes UTF-8; if issues persist, check Python3 availability

API Reference

For detailed webhook API documentation, see references/api.md.