A Workflowy CLI with Usage Reports

November 24, 2025

Motivation

Workflowy is an incredible tool, one I am a big fan of and have been using since 2012. Every little bit of information in my life, whether personal or professional has gone in that tool.

As a result, my data has grown rather large over the years:

Node Count Over Time

Workflowy Node Count Over Time

Loading data...

You can clearly see when I decided to prune large sections of my nodes.

All Nodes Always Loaded

I understand the design choice from the Workflowy team to load all nodes when the application starts, whether it be mobile, web or desktop. This drastically speeds up searching and simplifies offline editing. I love knowing that I will always have all my notes available, whether I’m connected to the Internet or not.

Decluttering Keeps Load and Search Efficient

Like gas in a container—or clothes in a closet—data expands to fill all available space. This is also true of disk storage as we always seem to run up against a drive’s capacity, despite storage having followed Moore’s law over time.

So how does one go about pruning intelligently? When considering elements for deletion, it is always useful to understand the size of the potential gains, relative to the overall size.

Percentage of Total Node Count

It is too easy to start agonizing over whether this node can be deleted or not, until one realizes that it represents only .1% of the total node count.

The CLI available at github.com/mholzen/workflowy provides an easy solution to this problem. After installing it, simply type:

$ workflowy report count

will produce a hierarchical report in Markdown, with links to your nodes, that can be directly pasted into Workflowy:

- [usage report sample](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)

And within Workflowy:

count report

Each node contains the total number of descendant nodes, the ratio of that count to total number of nodes, and is sorted in descending order. Any nodes below a configurable threshold (defaults to 1%) are omitted.

This allows you to navigate through your content, understanding where you store most of it, and intelligently decide what is worth purging. (Of course, remember you have the ability to restore from backup, assuming you have chosen the option to backup daily to Dropbox).

On macOS, a easy approach is to pipe the output directly to the clipboard:

$ workflowy report count | pbcopy

then switch to Workflowy and simply paste with Ctrl+V.

More Features

The CLI generates 3 other reports types, which are simple ranked list of nodes by:

immediate children count (descending)
by creation date (oldest first)
by modification date (oldest first)

It fetches data using the recently released Workflowy API, or against a backup file (--use-backup-file) if you’d rather not provide it access to your live data. It caches the fetched data so as to avoid hitting the API’s rate limit. It can also upload the report directly (--upload) although this might hit the node creation rate limit.

The CLI provides basic search, retrieval, creation, update, complete and uncomplete operations on nodes. It also provides an early stage output formatter (--format=markdown) that attempts to create a Markdown document from hierarchical nodes interpreting nodes as headers even if the layoutMode has not been specified. The intent is to allow document editing without formatting information and yet still generate a formatted document.

$ workflowy -h
NAME:
   workflowy - Interact with Workflowy API

USAGE:
   workflowy [global options] [command [command options]]

DESCRIPTION:
   Retieve, create and update nodes.  Generate usage reports and upload them to Workflowy.

   Specify how to access the data using the --method flag:
     --method=get      Use GET API (default for depth 1-3)
     --method=export   Use Export API (default for depth 4+, --all)
     --method=backup   Use local backup file (fastest, offline)

   Further customize the access method with the following flags:
     --api-key-file    Path to API key file (default: ~/.workflowy/api.key)
     --force-refresh   Bypass export cache (use with --method=export)
     --backup-file     Path to backup file (default: latest in ~/Dropbox/Apps/Workflowy/Data)

   Examples:
     workflowy get --method=backup
     workflowy list --force-refresh
     workflowy report count --upload

COMMANDS:
   get          Get item with optional recursive children (root if omitted)
   list         List descendants of an item as flat list (root if omitted)
   create       Create a new node
   update       Update an existing node
   complete     Mark a node as complete
   uncomplete   Mark a node as uncomplete
   report       Generate reports from Workflowy data
   search       Search for items by name
   version      Show version information
   help, h      Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --format string, -f string  Output format: list, json, or markdown (default: "list")
   --log string                Log level: debug, info, warn, error (default: "info")
   --help, -h                  show help

What Next?

I hope you find this useful.

Feel free to send me feedback at marc@vonholzen.org, or submit issues, comments or a PR at github.com/mholzen/workflowy