Skip to content

Rename sync to backfill, improve discoverability for AI agents #30

@kfastov

Description

@kfastov

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:

  1. sync jobs add --chat <id> --depth N — create a backfill job
  2. sync --once — run backfill
  3. 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

  1. Rename syncbackfill 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
  2. 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
  3. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions