Start here before calling any SettleKit capability.

Mental model

Use SettleKit as a discoverable capability layer.

A SettleKit account gives an agent one CLI, one API key, and one tool catalog for models, hosted agents, web tools, image/video generation, deployments, databases, resources, events, and future provider integrations.

Operating rules

Rules every agent should follow.

1. Prefer dynamic discovery over memorized tool names.
2. Use --json whenever output will be parsed.
3. Inspect a tool schema before invoking it.
4. Require explicit user intent before confirmed, costly, secret-bearing, provisioning, or deployment actions.
5. Use --wait --json for long-running calls and parse NDJSON events line by line.
6. Do not ask users for provider secrets unless a tool explicitly requires user-managed credentials.

Authentication

Use browser login for humans and API keys for automation.

npm install -g settlekit
settle login
settle whoami --json

export SETTLE_API_KEY="sk_..."
settle tool list --json

CLI authentication order is SETTLE_API_KEY, then the token saved by settle login. Direct HTTP calls use Authorization: Bearer $SETTLE_API_KEY.

Discovery

Find commands and tools from the live system.

settle help --json
settle help agents --json
settle help tool call --json

settle tool list --query search --json
settle tool show web.search --json

The command tree explains how to operate the CLI. The tool catalog explains executable capability IDs, providers, input schemas, wait behavior, pricing metadata, and follow-up actions.

Tool invocation

Call tools through one standard entrypoint.

settle tool call web.search \
  --input '{"query":"SettleKit agent guide","limit":5}' \
  --json

settle tool call server.sandbox \
  --input '{"name":"demo"}' \
  --confirm \
  --wait \
  --json

Standard JSON responses use {"ok":true,"tool_id":"...","status":"...","data":...,"next":[...],"meta":{...}}. Waiting calls may emit NDJSON events such as started, poll, action_required, completed, failed, and timeout.

HTTP API

Use the same catalog from backend code.

curl https://settlekit.io/v1/tools \
  -H "Authorization: Bearer $SETTLE_API_KEY"

curl https://settlekit.io/v1/capabilities/web.search/invoke \
  -H "Authorization: Bearer $SETTLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":{"query":"latest AI agent deployment patterns"}}'

For model calls, use the OpenAI-compatible API surface where available, including /v1/models and /v1/chat/completions.

Hosted agents

Create cloud agents from templates and editable soul files.

settle agents templates --json
settle agents create --name research-worker --template hermes --json
settle agents soul push agent_... --file ./AGENT.md --json
settle agents invoke agent_... --input '{"task":"summarize the uploaded files"}' --wait --json

Runtime schemas

Export tools for other agent runtimes.

settle tool schema \
  --format openai \
  --allowed web.search,image.gpt-image-2 \
  --include-local \
  --json

Use schema export when connecting SettleKit to OpenAI, Anthropic-style adapters, Hermes, OpenClaw, or custom hosted runtimes. Remote tools come from the live catalog; local runtime declarations such as shell, file, and memory tools are declared only when requested.

Errors and safety

Handle failures as structured protocol states.

This guide stays current because agents should discover command and tool metadata at runtime instead of depending on static examples.