kt chat

The kt chat command opens an interactive terminal REPL for governed AI conversations. It can stream assistant responses from a Keeptrusts gateway, apply local policy checks from a CLI config, resume prior history sessions from the API, and call memory or learning APIs when the CLI is authenticated.

Use this page when

You want to have AI conversations directly from the terminal.
You need a terminal-first chat surface for operator workflows, automation support, or testing.
You want to test policy enforcement without the console UI.
You need to resume a prior session or branch from the current conversation state.

Primary audience

Primary: AI Agents, Technical Engineers
Secondary: Technical Leaders

Starting a Session

kt chat --gateway http://localhost:41002
kt chat --model gpt-5.4-mini --gateway http://localhost:41002
kt chat --agent <agent-uuid> --gateway http://localhost:41002
kt chat --resume <session-uuid> --gateway http://localhost:41002
kt chat --gateway http://localhost:41002 --config ./policy-config.yaml

Common options:

--model: Override the default model. Default: gpt-5.4-mini.
--agent: Attach an agent UUID for session attribution and API-backed context injection.
--resume: Load a prior history session from the API by UUID.
--gateway: Target a specific Keeptrusts gateway URL for live completions.
--config: Load a local policy config for in-process input and output enforcement.
--no-stream: Disable SSE streaming and print the full assistant response after completion.

The REPL can start without --gateway, but user messages require a reachable gateway URL. Without one, only local slash-command workflows are available. Use kt auth login first if you plan to resume sessions or use memory and learning commands.

Interactive REPL

Once started, you stay in an interactive session. Type a message and press Enter to send it. When --gateway is set, responses stream in real time by default.

Keeptrusts Interactive Chat
Session:  3f2a0c2a-0f44-4ee8-a8f2-7c0c12345678
Model:    gpt-5.4-mini
Gateway:  remote
Type /help for available commands, /quit or Ctrl-D to exit.

[gpt-5.4-mini] > What is the deployment process?
assistant: Based on the deployment documentation...

[gpt-5.4-mini] > /branch
Branch point: session_id=3f2a0c2a-0f44-4ee8-a8f2-7c0c12345678
Use `kt chat --resume 3f2a0c2a-0f44-4ee8-a8f2-7c0c12345678` to continue from here.

Interactive quality-of-life features:

Slash-command completion is available in interactive mode.
Line editing history is stored in ~/.keeptrusts/chat_history.
End a line with \ to continue onto the next line.

Slash Commands

Command	Description
`/memory add <text>`	Create a memory through the API for the current session context
`/memory list`	Show recalled memories for the current session
`/recall`	Run a recall simulation through the API
`/learn`	Submit the current session to the learning workflow
`/export [md	json
`/branch`	Print a branch point session id you can resume later
`/clear`	Clear in-memory conversation context for the current REPL
`/model <name>`	Switch model mid-conversation
`/cost`	Show the current session token and cost summary
`/help`	Show available commands
`/quit`	Exit the session (`/exit`, `/q`, and Ctrl-D also work)

Commands that call the API (/memory ..., /recall, /learn) require authenticated CLI access.

SSE Streaming

By default, kt chat sends stream: true to the gateway and renders SSE chunks token-by-token as they arrive.

Use --no-stream when you want the full response buffered before printing.
Streaming output is rendered directly in the terminal as assistant: text arrives.
If the gateway request fails, the CLI prints the HTTP or transport error and keeps the session open.
Ctrl-C cancels the current input line; Ctrl-D exits the REPL.

Policy Enforcement

kt chat supports local policy evaluation when you provide --config.

Input messages are evaluated before the gateway call.
Assistant responses are evaluated again after the gateway returns.
Blocked messages display a policy violation with the rule reason code.
Redaction outcomes display a redaction notice before the assistant response is shown.
Agent context injection can add system context from the API on the first user turn when --agent and API auth are configured.

Session Management

Each chat session has a generated session id.
--resume <session-uuid> reloads prior entries from /v1/history/sessions/{id}/entries when API access is configured.
/branch prints the current session id as a checkpoint you can resume later.
Use kt history list-sessions to find resumable session ids.
On exit, the CLI saves local line-editing history and prints a session summary.

Non-Interactive Mode

The current public kt chat command is an interactive REPL. A one-shot --no-interactive mode is not part of the current CLI surface.

For scripting or automation today:

Use /export json to print the current session in a machine-readable format.
Use --no-stream when you want deterministic buffered output in an interactive shell.
Use kt history list-sessions and kt history get-session --include-entries for post-run automation.
Use the gateway's OpenAI-compatible /v1/chat/completions HTTP endpoint directly for one-shot scripted requests.

For AI systems

Canonical command: kt chat
Supported slash commands: /memory add, /memory list, /recall, /learn, /export, /branch, /clear, /model, /cost, /help, /quit
Related: kt history (session management), CLI task surfaces outside kt chat for task creation workflows
The current public kt chat surface does not expose /task, /approve, /deny, /pin, /search, or /settings slash commands

For engineers

Prerequisites: authenticated CLI for resume, memory, and learning features; reachable gateway URL for live completions; optional local policy-config.yaml for in-process policy checks.
Quick start: kt chat --gateway http://localhost:41002
Use --resume <session-uuid> only when the target session already exists in the history API.
Use --no-stream for buffered output when debugging gateway behavior or capturing terminal transcripts.

For leaders

kt chat gives operators a governed terminal surface for fast policy validation without needing the console UI.
Resume, export, and history integration help teams capture repeatable test conversations and audit trails.
Local config enforcement makes it useful for pre-console rollout checks and incident-response drills.

Use this page when​

Primary audience​

Starting a Session​

Interactive REPL​

Slash Commands​

SSE Streaming​

Policy Enforcement​

Session Management​

Non-Interactive Mode​

For AI systems​

For engineers​

For leaders​

Next steps​