vrk uuid

Try it in your browser

vrk, compiled to WebAssembly

# Makes three time-ordered v7 UUIDs.

Command to run

vrk uuid --v7 --count 3

Enter runs, Shift+Enter adds a line

output

Press RUN. Nothing leaves your browser.

files you can cat:

Edit the command and press RUN. Open the full playground for more recipes, or install vrk to run it on your own files.

vrk uuid generates v4 (random) or v7 (time-ordered) UUIDs with consistent output across platforms.

The problem

uuidgen generates v4 UUIDs, which fragment B-tree indexes because they are random. v7 UUIDs sort by creation time and fix this, but uuidgen does not support v7. It also does not exist on all platforms and has no batch mode.

The solution

vrk uuid generates v4 (random) or v7 (time-ordered) UUIDs with consistent output across macOS and Linux. v7 UUIDs sort by creation time, which keeps B-tree indexes compact. Use --count to generate a batch in one call.

Before and after

Before

uuidgen  # v4 only, macOS only, no batch mode
# Need v7? Install Python + uuid7 package

After

vrk uuid --v7

Example

vrk uuid --v7 --count 5

Exit codes

Code	Meaning
0	Success
1	Runtime error (generation failure)
2	–count less than 1, unknown flag

Flags

Flag	Short	Type	Description
`--v7`		bool	Generate a v7 (time-ordered) UUID instead of v4
`--count`	-n	int	Number of UUIDs to generate
`--json`	-j	bool	Emit JSON with uuid, version, generated_at
`--quiet`	-q	bool	Suppress stderr output

How it works

vrk uuid generates UUIDs: random v4 by default, or time-ordered v7 with --v7.

v4 (random, default)

$ vrk uuid
98d06ca5-e747-4a63-8fc9-045f0e02f8d4

A v4 UUID is random. Use it for correlation IDs, file names, and anywhere you need a unique ID but not an order.

v7 (time-ordered)

$ vrk uuid --v7
019d3fdb-2de7-756e-a340-de561cfa43ab

The first 48 bits of a v7 UUID are a millisecond timestamp. v7 UUIDs sort by time, so a newer ID is always greater than an older one. Use v7 for database primary keys to keep B-tree indexes efficient.

Batch generation

$ vrk uuid --count 3
c00bb1e4-51fd-4cfc-96b2-2c0123268c80
c4fd6dd9-c340-4f42-9929-7f0eae856230
58cbbd73-e561-43de-b20a-ccd5f5f92222

$ vrk uuid --v7 --count 3 --json
{"uuid":"019d3fdb-...","version":7,"generated_at":1774891000}
{"uuid":"019d3fdb-...","version":7,"generated_at":1774891000}
{"uuid":"019d3fdb-...","version":7,"generated_at":1774891000}

Pipeline integration

Generate a run ID for a batch pipeline

RUN_ID=$(vrk uuid --v7)
vrk kv set --ns pipeline run_id "$RUN_ID"
echo "Starting run $RUN_ID"

Use UUIDs as chunk IDs

# Assign unique IDs to each chunk of a document
cat document.md | vrk chunk --size 4000 | \
  while IFS= read -r record; do
    CHUNK_ID=$(vrk uuid --v7)
    echo "$record" | jq --arg id "$CHUNK_ID" '. + {id: $id}'
  done

Generate test data

# Create 100 unique user records
vrk uuid --count 100 | while IFS= read -r id; do
  echo "{\"id\":\"$id\",\"name\":\"user-$RANDOM\"}"
done

When it fails

If the count is below 1, uuid exits 2:

$ vrk uuid --count 0
usage error: uuid: count must be >= 1
$ echo $?
2