workflowy

README

Workflowy CLI

Quick Start

1. Get an API key or enable backup to Dropbox

2. Install

brew install mholzen/workflowy/workflowy-cli

1. Run the descendant count report and paste to Workflowy

workflowy report count | pbcopy

Use clip on Windows.

It will produce a report such as:

# Descendant Count Report

Root: Root
Threshold: 1.00%
Total descendants: 43

- [Root](https://workflowy.com/#/...) (100.0%, 43 descendants)
  - [Projects](https://workflowy.com/#/...) (72.1%, 31 descendants)
    - [Project C](https://workflowy.com/#/...) (34.9%, 15 descendants)
      - [issues](https://workflowy.com/#/...) (23.3%, 10 descendants)
    - [Project B](https://workflowy.com/#/...) (20.9%, 9 descendants)
      - [issues](https://workflowy.com/#/...) (9.3%, 4 descendants)
    - [Project A](https://workflowy.com/#/...) (14.0%, 6 descendants)
  - [Inbox](https://workflowy.com/#/...) (14.0%, 6 descendants)
  - [People](https://workflowy.com/#/...) (11.6%, 5 descendants)

to understand where the majority of your nodes are located.

Table of Contents

• Features
• Installation
  • Via Homebrew
  • From Source
• Setup
  • Get Your API Key
• Usage
  • Basic Commands
  • Usage Reports
  • Global Options
  • Command-Specific Options
  • Access Methods and Configuration
    • Data Access Methods
    • Configuration Flags
    • Performance Comparison
    • Rate Limiting

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, and Uncomplete to operate on nodes.
• Search: Search through all nodes with text or regex patterns, with case-sensitive/insensitive options and highlighted results.
• 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

brew install mholzen/workflowy/workflowy-cli

From Source

git clone https://github.com/mholzen/workflowy.git
cd workflowy
go build ./cmd/workflowy

Setup

Get Your API Key

1. Visit https://workflowy.com/api-key/
2. Save your API key to ~/.workflowy/api.key

mkdir -p ~/.workflowy
echo "your-api-key-here" > ~/.workflowy/api.key
chmod 600 ~/.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.

# Get root items with default depth (2 levels)
workflowy get

# Get specific item with default depth
workflowy get <item-id>

# Get with custom depth (1-3 uses GET API, 4+ uses Export API)
workflowy get <item-id> --depth 5

# Get all descendants (uses Export API)
workflowy get <item-id> --all

# Force specific access method
workflowy get <item-id> --method=backup
workflowy get <item-id> --method=export
workflowy get <item-id> --method=get

# Use specific backup file
workflowy get --method=backup --backup-file=/path/to/file.backup

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.

# List direct children of root (depth 1)
workflowy list

# List direct children of specific item
workflowy list <item-id>

# List with custom depth
workflowy list <item-id> --depth 3

# List all descendants a list of JSON nodes
workflowy list --all --format=json

# Use backup file for fastest access
workflowy list --method=backup

Update A Node

# Update node content
workflowy update <item-id> "new content"

# Update note only
workflowy update <item-id> --note "my note"

# Update multiple fields
workflowy update <item-id> --name "new title" --note "new note"

Complete And Uncomplete Nodes

# Mark a node as complete
workflowy complete <item-id>

# Mark a node as uncomplete
workflowy uncomplete <item-id>

# JSON output
workflowy complete <item-id> --format json

Search For Items

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

# Basic search (case-sensitive)
workflowy search "project"

# Case-insensitive search
workflowy search -i "PROJECT"

# Regex search
workflowy search -E "test.*ing"

# Regex with case-insensitive
workflowy search -iE "bug.*fix"

# Search within specific subtree
workflowy search "todo" --item-id abc-123-def

# Output as JSON with match positions
workflowy search "meeting" --format json

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.

Usage Reports

Descendant Count Report

Rank nodes by the number of total descendant nodes:

# Generate descendant count report
workflowy report count

# With custom threshold (show nodes with >5% of total descendants)
workflowy report count --threshold 0.05

Rank by Children Count

Find nodes with the most immediate children:

# Top 20 nodes by children count (default)
workflowy report children

# Top 10 nodes
workflowy report children --top-n 10

Find Oldest Nodes

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

# By creation date
workflowy report created --top-n 20

# By modification date
workflowy report modified --top-n 20

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:

workflowy report count --upload --parent-id xxx-yyy-zzz --position top

Global Options

• --format <list|json|markdown>: Output format: list, json, or markdown (default: "list")
• --log <level>: Log level: debug, info, warn, error (default: info)

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:

workflowy get <item-id> --depth 2        # Smart default uses GET
workflowy get <item-id> --method=get     # Force GET API

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:

workflowy get --all                      # Smart default uses Export
workflowy get --method=export            # Force Export API
workflowy get --method=export --force-refresh  # Bypass cache

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:

# Use latest backup file
workflowy get --method=backup

# Use specific backup file
workflowy get --method=backup --backup-file=/path/to/backup.json

Configuration Flags

--api-key-file

Specifies the location of your API key file.

Default: ~/.workflowy/api.key

Setup:

mkdir -p ~/.workflowy
echo "your-api-key-here" > ~/.workflowy/api.key
chmod 600 ~/.workflowy/api.key

Usage:

workflowy get --api-key-file=/path/to/custom-key.file

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

workflowy get --method=backup --backup-file=/custom/path/backup.json

--force-refresh

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

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

Usage:

workflowy get --all --force-refresh

When to use:

• After making changes via web/mobile app
• When you suspect stale data
• For critical operations requiring latest data

Performance Comparison

Method	Speed	Freshness	Offline	Rate Limits	Best For
GET API	Medium	Real-time	No	Yes	Specific items, shallow depth
Export API	Fast*	Real-time	No	Yes	Full tree, deep fetches
Backup File	Fastest	Stale	Yes	No	Bulk operations, offline work

* 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

Examples

Generate and upload a comprehensive report

# Find nodes with many descendants and upload the report
workflowy report count --threshold 0.01 --upload

Find stale content

# Find your 50 oldest unmodified nodes
workflowy report modified --top-n 50

Search for specific content

# Find all TODO items (case-insensitive)
workflowy search -i "todo"

# Find items with dates matching a pattern
workflowy search -E "\d{4}-\d{2}-\d{2}"

# Search for bugs in a specific project subtree
workflowy search -i "bug" --item-id project-xyz-123

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

go build ./cmd/workflowy

Run Tests

go test ./...

Project Structure

.
├── cmd/workflowy/       # Main CLI application
├── pkg/
│   ├── workflowy/       # Core Workflowy API client
│   ├── reports/         # Report generation and upload
│   └── formatter/       # Output formatting
└── README.md

License

MIT

Contributing

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