verdictan history
The verdictan history command group works with captured gateway sessions. You can
list, read, export, tag, search, share, replay, learn from, and summarize
sessions. Each command in this group must use API authentication.
List sessions
verdictan history list-sessions
verdictan history list-sessions --scope org --limit 25
verdictan 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 accept RFC3339 timestamps and
apply to the session page that the API returns. The CLI then applies --limit
to that filtered page.
Get one session
verdictan history get-session --session-id 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c
verdictan history get-session --session-id 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c --include-entries
verdictan 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 reports a warning and returns the session without an entries array.
Export
SESSION_ID="7f92ff69-7b29-4f2d-a8bb-766c06e61d3c"
verdictan history export "$SESSION_ID"
verdictan history export "$SESSION_ID" --format markdown --output ./exports/session.md
verdictan history export "$SESSION_ID" --format json --output ./exports/session.json
verdictan history export "$SESSION_ID" --format txt --output ./exports/session.txt
The CLI exports one session in markdown, json, or txt. The default is
markdown. You must have history:read access to the session.
The CLI requests entries in stable 500-entry pages and writes them in API
sequence. The command exits nonzero if a page has an error or a duplicate entry.
It also fails if the page does not use request_index sequence or ends before the reported
entry_count. After a failure, the CLI does not create the requested output
file.
History export capabilities are different for each surface:
| Surface | Selection | Formats | Active bound |
|---|---|---|---|
| Console History list | No download action | — | — |
verdictan 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 for each session |
The API-native exports return the artifact synchronously. They do not create an Evidence Export job. No History export surface supports PDF.
Tag
verdictan history tag 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c --tag important
verdictan history tag 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c --tag reviewed --json
verdictan history tag 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c --remove draft
verdictan history tag 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c
Without --tag and --remove, the command lists the assigned tags.
Search
verdictan history search --query "deployment error"
verdictan history search --query "API timeout" --entry-kind assistant
verdictan history search --query "budget" --agent-id bcb8904e-d692-42bd-a176-bc5d408405b4 --limit 20
verdictan history search --query "compliance" --json
You must specify --query. The CLI uses the history search endpoint first. If that
endpoint returns HTTP 503, the CLI prints a warning. It then does a bounded
client search through session and entry pages. This limited substring search
can give different results from the server search service.
Share
verdictan history share --with alice@example.com 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c
verdictan history share --with 0e959678-8740-482b-890e-05aa61884664 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c --json
The share command shares a session with a specified user or email address. It does not generate an expiring public link.
Replay
verdictan history replay 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c
verdictan history replay 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c --gateway-id gateway_prod_01
Replay sends one session again. Use --gateway-id to select a specified gateway
as an alternative to the initial gateway.
Do not use replay as a dry run. The CLI submits each replayable user request
to the history replay endpoint. A replay can invoke a provider and cause usage
or cost. Only entries with an object request_payload, a messages array, and
a last user message qualify for replay.
Stats
verdictan history stats
verdictan history stats --scope team --team-id a67d04a3-68d9-43df-8987-cf0828503756
verdictan history stats --agent-id bcb8904e-d692-42bd-a176-bc5d408405b4 --json
The CLI first uses the aggregate stats endpoint. If that request fails, the CLI calculates a local summary from one sessions page. It also uses this local summary for a non-success status or a decode error. This summary is a page snapshot, not a complete aggregate.
Learn from history
verdictan history learn --bind-to-session 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c
verdictan history learn --scope team --team-id a67d04a3-68d9-43df-8987-cf0828503756 --agent-id bcb8904e-d692-42bd-a176-bc5d408405b4
verdictan 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. An invocation without --dry-run requests
server-side history learning.
Condense
verdictan history condense --session-id 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c
verdictan history condense --session-id 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c --output history-condensed.json
verdictan history condense --scope org --allowed-only --dry-run
The CLI makes condensed output locally and deterministically. condense and
hybrid use the same extraction path as extract. None of the three
strategies calls an LLM. Use --include-blocked to include blocked entries. Use
--allowed-only to keep only allowed entries.
The CLI can continue when it cannot fetch some source entries. It prints a warning in this condition. Review the warnings before you use condensed output, because the result can be incomplete.