Skip to main content
The CLI mints a short alias for every entity it prints (w-6ec, s-b2c, pt-a3f). An alias is accepted anywhere a full UUID is expected, so you can copy one from any command’s output and paste it into the next command. Resolution maps the alias back to the UUID before the request is sent. See global flags for how --workspace and the other id-bearing flags accept aliases.

​
Format

An alias is a type prefix, a hyphen, and the first three hex characters of the entity’s UUID with dashes removed.
Aliases are deterministic: the same UUID always produces the same alias, across commands and terminals. On a collision (two UUIDs sharing the same three-character prefix) the CLI extends the second alias by one hex character at a time until it is unique, so a few aliases run longer than three characters.

​
Prefix table

p- is the person (the reusable profile). pt- is the participant (one instance of a person inside an iteration). They are different entities. See people.

​
Resolution order

Every id-bearing argument runs through one resolver. It accepts two shapes:
1

Full UUID

A well-formed UUID passes through unchanged.
2

Known alias

An alias is looked up in aliases.json and replaced with its UUID.
Anything else is a usage error. An alias whose prefix is recognized but whose entry is not in the store exits 4 (not_found) with the list command that would mint it, for example ish workspace list for a w- alias. A string that is neither a UUID nor a known alias shape exits 4 with guidance to run a list command first. See exit codes.

​
Where aliases are stored

Aliases persist to aliases.json under the config root, so they survive across commands and terminal sessions. The root is ~/.ish by default and is overridable with the ISH_HOME environment variable. A fresh install, a deleted aliases.json, or a new ISH_HOME starts with an empty store. When that happens, run the entity’s list command to repopulate it.

​
Working with aliases

Read an alias straight out of one command and pass it to the next.
To pull a specific alias out of JSON output, target the field with --get.
Aliases are for convenience at the terminal. In scripts that must survive a wiped config or a different ISH_HOME, capture the full UUID with --get id --verbose and pass that instead.
For the full output contract, including how aliases appear in JSON and table modes, see reactions and results.