= uuid(1)



== NAME

uuid - generate a UUID version 4 or 7, or validate a UUID string.



== SYNOPSYS

*uuid* [-v (4|7)] *uuid* [_STRING_]



== EXAMPLES


=== Print a (version 4) UUID on the terminal

[source, sh]
....
$ uuid
d3891787-c952-af17-d697-0df3b85981e1
....


=== Print a verson 7 UUID on the terminal

[source, sh]
....
$ uuid -v 7
d3891787-c952-af17-d697-0df3b85981e1
....


=== Create a new UUID as part of a path

[source, sh]
....
dir="$PWD"/"$(uuid)"/data
....


=== Validate a given UUID

[source, sh]
....
ID="$(basename -- "$directory")"
if ! uuid "$ID"; then
	echo "Bad UUID in directory: $ID" >&2
	exit 1
fi
....



== DESCRIPTION

The *uuid* utility generates a new UUID when no _STRING_ is given and write it to _stdout_. If a _STRING_ is given, *uuid* validates it and exits, and produces no output.

The *-v* option allows for choosing which type of UUID to be emitted, either version 4 ("the random one") or version 7 ("the sortable one"). When omitted, version 4 is chosen as default.



== OPTIONS

*-v NUMBER*:: Choose the UUID version *NUMBER* to be generated. Supported values are 4 (the default) and 7.



== OPERANDS

_STRING_:: If it is

  *not given*::: generate a brand new random UUIDv4, print it to _stdout_ and exit normally;
  *given*:::   test if it is a valid UUIDv4 and exit normally if so.



== IO


=== STDIN

Not used.


=== STDOUT

The UUIDv4 format is made of byte blocks encoded as hexadecimals, using a <hyphen-minus>('`-`') as the block separator:

[source, sh]
....
XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
....

An example output is:

[source, sh]
....
cb46d0c0-b2aa-4a6c-a119-8deace2544a2
....


=== STDERR

Errors on UUID validation are sent to the standard error. For instance:

[source, sh]
....
$ uuid not-a-uuid-123 1>/dev/null
uuid: str isn't of the correct length
....

When valid, validation emits nothing and exits with 0.


=== INPUT FILES

None.


=== OUTPUT FILES

None.



== EXIT STATUS

0:: Generating or validating a UUID was successfull.
3:: UUID validation failed.



== CONFORMING TO

The versions 4 and 7 of the UUID defined in *RFC 9562*.



== SEE ALSO



== AUTHORS

mailto:eu@euandre.org[EuAndreh] and contributors.



== BUGS

* Report bugs to the mailto:~euandreh/public-inbox@lists.sr.ht[mailing list]. Use the subject "[uuid] BUG or TASK: <description>".
* Browse bugs https://euandre.org/git/uuid/TODOs.html[online].
* https://euandre.org/git/uuid/[Homepage].
* https://lists.sr.ht/~euandreh/public-inbox?search=%5Buuid%5D[Comments and discussions].