Workflowy CLI and MCP Server

Quick Start

1. Get an API key or enable backup to Dropbox

2. Install

3. Run the descendant count report, send the output to the clipboard and paste directly to Workflowy:

Use pbcopy on macOS, clip on Windows, wl-copy on Linux, or xclip for X11 systems.

It will produce a report such as:

to understand where the majority of your nodes are located.

Related MCP server: WorkFlowy MCP Server

Table of Contents

• Features

• Installation

  • Via Homebrew

  • From Source

• Setup

  • Get Your API Key

• Usage

  • Basic Commands

    • List Targets

    • Search For Items

    • Search and Replace

  • Usage Reports

  • Global Options

  • Command-Specific Options

  • Access Methods and Configuration

    • Data Access Methods

    • Configuration Flags

    • Performance Comparison

    • Rate Limiting

• MCP Server

  • Configuring with Claude Desktop

  • Available Tools

• Examples

A command-line interface for interacting with Workflowy, including fetching, creating, and updating nodes, searching through content, and generating usage reports.

Features

• Node Operations: Get, List, Create, Update, Complete, Uncomplete, and Delete to operate on nodes.

• Targets: List all available shortcuts and system targets (like "inbox") for use in commands.

• Search: Search through all nodes with text or regex patterns, with case-sensitive/insensitive options and highlighted results.

• Search and Replace: Bulk find-and-replace across node names using regex with capture group support, interactive mode, and dry-run preview.

• Usage Reports: Understand where the majority of your nodes are stored, which nodes have many children or which ones are possibly stale:

  • Rank nodes by the count of descendants, with a configurable threshold to the total number of nodes

  • Rank nodes by count of immediate children

  • Rank nodes by oldest created or modified dates

• Format: produces Markdown lists or JSON

• Report Upload: Upload usage reports using the API or paste the markdown output into Workflowy

• Backup File Support: Operates on local backup files for faster operations

• Local Caching: Caches API responses for improved performance

Installation

Via Homebrew

From Source

Setup

Get Your API Key

1. Visit https://workflowy.com/api-key/

2. Configure your API key using one of these methods:

Option A: Environment variable (recommended for CI/scripts)

Option B: Key file (recommended for personal use)

Precedence order:

1. --api-key-file flag (if explicitly provided)

2. WORKFLOWY_API_KEY environment variable

3. Default file (~/.workflowy/api.key)

Usage

Basic Commands

Get Items (Tree Structure)

The get command retrieves items with their hierarchical structure. It automatically chooses the most efficient API method based on depth.

Smart API Selection:

• Depth 1-3: Uses GET API (efficient for shallow fetches)

• Depth 4+ or --all: Uses Export API (efficient for deep/complete fetches)

• Override with --method=get, --method=export, or --method=backup

List Items (Flat List)

The list command retrieves items as a flat list without hierarchy. Uses the same smart API selection as get.

Update A Node

Complete And Uncomplete Nodes

Delete A Node

List Targets

List all available targets (shortcuts and system targets like "inbox") that can be used as IDs in other commands:

What are targets?

• System targets: Built-in locations like inbox

• Shortcuts: User-defined shortcuts you create in Workflowy

Use targets as IDs: You can use target keys (like inbox) instead of UUIDs in commands that accept parent IDs or item IDs.

Example:

Search For Items

Search through your Workflowy items by name with text or regex patterns:

Search Features:

• Text or regex pattern matching

• Case-sensitive by default, use -i for case-insensitive

• Highlights all matches with bold in markdown output

• Returns markdown links to matching items

• Search entire tree or specific subtree with --item-id

• JSON output includes match positions for programmatic use

Output Formats:

• --format list (default): Markdown list with clickable links and highlighted matches

• --format json: JSON array with match positions and metadata

• —-format markdown: Experimental formatter that attempts to turn a tree of nodes without any layoutMode information into a Markdown document, translating parent nodes in header nodes, joining paragraphs, capitalizing and joining paragraphs, and detecting list vs paragraph items using a heuristic.

Search and Replace

Bulk find-and-replace text in node names using regular expressions:

Replace Features:

• Regular expression patterns with capture group support

• Substitution syntax: $1, $2 (or ${1}, ${2} when followed by alphanumerics)

• --dry-run: Preview all changes without modifying any nodes

• --interactive: Prompt for confirmation before each replacement (y/N/q to quit)

• --parent-id: Limit replacements to a specific subtree

• --depth: Control how deep to traverse (-1 for unlimited, default)

• -i: Case-insensitive pattern matching

Output Formats:

• --format list (default): Shows before/after for each match with node IDs

• --format json: JSON array with old_name, new_name, applied status, and URLs

Usage Reports

