EasySociable CLI

Agent-first CLI for EasySociable: local Content Engine, Template, Slideshow, and MCP.

npm i -g @easysociable/cli
# or
curl -fsSL https://easysociable.com/install.sh | bash

Requires Node.js 20+. Content Engine workbench also needs python3.

Quick start

# Default skill + MCP for Codex / Claude Code (slideshow).
# The curl installer already runs this; needed after an npm install.
easysociable install --yes

Default install does not include easysociable-content. Add it when you want the Content Engine pointer skill:

easysociable install --skills content,template,slideshow --yes

Preferred: clone the public core:

git clone https://github.com/murphywuwu/content-engine.git
cd content-engine
python3 workbench/build.py
python3 workbench/serve.py --no-open

See https://github.com/murphywuwu/content-engine (LAYOUT.md, migrate-split-vault.py).

Optional: easysociable engine init --root … --yes clones that repo into Content Engine/ (never overwrites an existing engine).

Then tell the Agent to follow CLAUDE.md. The core includes separate products/ (owned offers) and recommendations/ (third-party review subjects); neither is a substitute for needs/.

Lazy-auth guidance lives in the package at skills/ONBOARDING.md.

Content Engine

Core methodology lives in the public GitHub repo, not inside this CLI tarball. engine serve / build do not overwrite local workbench files unless you pass --sync-workbench (pulls from the public core checkout / CONTENT_ENGINE_CORE).

| Command | Purpose | |---------|---------| | easysociable engine init [--root] [--yes] [--serve] | Clone public core into Content Engine/ (no overwrite) | | easysociable engine update [--engine] [--yes] | Sync core rules from the public template; preview first, apply with --yes. Never touches vault data | | easysociable engine serve [--engine] [--no-open] [--sync-workbench] | Rebuild + start on :8765 | | easysociable engine build [--engine] [--sync-workbench] | Rebuild workbench/index.html | | easysociable engine detect | Find engines under search roots | | easysociable engine validate --root … | Core marker completeness | | easysociable engine validate --run … | Run / pack checks before render |

Optional engine.json field vault_root (default ".") points data at a separate vault; see the public LAYOUT.md.

The Workbench exposes Products and Recommendations as separate read-only indexes. Topics can cite either one without forcing a product connection.

Default --root / --engine parent is /workspace when that directory exists, otherwise the current working directory.

MCP Server Configuration

EasySociable exposes native Model Context Protocol (MCP) tools for Claude Desktop, Claude Code, Cursor, and any MCP-compatible agent host.

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "easysociable": {
      "command": "npx",
      "args": ["-y", "@easysociable/cli", "mcp", "serve", "--transport", "stdio"]
    }
  }
}

Claude Code

easysociable install --yes registers the server at user scope by running claude mcp add -s user easysociable -- easysociable mcp serve --transport stdio (removing any previous easysociable entry first, so re-running is safe). If the claude binary is not on PATH, it merges the same entry into the top-level mcpServers of ~/.claude.json and leaves every other key alone. Claude Code does not read ~/.claude/mcp.json; older installers wrote there, and that file can be deleted. To register by hand:

claude mcp add -s user easysociable -- easysociable mcp serve --transport stdio

The server starts without a stored key; until you run easysociable auth login, every tool returns an AUTH_REQUIRED result telling you to log in. Credentials are re-read on each tool call, so no host restart is needed after login (install warns when you are not logged in).

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "easysociable": {
      "command": "easysociable",
      "args": ["mcp", "serve", "--transport", "stdio"]
    }
  }
}

Authentication

easysociable auth login            # opens the browser; approve and the key is stored automatically
easysociable auth login --api-key <key>   # headless / CI
easysociable auth status
easysociable templates list --json
easysociable mcp serve --transport stdio

The gateway resolves in this order: EASYSOCIABLE_GATEWAY_URL (or legacy EASYSOCIABLE_API_URL) env → the baseUrl stored by auth login → the build default. The npm package is a production build (https://gateway.easysociable.com, site https://easysociable.com) and never uses a local gateway unless you export EASYSOCIABLE_GATEWAY_URL for that shell: it ignores a stored 127.0.0.1 / localhost baseUrl (e.g. http://127.0.0.1:8787 written by CLI ≤ 0.1.36, which recovers without re-login) and refuses auth login --gateway-url http://127.0.0.1:….

Building: production vs development

Environment defaults are baked at build time from build-envs.mjs; a bundle carries exactly one profile.

pnpm --filter @easysociable/cli build       # production (what prepack/npm publish ships)
pnpm --filter @easysociable/cli build:dev   # development: gateway 127.0.0.1:8787, site 127.0.0.1:5175
pnpm --filter @easysociable/cli dev         # development, watch mode
pnpm --filter @easysociable/cli check:dist  # fails unless dist is a production build (runs in prepack)

Other commands

| Command | Purpose | |---------|---------| | easysociable install [--yes] [--skills list] | Install Skills + MCP | | easysociable update [--yes] [--skills list] | Update Skills + MCP | | easysociable templates … | Page Template drafts / catalog (list --platform <p> --all for a full platform catalog) | | easysociable brands … | Workspace Brands | | easysociable slideshows … | Slideshow Runs | | easysociable slideshows recommend --file contracts.json --seed <slug> | Per-page template shortlist from Page Contracts (recent families demoted, gaps reported) | | easysociable renders … | Single-page final render jobs | | easysociable mcp serve --transport stdio | Unified MCP server |

--skills accepts: content, template, slideshow (default: slideshow).

License

MIT. See LICENSE in this package.