Docs
Open SmallForce

CLI

SmallForce CLI: Chat commands

Talk to AI employees in chats

This page covers 6 smallforce chat commands. It is generated from SmallForce CLI 0.1.17; run smallforce chat --help (or any command with --help) to see the same reference for the version you have installed. New to the CLI? Start with installation and authentication and JSON output.

Agent workflow:
  1. Discover a slug: smallforce employees list --json
  2. Start and wait: smallforce chat send "<task>" --employee <slug> --wait
  3. Keep the returned chat id.
  4. Continue: smallforce chat send "<follow-up>" --chat <chatId> --wait

send starts a chat when --employee is used and continues one when --chat is used.
Exactly one is required. Without --wait, send returns once the message is posted.
With --wait, it follows the chat until the employee replies.

Chats are ordinary chats: the team sees them in SmallForce HQ.
Ctrl-C stops watching only; it does not stop the AI employee. Use chat abort for
an explicit cancellation. Use --json for one buffered machine-readable result.

Common options

Most commands accept these options as well as their own. Every command also accepts -h, --help.

OptionDescription
--api-key <key>SmallForce API key, or set SMALLFORCE_API_KEY
--backend-url <url>SmallForce backend URL, or set SMALLFORCE_BACKEND_URL
--jsonPrint stable machine-readable JSON
--textPrint human-readable text
--format <format>Output format: text or json

smallforce chat send

Start or continue a chat with an AI employee

Usage: smallforce chat send [options] <message>

ArgumentDescription
messageTask or follow-up message
OptionDescription
--employee <slug>Start a new chat with this employee
--chat <chatId>Continue this chat
--waitFollow the chat until the employee replies

Also accepts the common options listed at the top of this page.

Exactly one of --employee or --chat is required.

Examples:
  $ smallforce chat send "Review the latest customer feedback" --employee operator
  $ smallforce chat send "Review the latest customer feedback" --employee operator --wait
  $ smallforce chat send "Focus on churn risks" --chat <chatId> --wait
  $ smallforce chat send "Return a concise summary" --chat <chatId> --wait --json

Without --wait, the command returns as soon as the message is posted. The AI
employee continues on its own. With --json --wait, one JSON document is printed
once the employee replies.

smallforce chat list

List chats

Usage: smallforce chat list [options]

OptionDescription
--employee <slug>Only chats this employee is in
--cursor <cursor>Continue from a previous nextCursor
--limit <count>Chats to return, 1-100

Also accepts the common options listed at the top of this page.

Examples:
  $ smallforce chat list
  $ smallforce chat list --employee operator --limit 20 --json
  $ smallforce chat list --cursor <nextCursor> --json

smallforce chat get

Inspect one chat

Usage: smallforce chat get [options] <chatId>

ArgumentDescription
chatIdChat id

Also accepts the common options listed at the top of this page.

Examples:
  $ smallforce chat get <chatId>
  $ smallforce chat get <chatId> --json

smallforce chat messages

Read a chat’s messages

Usage: smallforce chat messages [options] <chatId>

ArgumentDescription
chatIdChat id
OptionDescription
--cursor <cursor>Continue from a previous nextCursor
--limit <count>Messages to return, 1-100

Also accepts the common options listed at the top of this page.

Examples:
  $ smallforce chat messages <chatId>
  $ smallforce chat messages <chatId> --limit 50 --json
  $ smallforce chat messages <chatId> --cursor <nextCursor> --json

smallforce chat watch

Follow the work running in a chat until it finishes

Usage: smallforce chat watch [options] <chatId>

ArgumentDescription
chatIdChat id

Also accepts the common options listed at the top of this page.

Follows every request employees are working on in the chat right now. If no
employee is working, it exits immediately. Ctrl-C detaches without stopping work.

Examples:
  $ smallforce chat watch <chatId>
  $ smallforce chat watch <chatId> --json

smallforce chat abort

Explicitly stop an employee’s current work in a chat

Usage: smallforce chat abort [options] <chatId>

ArgumentDescription
chatIdChat id
OptionDescription
--employee <slug>The employee to stop (default: the chat’s default employee)

Also accepts the common options listed at the top of this page.

This is an explicit cancellation. Do not use it merely to stop local streaming;
Ctrl-C already detaches chat send --wait and chat watch without stopping work.

Examples:
  $ smallforce chat abort <chatId> --json
  $ smallforce chat abort <chatId> --employee operator