How I Built a WordPress CLI Tool to Audit Gutenberg Block Usage

As anyone who builds bespoke WordPress sites with ACF blocks knows, over time your content editors end up with a lot of block types — accordions, tabbed content, call-to-actions, sliders, hero banners, and so on.

That’s all great until someone asks “Can we remove that old accordion block now?”

and you realise… you have no idea how many pages it’s actually used on.

I wanted a quick, reliable way to audit block usage across a site — to answer questions like:

• Which blocks are used most often?
• Which ones can I safely retire?

And how consistently are certain patterns (like CTAs) being used?

So I built a small WP-CLI tool to do exactly that.

The original problem

You can run a database search for acf/accordion (or any other block you’re looking for) in the wp_posts table — it’ll return the pages using that block, but also:

• every revision and autosave,
• random drafts,
• and no sense of how many times the block appears on each page.

Not good enough for a clean report. I wanted something that would:

• Only count published content,
• Tell me how many times each block appears per post,
• Work for all ACF blocks in one go,
• And be exportable to CSV for sharing with clients.

The solution: acf-block-usage WP-CLI command

I built a small plugin that registers a custom WP-CLI command:

wp acf-block-usage report

This loops through all published posts, pages and case studies, parses the Gutenberg content using parse_blocks(), and counts every block with a name beginning acf/.

It even follows nested blocks (inside groups, columns, etc.) and reusable blocks (core/block references), so you get a complete picture.

Under the hood, it uses a simple recursive method:

$blocks = parse_blocks( $post->post_content );
$this->walk_blocks( $blocks, $post, $usage, $filter_block );

Each block name is recorded with a count for that post.

When it finds a reusable block (core/block), it loads the referenced wp_block and walks through those inner blocks too.

Exporting the data

Because it’s built with WP-CLI’s Formatter class, you can export the results to CSV with:

wp acf-block-usage report --format=csv > block-usage.csv

That gives you columns like:

Analysing it in Google Sheets

In the sheet, I added a summary tab to show how many times each block is used site-wide, using this formula:

=QUERY(
  {'Block Audit'!A1:C, ARRAYFORMULA(VALUE('Block Audit'!D1:D))},
  "select Col1, sum(Col4)
   where Col1 is not null
   group by Col1
   order by sum(Col4) desc
   label Col1 'Block', sum(Col4) 'Total uses'",
  1
)

That instantly gives me a ranked list of all ACF blocks, from most used to least.

Super handy for spotting redundant or legacy blocks that can be cleaned up.

Why this is useful

This little audit has already proved handy in several ways:

• Content hygiene: identifying old or unused blocks before redesigns.
• Performance: pruning heavy blocks that only appear once.
• Training: showing editors which components are actually being used.
• Future planning: knowing where to focus when rebuilding a block system.

It’s also an elegant example of how Gutenberg data can be programmatically parsed — no need to guess what’s hiding inside your post_content.

Takeaway

If you’re building sites with ACF + Gutenberg, you’re already treating WordPress like a component-based system. This CLI tool gives you visibility into how those components are being used in the real world. It’s small, clean, and something I’ll probably drop into all my client builds going forward.

If you’d like to try it out, I’ll be sharing a stripped-down version soon — or feel free to DM me and I’ll send it your way.