Epismo CLI

GitHub made code reusable. Hugging Face made AI models reusable. Epismo makes agentic workflows reusable.

Capture how you got your best results — not just the output — and share them as executable workflows that agents and humans can discover, adapt, and run across projects.

CLI Contract

Epismo CLI is designed for agents first.

• Non-interactive runs default to machine-readable JSON.
• Interactive TTY runs also keep success output machine-readable on stdout.
• stderr is used for prompts, browser-login guidance, and error output.
• Exit code 0 indicates success. Any non-zero exit code indicates failure.

In interactive sessions, the CLI may prompt on stderr. In non-interactive environments, commands that need prompts fail fast instead of waiting for input.

Install

npm install -g epismo

Or run without installing:

npx epismo <command>

Authentication

epismo login                                 # prompts for email, then OTP
epismo login --email [email protected]         # request OTP, then prompt for code
epismo logout                                # clear local credentials
EPISMO_TOKEN=<access-token> epismo whoami    # preferred for scripts

If EPISMO_TOKEN is set, the CLI uses it instead of stored credentials.

When EPISMO_TOKEN is active, the saved default workspace is ignored. The workspace is resolved from the token itself — use epismo token create --workspace-id to issue a workspace-scoped token for CI/CD.

Commands

epismo whoami

Show the current user, effective workspace context, and accessible workspaces.

epismo workspace

epismo workspace list                                       # list accessible workspaces
epismo workspace current                                    # show saved default from local config only
epismo workspace use <workspace-id>                         # set default workspace
epismo workspace clear                                      # clear default workspace
epismo workspace create --name "ws001" --plan basic         # create workspace
epismo workspace update <workspace-id> --name "New Name"    # update workspace
epismo workspace checkout <workspace-id>                    # get billing URL

workspace create always returns a url field — a Stripe checkout link to activate the subscription for the chosen plan (basic or pro). Use workspace checkout to retrieve the billing URL for an existing workspace.

Workspace members

epismo workspace member list
epismo workspace member upsert <user-id> --role owner|admin|member
epismo workspace member upsert <uid1>,<uid2> --role member        # bulk
epismo workspace member delete <user-id>
epismo workspace member delete <uid1>,<uid2>                      # bulk

Member seat count is synced to Stripe automatically on add and remove. Bulk operations (comma-separated <user-ids>) make a single Stripe subscription update after the batch completes, not one per user.

epismo project

epismo project list                                                       # list projects in workspace
epismo project create --name "My Project"                                 # create project
epismo project update <project-id> --name "New Name" --description "..."  # update project
epismo project delete <project-id>                                        # delete project

Project members

epismo project member list   --project-ids <id1,id2>
epismo project member add    <user-id> --project-id <pid>
epismo project member add    <uid1>,<uid2> --project-id <pid>             # bulk
epismo project member delete <user-id> --project-id <pid>
epismo project member delete <uid1>,<uid2> --project-id <pid>             # bulk

epismo agent

Manage which AI teammates appear in the assignee roster.

epismo agent list                            # list all agents and selected roster
epismo agent add    --agent-ids <id1,id2>    # add agents to the roster
epismo agent remove --agent-ids <id1,id2>    # remove agents from the roster

epismo track

Manage project tracks for tasks and goals.

epismo track create --type goal --title "Launch Q3" --goal '{"status":"on_track"}'
epismo track create --input @task.json
epismo track update <id> --task '{"status":"done"}'
epismo track get <id>
epismo track search --type task --query "bug" --projects proj1
epismo track search --type task --personal --projects proj1
epismo track delete <id>
epismo track apply --input @batch.json

track apply creates, updates, and deletes multiple tracks in a single request. Use a non-UUID string (e.g. "t001") as id in upserts to create a new track. Cross-references between new entries in task.parentId, task.dependsOn, and task.goalId are resolved by the server. Track search uses additive scope selectors: --personal, --projects <ids>, or both. Omit both to use the default search scope. Track create/update/apply use scope ({ "type": "personal" } or { "type": "projects", "ids": [...] }) and an optional sharedWith ({ "userIds": [...], "emails": [...] }). On create, scope is required. On update, omit scope/sharedWith to preserve the existing acl bits. CLI flags: --personal, --projects <id...>, --share-with <userIdOrEmail...> (values containing @ are treated as emails).

epismo pack

Manage agent packs for workflows and contexts.

