Epismo Basics

Shared reference for all Epismo skills. Covers connection, surface conventions, scope, share URL resolution, and error handling.

Skills that build on this:

Project Tracking — tasks, goals, notes, planning
Workflow Pack — workflow pack discovery and release
Context Pack — context packs, session handoff

Connection

CLI and MCP are two interfaces to the same Epismo service — same account, same data, same tools. There is one Epismo account; the difference is only how you connect.

When both are available, use CLI. If only MCP is available, use MCP. Never use both in the same session.

Auth

CLI (preferred):

bash

epismo login --email you@example.com   # OTP flow (default, no browser)
epismo login --browser                  # browser-based flow
epismo whoami                           # verify

MCP: add

https://mcp.epismo.ai

as an MCP server in your client. Authentication is handled automatically via OAuth.

Surface Conventions

Surface	Pattern	Example
`cli`	`epismo <resource> <action> [--flags]`	`epismo pack search --type context`
`mcp`	`epismo_<resource>_<action>` + JSON	`epismo_pack_search`

MCP tool name = CLI command with spaces and hyphens replaced by underscores. Conceptual payloads are the same across surfaces; CLI flags are mapped into the JSON shape used by API/MCP.

Pack Aliases

Packs can be fetched by a short alias instead of a full ID. Pass

--alias <name>

(or

alias

parameter in MCP) wherever

--id

is accepted on

get pack

. To create and manage aliases, see Pack Alias.

CLI Input Conventions

```
--input '<json>'
```
— inline JSON
```
--input @path/to/file.json
```
— from file
```
--input -
```
— from stdin
Explicit flags override fields in
```
--input
```
.

Workspace Selection

bash

epismo workspace list
epismo workspace use --workspace-id <workspace-id>   # save default
epismo workspace current                              # show saved default (no network)

Workspace selection is CLI-only. All CLI commands resolve workspace automatically from

EPISMO_TOKEN

, saved default, then personal space. In MCP, workspace scope is implicit in the OAuth token.

Scope Model

```
workspace
```
— top-level access boundary. All operations run within the active workspace.
```
targets.projectIds[]
```
— narrows private search or write access to specific projects within the active workspace.
```
targets.userIds[]
```
/
```
targets.emails[]
```
— grant private write access to specific people on mutation calls.
```
targets.self
```
— for search, include private items that target the current user directly; defaults to
```
true
```
.
CLI search/write flags such as
```
--project-ids
```
,
```
--user-ids
```
,
```
--emails
```
, and
```
--self
```
are convenience flags that build the
```
targets
```
object.
For search, omitting
```
targets.projectIds
```
uses the default private scope for the current context;
```
targets.projectIds: []
```
explicitly disables project targets.

When the user refers to "my project", resolve both layers before writing:

Active workspace
Target project(s) via
```
targets.projectIds[]
```

Resolving Share URLs

Share URLs resolve to a resource without credentials by following the HTTP redirect.

Public packs typically use
```
https://epismo.ai/share/{token}
```
.

Internal/private workspace packs may use

https://{workspace}.epismo.ai/share/{token}

Do not assume the host is always the root domain; preserve the original host from the share URL.

bash

# curl
curl -s -o /dev/null -w "%{redirect_url}" "https://epismo.ai/share/${TOKEN}"
# → https://epismo.ai/hub/workflows/{id}
# → https://epismo.ai/hub/contexts/{id}

# internal/private packs may redirect from a workspace subdomain instead
curl -s -o /dev/null -w "%{redirect_url}" "https://${WORKSPACE}.epismo.ai/share/${TOKEN}"
# → https://${WORKSPACE}.epismo.ai/hub/workflows/{id}
# → https://${WORKSPACE}.epismo.ai/hub/contexts/{id}

typescript

// fetch (Node.js)
const shareUrl = new URL(process.argv[2]);
const res = await fetch(shareUrl, {
  redirect: "manual",
});
const location = res.headers.get("location") ?? "";

const workflowMatch = location.match(/\/hub\/workflows\/([^/?#]+)/);
const contextMatch = location.match(/\/hub\/contexts\/([^/?#]+)/);
// use whichever matches; id = decodeURIComponent(match[1])

Redirect path	Resource type
`/hub/workflows/{id}`	`workflow` pack
`/hub/contexts/{id}`	`context` pack

Use the resolved

id

with

get pack

on any surface. If the original share URL is on a workspace subdomain, keep using that host when handing the link back to the user.

Selective Fetch Pattern

search

always returns outline format (

id

title

, and brief metadata) — never full content blocks. Always scan titles first, then fetch only what you need — this keeps session context lean.

Scan —
```
search pack
```
or
```
search track
```
to get a title list.
Select — identify relevant items from the titles. Skip clearly unrelated ones.
Fetch —
```
get pack --full
```
or
```
get track
```
for each selected item to load full content.

get pack

has two modes:

Mode	Flag	Returns
Outline (default)	(none)	`id` , `title` , `view` , `contentIndex` — no content blocks
Full	`--full`	complete content including all blocks / steps

To load a single block or step instead of the full pack:

bash

# context pack — fetch one block
epismo pack get --id <id> --block-id <block-id>

# workflow pack — fetch specific steps
epismo pack get --id <id> --step-id <step-id-1>,<step-id-2>

Pack Reuse Scan Order

Before creating any new pack, scan in this order to avoid duplicating something that already exists:

```
visibility=["private"]
```
+
```
query=<topic>
```
— your own packs first
```
like="liked"
```
+
```
query=<topic>
```
— packs you bookmarked
```
visibility=["public"]
```
+
```
query=<topic>
```
— community packs

If a close match is found, prefer

get pack

over creating new.

Pagination

All

search

calls return page size 20. For large result sets, iterate

page=1, 2, 3...

and merge results.

bash

epismo pack search --type context --filter '{"visibility":["public"]}' --page 2
epismo track search --type task --filter '{"status":["todo"]}' --page 2

Stop iterating when a page returns fewer than 20 results.

Error Handling

Error	Action
`Payment Required: Insufficient credits`	Stop. Check balance and purchase credits — see Credit Purchase.
`Permission denied`	Re-check accessible projects and resource ownership.
`Unauthorized` / `403`	Re-authenticate: run `epismo login` (CLI) or reconnect via MCP OAuth. Verify active workspace and subscription.
`Not Found` / `404`	Confirm the resource ID. It may have been deleted or the share token may have expired.
Rate limit / `429`	Wait and retry with backoff. Inform user if persistent.
Timeout	Retry once. If persistent, reduce payload size or split the operation.

Source of Truth

Repository:

https://github.com/epismoai/skills

epismo-basics

NPX Install

Tags

SKILL.md Content

Epismo Basics

Connection

Auth

Surface Conventions

Pack Aliases

CLI Input Conventions

Workspace Selection

Scope Model

Resolving Share URLs

Selective Fetch Pattern

Pack Reuse Scan Order

Pagination

Error Handling

Source of Truth