# SettleMesh Agent Quickstart

Read this before using SettleMesh from Codex, Cursor, Claude Code, CI, or another agent runtime.

## First Time: Localize This Guide (do this once)

If you are an agent reading this for the first time:

1. Save this file into the project as `agent.md` — run `settlemesh agent-md --save`, or fetch `https://www.settlemesh.io/agent.md`.
2. Create a skill / rule in your runtime that says: **"For any SettleMesh task, read `./agent.md` first."** (Claude Code: a skill; Cursor: a rule; Codex/CI: a line in your project instructions.)
3. Authenticate once: run `settlemesh login` — a human approves in the browser. The CLI then reuses the stored session; no further login is needed.
4. Print the shortest reliable path for any task with `settlemesh recipes`.

From then on every SettleMesh task starts from your local `agent.md` and an already-authenticated CLI — no re-deriving how the platform works.

## Core Rule

SettleMesh is a searchable service layer. Do not memorize provider-specific endpoints. Search first, inspect the service or tool contract, then call it. Every call is billed in credits — confirm intent before paid, deploy, publish, or destructive actions.

## Install And Auth

```bash
npm install settlemesh@latest --prefer-online
./node_modules/.bin/settlemesh doctor --require-latest
./node_modules/.bin/settlemesh login
./node_modules/.bin/settlemesh whoami --json
```

The npm package and primary command are both `settlemesh`. The older `settle`, `settlekit`, and `kit` aliases still work for compatibility.

For non-interactive scripts, set an API key instead of `login`. It is sent as `Authorization: Bearer <key>`:

```bash
export SETTLE_API_KEY="sk_..."
```

## Find A Service

```bash
settlemesh search "image generation" --json
settlemesh search "deploy app with login and database" --json
settlemesh search "upload public agent" --json
settlemesh search "local worker compute" --json
```

Then inspect the selected service:

```bash
settlemesh show <service-id> --json
settlemesh tool show <tool-id> --json
```

## Call A Tool

```bash
settlemesh tool call web.search --input '{"q":"SettleMesh"}' --json
settlemesh tool call image.gpt-image-2 --input '{"prompt":"a glass city at sunrise"}' --wait --json
```

Use `--wait` for async jobs and `--confirm` for costly or side-effecting calls. Always parse JSON defensively. Result URLs or payloads may appear in `data.result`, `data.results`, `data.output`, `output`, `url`, `urls`, or nested arrays/objects.

## Credits And Cost

One credit balance pays for every call. Check it and top up before long runs:

```bash
settlemesh credits balance --json
settlemesh credits ledger --limit 20 --json
settlemesh credits topup --credits 500 --json    # opens a checkout session
```

## When A Call Fails (handle these — do not loop blindly)

- **HTTP 402 `insufficient_credits`** — calls are billed *before* they run and your balance is too low. Run `settlemesh credits balance`, then `settlemesh credits topup --credits <n>` (or ask the user to top up), then retry. Do not retry without topping up.
- **HTTP 402 `credit_limit_exceeded`** — the API key hit its own spend cap; use a key with a higher limit.
- **An async job did not finish under `--wait`** — read progress with `settlemesh tool events <job-id> --json`; for deploys use `settlemesh deploy status <app-id>` and `settlemesh deploy logs <build-id>`.
- **`doctor` reports a stale CLI** — reinstall `npm install settlemesh@latest --prefer-online` before continuing.
- **`search` returns nothing useful** — broaden the query, try `settlemesh search --all --category <category>`, or read `settlemesh recipes`.

## Build And Deploy An App

SettleMesh is not a template generator. Build the app normally, then add generic SettleMesh guardrails:

```bash
settlemesh apps doctor . --fix
settlemesh deploy . --name my-app --full-stack --wait --json
```

`--full-stack` provisions and injects SettleMesh auth, a database, a runtime API key, and deployment secrets. Redeploy onto an existing app without changing its public URL by pinning its id:

```bash
settlemesh deploy . --app-id app_123 --full-stack --wait --json
settlemesh deploy status app_123 --json     # if --wait timed out
settlemesh deploy logs build_123 --json      # diagnose a failed build
```

## Use A Managed Database And Auth

`--full-stack` binds a database automatically; you can also manage project backends directly. Database access is server-side only — browsers use project Auth, servers use keys.

```bash
settlemesh projects create --name demo --db postgres --auth email_password,magic_link --json
settlemesh db query <project-id> --sql "select 1" --json
settlemesh db migrate <project-id> --file schema.sql --json
```

## Optional App API Or CLI Command

Use App APIs and App Commands only when the app should expose a route or command for other users or agents.

```bash
settlemesh apps api publish <app-id> --file app-api.json --json
settlemesh apps api call <app-id> <endpoint-id> --input '{}' --json

settlemesh apps commands publish <app-id> --file app-commands.json --json
settlemesh run <command-id> --input '{}' --json
```

## Hand Off To A Human

When a task needs human judgment (confirm, sign in, pay, review), create a login-gated continuation URL instead of guessing:

```bash
settlemesh handoff create <provider-or-app> <action-id> --input '{...}' --json
settlemesh handoff get <session-id> --json
settlemesh open <command-ref> --input '{...}'   # open an app command's web/handoff page with your CLI identity
```

Give the returned URL to the user, then poll `handoff get` for the result.

## Publish A Hosted Agent

```bash
settlemesh agents create --name helper --template hermes --public --max-budget 50 --allowed-capabilities web.search,web.scrape,llm.chat --json
settlemesh agents invoke agent_123 --input '{"prompt":"hello"}' --json
settlemesh agents deploy agent_123 --project ./agent-dir --json
```

## Share Local Compute As A Worker

```bash
settlemesh worker start --name local-model --public --model local/model --endpoint http://localhost:11434/v1/chat/completions --credits-per-second 0.05
```

Other users can find approved public worker offers through service search.

## Load The Toolset Into Your Own Agent Runtime

Export SettleMesh tools as native function schemas for your SDK, including user-published services:

```bash
settlemesh tool schema --format openai --include-services --json
# --format also supports anthropic | mcp | settle
```