Conversations & History

CLI

The Hutly CLI exposes two read/search surfaces over your org’s activity:

conversations (alias conv) — search, browse, and dispatch handoffs across the conversations the calling user can access.
history — search across everything the org has done: conversations, feed outputs, and workflows.

Both groups emit machine-readable JSON. The --json flag is the default for most commands and is accepted as a no-op everywhere for compatibility. Add --pretty to any command for pretty-printed output. Results are scoped to what the calling user’s role and org membership grant — you only ever see conversations you can access and history within your own org.

Conversations

hutly conversations <command> [options]
hutly conv <command> [options]   # alias

list

List conversations the calling user has access to, most recent first. Returns a paginated envelope — read paginationHint in the response for a copy-pasteable next-page command, or use nextCursor directly.

hutly conv list
hutly conv list --agent-id <agentId> --limit 50
hutly conv list -q "lease renewal" --cursor 20

Option	Description
`--agent-id <id>`	Filter by agent UUID
`-q, --query <q>`	Filter by title / agent-name substring
`-l, --limit <n>`	Max results (default 20, max 100)
`-c, --cursor <n>`	Numeric offset for pagination
`--pretty`	Pretty-print JSON

show

Print all messages from a single conversation in chronological order. Aliased as get.

hutly conv show <conversationId>
hutly conv get <conversationId> --pretty

Option	Description
`--pretty`	Pretty-print JSON

search

Search past message bodies. Defaults to keyword search (tsvector); pass --semantic for embedding-based cosine search.

Keyword mode returns a paginated envelope with a paginationHint. Semantic mode returns the top-K matches by embedding similarity and ignores --cursor — raise --limit to widen the result set instead.

hutly conv search "bond lodgement"
hutly conv search "tenant wants to break lease" --semantic --limit 10
hutly conv search "invoice" --agent-id <agentId> --from-date 2026-01-01 --to-date 2026-03-31

Option	Description
`--semantic`	Use semantic (embedding) search instead of keyword
`--agent-id <id>`	Restrict to a single agent
`--conversation-id <id>`	Restrict to a single conversation
`--from-date <iso>`	Earliest message `createdAt` (ISO 8601)
`--to-date <iso>`	Latest message `createdAt` (ISO 8601)
`-l, --limit <n>`	Max results (default 20, max 100)
`-c, --cursor <n>`	Numeric offset for pagination (keyword mode only)
`--pretty`	Pretty-print JSON

The response includes a mode field set to keyword or semantic.

send-to-agent

Fire-and-forget: dispatch a message to another agent. The reply lands as a system message in the calling conversation when the sub-agent finishes. End your turn after dispatch — do not poll for the result.

The callback conversation defaults to the HUTLY_CONVERSATION_ID environment variable (set automatically inside an agent code-interpreter session). Outside such a session you must pass --callback-conversation-id explicitly or the command errors.

hutly conv send-to-agent <agentId> "Summarise the latest inspection report"
hutly conv send-to-agent <agentId> "Draft a reply" --callback-conversation-id <conversationId>

Option	Description
`-c, --callback-conversation-id <id>`	Conversation that receives the system-message reply. Defaults to `HUTLY_CONVERSATION_ID`.
`--pretty`	Pretty-print JSON

The response returns the jobId, status, and dispatchedAt for the dispatched handoff.

jobs

Inspect pending and completed agent-handoff jobs initiated by this user. Has two subcommands.

jobs status

Show status and a result preview for a single handoff job.

hutly conv jobs status <jobId>

Option	Description
`--pretty`	Pretty-print JSON

jobs list

List recent handoff jobs initiated by this user, most recent first.

hutly conv jobs list
hutly conv jobs list --status pending
hutly conv jobs list --status completed --limit 50

Option	Description
`--status <s>`	Filter by status: `pending`, `completed`, `failed`, or `orphaned`
`-l, --limit <n>`	Max results (default 20, max 100)
`-c, --cursor <s>`	Pagination cursor from the previous response
`--pretty`	Pretty-print JSON

History

hutly history <command> [options]

search

Find prior work by keyword across conversations, feed outputs, and workflows — including archived items. Use it when a user refers to something they did before but can’t pinpoint it, then link the best match. Results are scoped to the calling user’s org.

hutly history search "end of financial year report"
hutly history search "rent increase" --types conversation,output
hutly history search "vacate notice" --limit 25 --no-include-deleted

Option	Description
`--types <list>`	Comma-separated subset of `conversation`, `output`, `workflow` (default all)
`-l, --limit <n>`	Max results per type (default 8, max 25)
`--no-include-deleted`	Exclude archived / soft-deleted items (included by default)
`--pretty`	Pretty-print JSON

The response returns results plus a count of the total matches across all types.

Integrations Custom Tables