Descendant Count Report

Rank nodes by the number of total descendant nodes:

Rank by Children Count

Find nodes with the most immediate children:

Find Oldest Nodes

Find nodes that haven't been updated in a long time:

Upload Options

All report commands support these upload flags:

• --upload: Upload report to Workflowy instead of printing

• --parent-id <id>: Parent node ID for uploaded report (default: root)

• --position <top|bottom>: Position in parent node (default: top)

Example:

Global Options

• --format <list|json|markdown>: Output format: list, json, or markdown (default: "list")

• --log <level>: Log level: debug, info, warn, error (default: info)

• --log-file <path>: Write logs to a file instead of stderr (useful for MCP server mode)

Command-Specific Options

Get and List Commands

• --depth <n>: Recursion depth for operations (default: 2)

• --all: Get/list all descendants (equivalent to --depth=-1)

• --include-empty-names: Include items with empty names

Access Methods and Configuration

Data Access Methods (--method)

The CLI supports three ways to access your Workflowy data. By default, it automatically chooses the most efficient method based on depth:

1. GET API (--method=get)

When used:

• Default for depth 1-3

• Explicitly via --method=get

Characteristics:

• Multiple API calls (one per depth level)

• Best for specific items with shallow depth

• No caching

• Requires API key

• Subject to rate limits

Example:

2. Export API (--method=export)

When used:

• Default for depth ≥4 or --all

• Explicitly via --method=export

Characteristics:

• Single API call fetches entire tree

• Best for deep fetches or complete tree access

• Cached locally for performance

• Requires API key

• More efficient for large trees

Cache location: ~/.workflowy/export-cache.json

Example:

3. Backup File (--method=backup)

The CLI can read from a Workflowy backup file, stored to Dropbox and sync'ed to your filesystem locally. Enable "Auto-Backup my Workflowy to Dropbox" in Settings and ensure your Dropbox folder /Apps/Workflowy/Data/ is synced locally to ~/Dropbox/Apps/Workflowy/Data/.

When used:

• Explicitly via --method=backup

• As a fallback, if no API key is found

Characteristics:

• Reads from local Workflowy backup file

• Fastest option

• Works offline

• No API calls required

• No rate limits

• Data may be slightly stale (depends on backup frequency)

Default backup location: ~/Dropbox/Apps/Workflowy/Data/*.workflowy.backup (most recent file)

Example:

Configuration Flags

API Key Configuration

The CLI supports multiple ways to provide your API key:

Environment variable:

Default file location: ~/.workflowy/api.key

Explicit file path:

--backup-file

Specifies a specific backup file to use (only relevant with --method=backup).

Default: Latest file matching ~/Dropbox/Apps/Workflowy/Data/*.workflowy.backup

Usage:

--force-refresh

Bypasses the export cache and forces a fresh API call (only relevant with --method=export).

Cache location: ~/.workflowy/export-cache.json

Usage:

When to use:

• After making changes via web/mobile app

• When you suspect stale data

• For critical operations requiring latest data

Performance Comparison

* After first fetch (cached)

Rate Limiting

The Workflowy API may enforce rate limits. If you encounter rate limit errors:

• Use --method=backup for bulk operations

• Use --method=export instead of multiple GET calls

• Space out API requests

• Check Workflowy's API documentation for current limits

MCP Server

The Workflowy CLI includes an MCP (Model Context Protocol) server that enables AI assistants like Claude to interact with your Workflowy data.

Configuring with Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

For read-only access (safer):

Using environment variable for API key:

After updating the configuration, restart Claude Desktop.

Available Tools

The MCP server exposes Workflowy operations as tools that Claude can use:

Read Tools (default, --expose=read):

• workflowy_get - Get a node and its descendants

• workflowy_list - List descendants as a flat list

• workflowy_search - Search nodes by text or regex

• workflowy_targets - List available shortcuts and system targets

• workflowy_report_count - Generate descendant count report

• workflowy_report_children - Rank nodes by children count

• workflowy_report_created - Rank nodes by creation date

• workflowy_report_modified - Rank nodes by modification date

Write Tools (--expose=write or --expose=all):

• workflowy_create - Create a new node

• workflowy_update - Update an existing node

• workflowy_delete - Delete a node

• workflowy_complete - Mark a node as complete

• workflowy_uncomplete - Mark a node as uncomplete

• workflowy_replace - Search and replace text in node names

Examples:

Examples

Generate and upload a comprehensive report

Find stale content

Search for specific content

Bulk search and replace

API Reference

This tool uses the Workflowy API. For more information:

• API Documentation: https://workflowy.com/api-reference/

• Get API Key: https://workflowy.com/api-key/

Development

Build

Run Tests

Project Structure

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.