Workflowy CLI: Group Search Results by Parent, Path, Date

February 2, 2026

Video Walkthrough

The Problem

Workflowy’s native search results are unreadable when matches are too deeply nested — everything squishes to the right until you’re scrolling horizontally just to see what matched.

I often want to bring together all the nodes on a topic, ones I’ve created in a hurry and not taken the time to properly place. In those cases, I care mostly about the parent node of a match, so I can navigate there quickly and consolidate duplicates under a single home.

So I added --group-by to the Workflowy CLI, with options for parent, path, and a few others while I was at it.

You can pipe results to your clipboard (pbcopy on macOS, clip on Windows, wl-copy on Linux) and paste them directly into Workflowy. They contain links to your nodes, so navigation is easy.

Group by Parent

Parent node only, linking to its location:

workflowy search <search-term> --group-by=parent

produces:

- [parent node](https://workflowy/...)
    - start of node [match](https://workflowy/...) end of node
- ...

So:

workflowy search refactor --group-by=parent | pbcopy

pasted to Workflowy produces:

Group by Path

Full ancestor chain on one line, each segment trimmed and linked:

workflowy search refactor --group-by=path

produces essentially flattened search results:

This is my favorite mode — it gives you the full context at a glance without the horizontal scroll nightmare.

Group by Created and Modified Dates

While I was at it, I added grouping by created and modified dates, which supports customizing the date format, allowing grouping by year, month, weekday, etc:

workflowy search refactor --group-by=modified
workflowy search refactor --group-by=created.year

produce:

Group by Tree

I also added grouping by tree, which is similar to the native search results, with each segment of the path being its own node:

workflowy search "todo" --group-by=tree

This reconstructs the original hierarchy, keeping only branches that contain matches.

Sort Ascending/Descending

You can sort items according to a key different from what you group by, or change the sorting order (by adding - in front of the key):

workflowy search "todo" --order-by=-modified

Available sort fields: match, parent, path, modified, created.

Regex Search

Regular expressions are available — something I don’t believe is possible in Workflowy’s native search:

workflowy search -iE "bug.*fix|fixme"

Combined with -i for case-insensitive matching, this makes it easy to find variations of a term across your entire outline.

Completed Nodes Excluded by Default

Completed nodes and their descendants are excluded from results by default. This keeps results focused on active content. To include them:

workflowy search todo --include-completed

Options Available to MCP Tools

These search options are also exposed in the MCP search tool, so agents can benefit from efficient, structured search:

MCP Parameter	Description
`group_by`	`parent`, `path`, `tree`, `modified.<unit>`, `created.<unit>`
`order_by`	`match`, `parent`, `path`, `modified`, `created` (prefix `+`/`-`)
`path_max_length`	Max chars per path segment (default 20)
`include_completed`	Include completed nodes (default false)

See MCP documentation for details.

A Note on Rate Limiting

The search capability uses the Export All API call, which is rate limited to 1 request per minute. The CLI and MCP server cache results and reuse them for 1 minute, automatically refreshing afterwards. You can force a refresh with --force-refresh, just be prepared for a 429 if you do it too often.

Also, mirror nodes are not provided by the API — so unfortunately, we cannot search through them. If you care about this, consider +1 this feature request.

Installation

Homebrew (macOS & Linux)

brew install mholzen/workflowy/workflowy-cli

Scoop (Windows)

scoop bucket add workflowy https://github.com/mholzen/scoop-workflowy
scoop install workflowy

Go Install

go install github.com/mholzen/workflowy/cmd/workflowy@latest

Docker

docker run --rm -e WORKFLOWY_API_KEY=your-key ghcr.io/mholzen/workflowy:latest search -iE "todo"

Download Binary

Pre-built binaries for all platforms are available from GitHub Releases.

See the README for full setup instructions, including API key configuration and MCP server setup.