Problem
The sync command is the main way to backfill chat history, but the name doesn't communicate this clearly. An AI agent trying to "download/index/export chat history" doesn't intuitively reach for sync. The actual workflow is:
sync jobs add --chat <id> --depth N — create a backfill job
sync --once — run backfill
sync jobs list — check progress
This took significant trial-and-error to discover. The channels sync --enable/--disable command adds to the confusion (is that the same sync? different?).
Proposal
-
Rename sync → backfill as the primary command name
- Keep
sync as an alias for backward compatibility (forks/existing users)
tgcli backfill --chat <id> --depth 5000 — single command to add job + run it
-
Simplify the common case:
# Current: 2 steps
tgcli sync jobs add --chat <id> --depth 5000
tgcli sync --once
# Proposed: 1 step
tgcli backfill --chat <id> --depth 5000
-
Clarify relationship with channels sync — maybe rename to channels watch or channels follow to avoid the name collision.
Context
This is especially important for AI agent usage. Agents discover commands via --help and need clear, self-documenting command names. "backfill" immediately communicates intent; "sync" is ambiguous.
Problem
The
synccommand is the main way to backfill chat history, but the name doesn't communicate this clearly. An AI agent trying to "download/index/export chat history" doesn't intuitively reach forsync. The actual workflow is:sync jobs add --chat <id> --depth N— create a backfill jobsync --once— run backfillsync jobs list— check progressThis took significant trial-and-error to discover. The
channels sync --enable/--disablecommand adds to the confusion (is that the same sync? different?).Proposal
Rename
sync→backfillas the primary command namesyncas an alias for backward compatibility (forks/existing users)tgcli backfill --chat <id> --depth 5000— single command to add job + run itSimplify the common case:
Clarify relationship with
channels sync— maybe rename tochannels watchorchannels followto avoid the name collision.Context
This is especially important for AI agent usage. Agents discover commands via
--helpand need clear, self-documenting command names. "backfill" immediately communicates intent; "sync" is ambiguous.