epismo

Epismo CLI

GitHub made code reusable. Hugging Face made models reusable. Epismo makes human-AI 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 [e-mail]         # 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 unless you pass --workspace-id.

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 <workspace-id>    # set default workspace
epismo workspace clear                                # clear default workspace

epismo track

Manage tasks and goals.

epismo track upsert --type task --title "Fix bug" --content "Details..."
epismo track upsert --input @task.json
epismo track get --id <id>
epismo track search --type task --query "bug" --filter '{"status":["todo"]}'
epismo track delete --id <id>

epismo asset

Manage workflows and other assets.

epismo asset upsert --type workflow --title "My workflow" --input @workflow.json
epismo asset get --id <id>
epismo asset get --id <id> --full
epismo asset get --alias myproject
epismo asset get --alias @handle/myproject
epismo asset get --id <id> --block-id b001
epismo asset get --id <id> --step-id s001
epismo asset search --type workflow --query "onboarding" --filter '{"visibility":["public"]}'
epismo asset like --id <id> --liked
epismo asset like --id <id> --no-liked
epismo asset delete --id <id>    # also removes your aliases for that asset

epismo alias

Manage asset aliases as a top-level resource.

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

epismo credit

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

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

• epismo workspace use --workspace-id <workspace-id> saves the default for all commands.
• --workspace-id <id> overrides the default for a single command.
• If neither is set, the CLI operates in personal context.
• epismo workspace current reads only local config and does not require network access.
• When EPISMO_TOKEN is active, saved default workspace selection is ignored unless --workspace-id is provided.

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.