kt history
The kt history command group works with captured gateway sessions: listing
them, reading one session, exporting, tagging, searching, sharing, replaying,
learning, summarizing, and deleting. Every command in this group requires API
authentication.
List sessions
kt history list-sessions
kt history list-sessions --scope org --limit 25
kt history list-sessions --agent-id agent_main --tag reviewed --json
Available filters include --scope, --team-id, --agent-id, --tag,
--since, and --until. --since and --until take RFC3339 timestamps and
are applied client-side to the session page returned by the API; the CLI then
applies --limit to that filtered page.
Get one session
kt history get-session --session-id 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c
kt history get-session --session-id 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c --include-entries
kt history get-session --session-id 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c --include-entries --json
--include-entries makes a second entries request. If that request fails, the
CLI warns and still returns the session without an entries array.
Export
SESSION_ID="7f92ff69-7b29-4f2d-a8bb-766c06e61d3c"
kt history export "$SESSION_ID"
kt history export "$SESSION_ID" --format markdown --output ./exports/session.md
kt history export "$SESSION_ID" --format json --output ./exports/session.json
kt history export "$SESSION_ID" --format txt --output ./exports/session.txt
The CLI exports one session in markdown (the default), json, or txt and
requires history:read access to that session. It requests entries in stable
500-entry pages and writes them in API order. If a page is malformed, repeats
an entry, breaks request_index ordering, or ends before the session's
reported entry_count, the command exits nonzero and does not create the
requested output file.
History export capabilities differ by surface:
| Surface | Selection | Formats | Current bound |
|---|---|---|---|
| Console History list | No download action | — | — |
kt history export | One session | markdown, json, txt | Pages through the complete authorized session |
GET /v1/history/sessions/{id}/export | One session | markdown, json, csv | First 1,000 entries |
POST /v1/history/sessions/export | At most 50 session IDs | jsonl, csv | First 1,000 entries per session |
The API-native exports return the artifact synchronously; they do not create an Evidence Export job. No History export surface currently supports PDF.
Tag
kt history tag 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c --tag important
kt history tag 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c --tag reviewed --json
kt history tag 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c --remove draft
kt history tag 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c
With neither --tag nor --remove, the command lists the current tags.
Search
kt history search --query "deployment error"
kt history search --query "API timeout" --entry-kind assistant
kt history search --query "budget" --agent-id bcb8904e-d692-42bd-a176-bc5d408405b4 --limit 20
kt history search --query "compliance" --json
--query is required. The CLI uses the history search endpoint first. If that
endpoint returns HTTP 503, it prints a warning and performs a bounded
client-side search over paged sessions and entries instead. The fallback is a
best-effort substring search and can differ from the server search service.
Share
kt history share --with alice@example.com 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c
kt history share --with 0e959678-8740-482b-890e-05aa61884664 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c --json
The share command shares a session with a specific user or email address. It does not generate an expiring public link.
Replay
kt history replay 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c
kt history replay 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c --gateway-id gateway_prod_01
Replay replays one session. Use --gateway-id when you want to target a specific gateway instead of the session's original gateway.
Replay is not a dry run. The CLI submits each replayable user request to the
history replay endpoint, which may invoke a provider and incur usage or cost.
Only entries with an object request_payload, a messages array, and a final
user message are replayed.
Stats
kt history stats
kt history stats --scope team --team-id a67d04a3-68d9-43df-8987-cf0828503756
kt history stats --agent-id bcb8904e-d692-42bd-a176-bc5d408405b4 --json
The CLI prefers the aggregate stats endpoint. If that request fails, returns a non-success status, or cannot be decoded, it computes a local summary from the single sessions page returned by the list endpoint. Treat that fallback as a page snapshot rather than a complete aggregate.
Learn from history
kt history learn --bind-to-session 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c
kt history learn --scope team --team-id a67d04a3-68d9-43df-8987-cf0828503756 --agent-id bcb8904e-d692-42bd-a176-bc5d408405b4
kt history learn --bind-to-session 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c --dry-run --json
Without --bind-to-session, the CLI selects the most recent session matching
the optional scope, team, and agent filters. The default strategy is
condense, with up to four previous sessions and a 1,200-token target. Adjust
those values with --strategy, --previous-sessions-max, and
--target-max-tokens.
--dry-run fetches and previews the selected session's source entries without
posting the /learn request. A normal invocation requests server-side history
learning.
Delete a session
kt history delete-session --session-id 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c --yes
Condense
kt history condense --session-id 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c
kt history condense --session-id 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c --output history-condensed.json
kt history condense --scope org --allowed-only --dry-run
Condensation is local and deterministic in the CLI. condense and hybrid
currently use the same deterministic extraction path as extract; none of the
three strategies calls an LLM. Use --include-blocked to include blocked
entries, or --allowed-only to retain only allowed entries.