SDK and CLI

Use the official TypeScript SDK and command-line client for AlonChat agents

SDK and CLI#

The SDK and CLI are thin clients over the public Chat API. They do not create a separate chatbot runtime, so replies, tools, procedures, permissions, and credit use stay consistent with AlonChat.

TypeScript SDK#

Install the package in a server-side Node.js or TypeScript application:

bash
npm install @alonchat/sdk
ts
import { AlonChatClient } from '@alonchat/sdk'

const alonchat = new AlonChatClient({
  apiKey: process.env.ALONCHAT_API_KEY!,
})

const result = await alonchat.sendMessage({
  agentId: process.env.ALONCHAT_AGENT_ID!,
  message: 'What time do you close?',
  idempotencyKey: crypto.randomUUID(),
})

console.log(result.response)
console.log(result.conversationId)

Continue the same thread:

ts
const next = await alonchat.sendMessage({
  agentId: process.env.ALONCHAT_AGENT_ID!,
  message: 'What about Sunday?',
  conversationId: result.conversationId,
  idempotencyKey: crypto.randomUUID(),
})

Read subscription and usage information:

ts
const subscription = await alonchat.getBillingSubscription()
const usage = await alonchat.getBillingUsage()

console.log(subscription.status, subscription.plan.displayName)
console.log(usage.credits.remaining)

getBillingUsage() and invoice access require the API key's billing_read permission. Subscription status and available-plan reads remain available to a valid project key so an integration can explain an expired or restricted plan and direct the owner to the secure dashboard.

Streaming#

ts
for await (const event of alonchat.streamMessage({
  agentId: process.env.ALONCHAT_AGENT_ID!,
  message: 'Explain your services',
  idempotencyKey: crypto.randomUUID(),
})) {
  if (event.type === 'token') process.stdout.write(event.token)
  if (event.type === 'done') console.log('\nConversation:', event.conversationId)
}

Command-Line Interface#

Run the CLI without installing it globally:

bash
ALONCHAT_API_KEY=sk-your-key npx -y @alonchat/cli chat \
  --agent your-agent-id \
  --message "What time do you close?"

PowerShell:

powershell
$env:ALONCHAT_API_KEY = 'sk-your-key'
npx -y @alonchat/cli chat --agent your-agent-id --message 'What time do you close?'

Billing commands:

bash
alonchat billing status --json
alonchat billing usage --json
alonchat billing plans --json
alonchat billing invoices --input '{"limit":20}' --json

Agent-workbench commands:

bash
alonchat agents inspect --input '{"agentId":"AGENT_UUID"}' --json
alonchat conversations list --input '{"agentId":"AGENT_UUID","limit":20}' --json
alonchat conversations get \
  --input '{"agentId":"AGENT_UUID","conversationId":"CONVERSATION_UUID"}' \
  --json
alonchat design validate --input '{"agentId":"AGENT_UUID", ...proposal }' --json
alonchat design draft \
  --input '{"agentId":"AGENT_UUID","designSessionId":"STABLE_UUID", ...proposal }' \
  --idempotency-key "agent-design-STABLE_UUID-revision-1" \
  --json

See Build agents with Codex or Claude for the proposal contract, evidence rules, permissions, and owner-review boundary.

Useful options:

OptionPurpose
--conversation-id UUIDContinue an existing thread
--idempotency-key KEYMake retries safe
--streamPrint progressive reply events
--jsonProduce machine-readable output
--base-url URLOverride the API origin for local development

You can also set ALONCHAT_BASE_URL in the CLI environment.

Credentials#

Use a project API key with chat permission. Add read_agents only when the integration must list agents, and add billing_read only when it must inspect usage or invoices. Restrict the key to one agent when possible.

Do not expose either package in browser-side code with a real API key.

Related Pages#