TiDB Cloud Filesystem Journal CLI Command Reference
ti fs-journal provides an append-only, verifiable ledger for agent and workflow events. Unlike a mutable text file, a journal assigns ordered sequence numbers, supports structured search, and maintains a hash chain that can detect alteration.
Command tree
ti fs-journal
├── create-journal
├── append-journal-entries
├── read-journal-entries
├── search-journal-entries
└── verify-journal
Prerequisites
Select a Filesystem by ID with locally stored credentials, or provide only TI_FS_TOKEN and TI_REGION_CODE; TI_FS_FILE_SYSTEM_ID is an optional assertion.
Create a journal
ti fs-journal create-journal \
--journal-id jrn-demo \
--journal-kind agent \
--title "demo task" \
--actor agent:ti \
--label env=dev
--journal-id is optional and generated when omitted. Labels are repeatable.
Append entries
Append one or more JSON objects:
ti fs-journal append-journal-entries \
--journal-id jrn-demo \
--entry-json '{"type":"task.started","status":"running"}' \
--entry-json '{"type":"tool.called","tool":"ti"}'
Use --entry-type as a default for entries without type, and add --source or repeatable --subject metadata. --idempotency-key makes a retry deterministic; the CLI generates one when omitted.
For pipelines, send JSON Lines on stdin, or use --json-array for a JSON array.
Read and search
Read entries after a sequence:
ti fs-journal read-journal-entries \
--journal-id jrn-demo \
--after-seq 0 \
--limit 100
Search across journals:
ti fs-journal search-journal-entries \
--entry-type task.started \
--journal-kind agent \
--label env=dev \
--include-entries
Search also supports status, actor, subject, --since, --until, --limit, and pagination cursor filters.
Verify integrity
ti fs-journal verify-journal \
--journal-id jrn-demo \
--output text
Verification recalculates the ordered hash chain and reports whether the entries are internally consistent. It does not assert that the event payload was truthful when originally appended.