settlemesh

SettleMesh CLI

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

Install

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

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

Global install is also supported for interactive use:

npm install -g settlemesh
settlemesh doctor

The package exposes the primary command:

settlemesh --version

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

Project-local install also works:

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

Login

settlemesh login

For CI, scripts, and hosted agents:

export SETTLE_API_KEY="sk_..."

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

Use as an MCP server

settlemesh mcp runs a stdio Model Context Protocol server so any MCP-compatible client (Claude Code, Claude Desktop, Cursor, Codex) can call the SettleMesh 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 settlemesh login session or SETTLE_API_KEY; the key is never written to the protocol stream or logs.

Claude Code (one line):

claude mcp add settlemesh --env SETTLE_API_KEY=sk-settle-... -- npx -y settlemesh mcp

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

{
  "mcpServers": {
    "settlemesh": {
      "command": "npx",
      "args": ["-y", "settlemesh", "mcp"],
      "env": { "SETTLE_API_KEY": "sk-settle-..." }
    }
  }
}

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

[mcp_servers.settlemesh]
command = "npx"
args = ["-y", "settlemesh", "mcp"]
env = { SETTLE_API_KEY = "sk-settle-..." }

Run settlemesh login first to omit the key entirely.

Use Tools

Always use discovery before calling tools:

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

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

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

settlemesh 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:

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

Generate an image task:

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

Poll async media:

settlemesh tool events image_... --json

Upload a local image for image-to-image:

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

Credits

settlemesh credits balance --json
settlemesh credits ledger --json
settlemesh credits topup --credits 100 --json

Hosted Agents

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

settlemesh agents templates --json
settlemesh agents create \
  --name research-helper \
  --template hermes \
  --public \
  --max-budget 50 \
  --allowed-capabilities web.search,web.scrape,llm.chat \
  --json
settlemesh 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 settlemesh agents invoke or settlemesh tool call agent.invoke.

Managed Backends

Create a SettleMesh project with database + app auth:

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

settlemesh 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 SettleMesh auth, database, runtime API keys, and optional payment bindings:

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

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

settlemesh apps api publish app_... --file app-api.json --json
settlemesh apps api call app_... summarize --input '{"topic":"shipping"}' --json
settlemesh apps commands publish app_... --file app-commands.json --json
settlemesh 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:

settlemesh search "lend local compute worker offer"
settlemesh worker start --name local-model --public --model local/model --endpoint http://localhost:11434/v1/chat/completions --credits-per-second 0.05
settlemesh 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.