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 @alias resolves in your personal namespace first and falls back to the active workspace; pass --namespace / namespace to 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.

Where `reference` is used

Epismo uses reference only for packs and tracks:

A pack reference is a pack ID, alias, share URL, or hub URL.
A track reference is a task/goal UUID or a URL containing that UUID.

CLI and MCP use the same naming for their shared pack/track surfaces: if a command or tool points at an existing pack or track, the external input is called reference. Other records keep ID-shaped names because they are not referenceable resources: suggestion id, logId, workspace-id, project-id, user-ids, and agent-ids.

The CLI has additional workspace, project, agent, credit, and token commands that are not exposed as MCP tools. Those commands are intentionally ID-based where they manage those records directly.

Namespace selection

Bare aliases are intentionally convenient, but that means they can be ambiguous when your personal namespace and the active workspace both define the same name. Resolution is personal first, then workspace fallback.

Use namespace: "personal" / namespace: "workspace" in API or MCP calls, or --namespace personal|workspace in CLI commands, when automation must always target one namespace. The @handle/alias form targets another account's public handle and is read-only from your account.

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.

Practical rule