References
The reference formats you can use to point at packs and tracks.
Whenever you read, update, or link to a pack or track, you identify it with a reference. Packs accept several reference forms because they are meant to be shared and reused; tracks accept a narrower set because they represent live work that must stay unambiguous. Knowing which form to use saves you from copying raw UUIDs around.
Pack references
| Form | Example | Use it when… |
|---|---|---|
| UUID | 8f3c… |
You already have the exact ID, e.g. from a previous API response |
| Alias | @team-onboarding |
You want a stable, readable name; resolves personal-first, then workspace |
| Owner alias | @hiroki/team-onboarding |
You are reading an alias that belongs to another handle |
| Share URL | https://epismo.ai/share/<token> |
Someone shared a private pack with you via a link |
| Hub URL | https://epismo.ai/hub/workflows/<id> |
You are pulling a public pack from the hub |
A few details worth knowing:
- Aliases are the most human-friendly form. They are what you should use in prompts, runbooks, and CI scripts. A bare
@aliasresolves in your personal namespace first and falls back to the active workspace; pass--namespace/namespaceto pin a namespace. See Aliases. - Share URLs are produced when a pack is shared by link. On a workspace they may use the workspace subdomain, e.g.
https://acme.epismo.ai/share/<token>. - Hub URLs point at public packs and exist for both pack types:
…/hub/workflows/<id>and…/hub/contexts/<id>.
Pack read and update surfaces accept any of these forms wherever a reference is documented, so a CLI example that works with a UUID also works with an alias or URL.
Track references
Tracks are referenced only by UUID, or by a URL that contains a task or goal UUID. There are no track aliases. This is deliberate: tracks carry status and ownership, and an ambiguous reference to active work is more dangerous than an inconvenient one. If you need a readable handle for something, that is a sign it should be a pack.