A pack reference is any of: bare UUID, alias (@<alias> or @<handle>/<alias>), share URL, or hub URL.

epismo pack create --type workflow --title "My workflow" --input @workflow.json
epismo pack update <reference> --visibility public --category productivity
epismo pack update <reference> --blocks '[{"op":"add","title":"New Block","content":"..."}]'
epismo pack get <id>
epismo pack get <id> --full
epismo pack get @myproject
epismo pack get @handle/myproject
epismo pack get https://epismo.ai/share/<token>
epismo pack get https://epismo.ai/hub/workflows/<id>
epismo pack get <id> --block-id b001
epismo pack get <id> --block-id b001 --block-id b002
epismo pack get <id> --step-id s001,s002
epismo pack search --type context --query "onboarding" --projects proj1
epismo pack search --type context --personal --projects proj1
epismo pack like <reference> --liked
epismo pack like <reference> --no-liked
epismo pack delete <reference>    # also removes your aliases for that pack

Pack search uses additive scope selectors: --personal, --projects <ids>, or both. Omit both to use the default search scope. Pack create/update use scope ({ "type": "personal" } or { "type": "projects", "ids": [...] }) and an optional sharedWith ({ "userIds": [...], "emails": [...] }). On create, scope is required. On update, omit scope/sharedWith to preserve the existing acl bits. CLI flags: --personal, --projects <id...>, --share-with <userIdOrEmail...> (values containing @ are treated as emails).

epismo alias

Manage pack aliases as a top-level resource.

epismo alias upsert @myproject --type context --id <pack-id>
epismo alias get @myproject
epismo alias get @handle/myproject    # another user's alias
epismo alias list
epismo alias list --type workflow
epismo alias delete @myproject

epismo credit

epismo credit balance
epismo credit checkout --allocations '[{"userId":"<user-id>","quantity":500}]'

Skills

Skills are reusable instruction sets that give AI agents step-by-step processes for common project operations (intake, planning, coordination, and more). Any agent with Epismo access — via CLI or MCP — can load and run them.

Browse skills: https://github.com/epismoai/skills

Workspace Selection

All commands resolve workspace automatically — there is no per-command --workspace-id flag.

Interactive / development use:

• epismo workspace use <workspace-id> — save a default workspace for all commands
• epismo workspace clear — revert to personal space
• epismo workspace current — show the saved default (reads local config only, no network)

CI/CD use:

• Issue a workspace-scoped token once, then set it as EPISMO_TOKEN:

epismo workspace list                               # find your workspace id
epismo token create --workspace-id <workspace-id>  # issue a scoped token
export EPISMO_TOKEN=<accessToken>                  # all commands use that workspace

• Or rely on the saved default if the CI environment has local config:

epismo workspace use <workspace-id>   # done once in the environment
epismo token create                   # uses saved default workspace
export EPISMO_TOKEN=<accessToken>

Workspace resolution order:

1. Workspace embedded in EPISMO_TOKEN (when token was issued with epismo token create --workspace-id)
2. Saved default from epismo workspace use (interactive sessions)
3. Personal space (fallback when no workspace is configured)

epismo token

Issue workspace-scoped CLI tokens for use in CI/CD pipelines.

epismo token create --workspace-id <workspace-id>  # workspace-scoped token
epismo token create                                # personal space token (or saved default)

The issued token has the same scopes as a normal CLI login (read, write, offline_access) but carries the workspace ID embedded. Set it as EPISMO_TOKEN so all subsequent commands resolve the workspace automatically without any flags.

Input

• --input <json> — inline JSON object
• --input @path/to/file.json — load from file
• --input - — read from stdin
• Explicit flags override fields from --input
• Enum-like flags are validated in the CLI before the request is sent.

Output

• Successful command output is JSON on stdout.
• Errors and warnings are written to stderr as JSON.
• Prompts and browser-login guidance are also written to stderr.

Error shape (stderr, exit code ≠ 0):

{ "error": { "code": "NOT_FOUND", "message": "...", "retryable": false, "hint": "..." } }

Warning shape (stderr, exit code 0):

{ "warning": { "code": "UPDATE_AVAILABLE", "message": "..." } }

Update Checks

Automatic update checks are enabled by default (once per day, shown only in interactive TTY sessions).

• Set EPISMO_UPDATE_CHECK=0 to disable the background npm version check.