cxntion CLI

Connect a self-hosted AI agent to cxntion managed SMS.

Canonical project rules, launch evidence, and blockers live in ../CLAUDE.md. The root README.md is the public overview; this file stays focused on CLI usage.

Usage

Public beta access is invite-reviewed. Once your email is invited, sign in to the dashboard, create or select an agent, and run the CLI from the same machine that can reach the agent endpoint.

npx cxntion init
npx cxntion doctor
npx cxntion connect

init saves your cxntion API key, agent ID, target endpoint, adapter, and optional endpoint API key in ~/.cxntion/config.json. Public launch is in a request-access phase, so dashboard/API-key access is invite-reviewed until SMS, billing, and promotion gates are green. doctor is mandatory before connect: it proves cxntion API auth, tunnel reachability, local endpoint reachability, adapter/model/auth, latency, and cxntion metadata support before any production number is attached. cxntion API keys are shown only when created or rotated; store the new key in your process manager or local config when you generate it.

cxntion public launch uses managed Twilio SMS. Users bring the agent endpoint, not provider API keys.

Agent prompt

Paste this into your agent's system or developer instructions before connecting it to cxntion:

You are connected to cxntion, a managed SMS bridge for this agent.

When a cxntion message arrives:
- Treat it as a text message from a real human.
- Reply with only the exact SMS text that should be sent back.
- Keep replies concise, clear, and useful. Avoid long paragraphs, markdown tables, and JSON unless the user explicitly asks for them.
- Use cxntion metadata when available: channel, caller number, timestamp, requestId, session, and recent context.
- Keep caller context isolated by caller number. Never leak information from one caller to another.
- Do not ask for or expose API keys, auth tokens, provider credentials, or internal system details.
- If the user asks for a high-impact action, confirm before doing it.
- If you are unsure, ask one brief clarifying question.
- If a request cannot be completed by SMS, explain the next step briefly.

If your integration exposes a cxntion request ID, preserve it in your internal protocol response exactly as received. Do not show request IDs to the SMS user.

Tune the agent's business policy, tool permissions, and escalation rules for your own use case. cxntion transports messages; your agent remains responsible for its own behavior.

Non-interactive setup

Use init --yes for droplets, PM2, systemd, CI smoke fixtures, and other scripted installs. It writes the same ~/.cxntion/config.json as the wizard, so doctor and connect stay unchanged.

Hermes:

npx cxntion init --yes \
  --key "$CXNTION_API_KEY" \
  --agent "$CXNTION_AGENT_ID" \
  --adapter hermes \
  --target http://localhost:8642/v1/chat/completions \
  --model hermes-agent \
  --api-key-env API_SERVER_KEY
npx cxntion doctor
npx cxntion connect

OpenClaw:

npx cxntion init --yes \
  --key "$CXNTION_API_KEY" \
  --agent "$CXNTION_AGENT_ID" \
  --adapter openclaw \
  --target ws://localhost:18789
npx cxntion doctor
npx cxntion connect

Hermes

Hermes works through its OpenAI-compatible API server:

npx cxntion connect \
  --adapter openai \
  --target http://localhost:8642/v1/chat/completions \
  --model hermes-agent \
  --api-key "$API_SERVER_KEY"

The CLI adds stable Hermes session headers for cxntion traffic so SMS threads enter Hermes through the API-server platform path without patching the Hermes agent itself.

OpenClaw

npx cxntion connect \
  --adapter openclaw \
  --target ws://localhost:18789

OpenClaw receives cxntion messages as user_message frames with source: "cxntion" and metadata for channel, session, caller, context, timestamp, and requestId. Private voice-alpha frames may also include callId.

Diagnostics

npx cxntion doctor

doctor should pass before attaching a production number. It checks cxntion API auth, tunnel reachability, local endpoint reachability, adapter/model/auth, latency, and whether the adapter can receive cxntion channel metadata.

For OpenAI-compatible endpoints:

npx cxntion doctor \
  --adapter openai \
  --target http://localhost:8642/v1/chat/completions \
  --model hermes-agent \
  --api-key "$API_SERVER_KEY"

doctor also prints the effective agent response timeouts. Defaults are 30s for SMS and 30s for the private voice alpha path; override with --sms-timeout-ms, --voice-timeout-ms, CXNTION_SMS_AGENT_TIMEOUT_MS, or CXNTION_VOICE_AGENT_TIMEOUT_MS when testing unusually slow agents.

The public package installs the cxntion CLI. Dashboard/API-key access and managed SMS number activation remain invite-reviewed during beta.