@easysociable/cli

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.