Defining custom units for the units CLI

Sun, 01 Feb 2026 06:37:00 +0000

I recently started using a Glowforge Aura to laser cut stuff. So far I made a copy of the game Hex, designed an organizer for Kingdom Builder’s tiny hexagons that are a pain to sort, and plan to also try my hand at creating custom Jig-Saw Puzzles.

While designing the Kingdom Builder organizer, I needed to measure game pieces using callipers and then cut out pieces of EVA foam with the correct size. Through a little bit of trial and error I determined that a 1151px square SVG exported from Figma (vector editing) was the largest size that didn’t get resized when importing it into the Glowforge software and corresponded to the complete size of the Glowforge Aura’s available cutting bed which is a 1ft / 304.8mm square.

Performing these conversions using a calculator was annoying.

I just discovered the units CLI, and it makes it pretty easy to define custom units. I defined a gf / glowforge unit which represents 1 pixel in Figma’s coordinate space:

# Figma pixels to millimeters conversion for Glowforge Aura
glowforge			304.8|1151 millimeter
gf		glowforge

I couldn’t figure out how to get the units to combine my custom units with its existing definitions, but it was easy to define an alias that combined the system library with my custom definitions:

units() {
  command units -f <(cat /usr/share/misc/units.lib "$DOTFILES/custom-units.lib") "$@"
}

Now I can do units '25 mm' gf to see that I should make my design 94.406168px in Figma.

Performing unit conversions on the CLI

Sun, 01 Feb 2026 06:37:00 +0000

I recently discovered¹ the units CLI tool which installed by default on macOS/Linux and comes with a ton of builtin conversions. For example you can do:

❯ units '12 tablespoons' cups
	* 0.75
	/ 1.3333333

This tells you that 12 tablespoons is 0.75 cups, or that a cup is approximately 1.3333333 times 12 tablespoons. I don’t really have any idea why it also shows the latter, but it’s easy enough to ignore.

It also has an interactive mode that reduces the need for quoting shell arguments, e.g.:

❯ units
753 units, 62 prefixes
You have: 190 degC
You want: degF
	374

It also handles compound units seamlessly:

❯ units '10 m/s' mph
	* 22.369363
	/ 0.044704

One gotcha you have to watch out for is that numbers need to be separated from units by spaces, otherwise you get a conformability error and a gibberish result:

❯ units 10mm cm
conformability error
	10
	0.01 m
❯ units '10 mm' cm
	* 1
	/ 1

One of the most amazing things is the file containing the builtin unit definitions. On macOS 26 it is located at /usr/share/misc/units.lib. It starts out simple defining primitive units and prefixes:

# primitive units

m			!a!
kg			!b!
sec			!c!
[...]

# prefixes

[...]
kilo-			1e3
hecto-			1e2
deka-			1e1
deca-			deka
deci-			1e-1
centi-			1e-2
milli-			1e-3
micro-			1e-6
[...]

But it also contains a lot of (at least to me) extremely obscure units. For example, did you know that it takes 16 US feet make 15 French feet?

frenchfoot		16|15 ft

You also can define your own custom conversions for your own unique use cases.

I frequently find it convenient to use bc as a calculator on the command line in my dropdown terminal instead of using a browser/search engine, so I imagine I’ll use units in the future when remembering or typing the conversion into bc is too inconvenient.

I read the short story 500 Miles and was intrigued / didn’t get the punchline because I’d never heard of units. To my surprise, it just existed. ↩

Unformed Delta - cli

Defining custom units for the units CLI

Performing unit conversions on the CLI