Semesh CLI

Semesh is a CLI-first tool platform for developers, scripts, and AI agents. The npm package and primary command are both semesh.

Install

Requires Node.js 22.14.0 or newer. End-of-life Node.js releases are not supported.

For AI agents, clean terminals, and project-specific deploys, prefer a project-local latest install. This avoids stale global binaries:

npm install semesh@latest --prefer-online
./node_modules/.bin/semesh doctor --require-latest
./node_modules/.bin/semesh recipes

Global install is also supported for interactive use:

npm install -g semesh
semesh doctor

Each published package contains the complete supported binary matrix and verifies the host binary against its commit-bound SHA-256 manifest during installation and every invocation. After npm has downloaded the package, installation does not depend on a GitHub Release or any other binary host. For reproducible CI, pin an exact version such as [email protected] instead of a moving tag.

The package exposes the primary command:

semesh --version

Older settle / kit aliases may exist on machines that installed the legacy package. New installs use semesh only so they do not collide with legacy global binaries.

Project-local install also works:

npm install semesh@latest --prefer-online
./node_modules/.bin/semesh help

Login

semesh login

For CI, scripts, and hosted agents:

export SEMESH_API_KEY="sk_..."

Use SEMESH_BASE_URL=http://localhost:8080 for local development, and SEMESH_REQUEST_TIMEOUT=90s for slow provider calls.

Use as an MCP server

semesh mcp runs a stdio Model Context Protocol server so any MCP-compatible client (Claude Code, Claude Desktop, Cursor, Codex) can call the Semesh capability catalog directly — discover a tool by search, then invoke any of them, with a confirm step before any paid call. It authenticates with your existing semesh login session or SEMESH_API_KEY; the key is never written to the protocol stream or logs.

Claude Code (one line):

claude mcp add semesh --env SEMESH_API_KEY=sk-semesh-... -- npx -y semesh mcp

Claude Desktop (claude_desktop_config.json) or Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "semesh": {
      "command": "npx",
      "args": ["-y", "semesh", "mcp"],
      "env": { "SEMESH_API_KEY": "sk-semesh-..." }
    }
  }
}

Codex (~/.codex/config.toml):

[mcp_servers.semesh]
command = "npx"
args = ["-y", "semesh", "mcp"]
env = { SEMESH_API_KEY = "sk-semesh-..." }

Run semesh login first to omit the key entirely.

Use Tools

Always use discovery before calling tools:

semesh help --json
semesh recipes
semesh tool list --json
semesh tool show web.search --json

For a no-context agent, start with the built-in golden paths:

npm install semesh@latest --prefer-online
./node_modules/.bin/semesh doctor --require-latest
./node_modules/.bin/semesh recipes
./node_modules/.bin/semesh search "build app with login database api command"
./node_modules/.bin/semesh services show app-project-backends --json

semesh recipes covers the shortest flows for full-stack app deploys, App API/CLI commands, browser bridge URLs, hosted agents, and local worker offers.

Call a tool with JSON input:

semesh tool call web.search \
  --input '{"q":"Semesh","count":5}' \
  --json

Generate an image task:

semesh tool call image.gpt-image-2 \
  --input '{"prompt":"A clean product photo of a ceramic tea cup","size":"1:1"}' \
  --json

Poll async media:

semesh tool events image_... --json

Upload a local image for image-to-image:

semesh files upload ./input.png --json
semesh tool call image.gpt-image-2 \
  --input '{"prompt":"Turn this into a clean product photo","size":"1:1"}' \
  --image-file ./input.png \
  --json

Recognize a local video with a multimodal LLM (use the default temporary upload; do not use --durable for model inputs):

semesh files upload ./clip.mp4 --json
semesh call llm.chat \
  --input '{"model":"google/gemini-3-flash-preview","messages":[{"role":"user","content":[{"type":"text","text":"Summarize this video."},{"type":"file","file":{"filename":"clip.mp4","file_data":"<paste returned data.url>"}}]}]}' \
  --json

Credits

semesh credits balance --json
semesh credits ledger --json
semesh credits topup --credits 100 --json

Hosted Agents

Create from a built-in template and make it callable by other accounts:

semesh agents templates --json
semesh agents create \
  --name research-helper \
  --template hermes \
  --public \
  --max-budget 50 \
  --allowed-capabilities web.search,web.scrape,llm.chat \
  --json
semesh agents invoke agent_... --input '{"prompt":"Find three primary sources."}' --json

You can share the returned agent_id; other users can call public agents directly by id with semesh agents invoke or semesh tool call agent.invoke.

Managed Backends

Create a Semesh project with database + app auth:

semesh projects create --name demo --db sqlite --auth email_password,magic_link
semesh db query proj_... --sql "select 1"
semesh db migrate proj_... --file schema.sql
semesh db connection proj_...
semesh auth users proj_...

semesh db connection is redacted by default. Add --reveal only in a trusted terminal. Database SQL endpoints accept a developer key or the one-time project server key returned by projects create; browser/public project keys are only for app auth.

Full-stack Apps, App APIs, and CLI Commands

Deploy a local app project with Semesh auth, database, runtime API keys, and optional payment bindings:

./node_modules/.bin/semesh deploy ./my-next-app --name my-next-app --full-stack --wait --json

Expose selected routes from that app as APIs and CLI commands:

semesh apps api publish app_... --file app-api.json --json
semesh apps api call app_... summarize --input '{"topic":"shipping"}' --json
semesh apps commands publish app_... --file app-commands.json --json
semesh run app:app_....summarize --input '{"topic":"shipping"}' --open --json

When a command has a web binding, --open can return a short-lived URL that opens the app in the browser using the caller's Settle login, without a second manual login.

Local Worker Offers

Share a local OpenAI-compatible endpoint as a callable service:

semesh search "lend local compute worker offer"
semesh worker start --name local-model --public --model local/model --endpoint http://localhost:11434/v1/chat/completions --credits-per-second 0.05
semesh worker-offers list --json

Public Tool Surface

The public CLI surface includes discovery, tools, full-stack app deployment, App APIs/commands, hosted agents, local worker offers, credits, files, and managed project/database/auth operations. Provider-specific operations may still be gated on a given deployment. Inspect each tool's availability, policy, and input_schema before side-effecting or costly calls.