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.
| Option | Description |
|---|---|
--api-key <key> | SmallForce API key, or set SMALLFORCE_API_KEY |
--backend-url <url> | SmallForce backend URL, or set SMALLFORCE_BACKEND_URL |
--json | Print stable machine-readable JSON |
--text | Print 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>
| Argument | Description |
|---|---|
message | Task or follow-up message |
| Option | Description |
|---|---|
--employee <slug> | Start a new chat with this employee |
--chat <chatId> | Continue this chat |
--wait | Follow 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]
| Option | Description |
|---|---|
--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>
| Argument | Description |
|---|---|
chatId | Chat 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>
| Argument | Description |
|---|---|
chatId | Chat id |
| Option | Description |
|---|---|
--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>
| Argument | Description |
|---|---|
chatId | Chat 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>
| Argument | Description |
|---|---|
chatId | Chat id |
| Option | Description |
|---|---|
--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