From 7a5976481d73d43fa0665ad0329bf814e5784a6b Mon Sep 17 00:00:00 2001
From: Aleksandr Razumov <ernado@go-faster.org>
Date: Sat, 13 Jun 2026 00:03:02 +0300
Subject: [PATCH] feat: migrate CLI to cobra and add roadmap

Replace urfave/cli/v2 with spf13/cobra for the command surface, giving
first-class shell completion and doc generation:

- Root command with persistent global flags, command groups, and flag-name
  normalization preserving old aliases (--staging/--target/--msg/--as).
- init/send/upload ported to cobra with rich Short/Long/Example help.
- Dynamic completion for --peer (self aliases for now) and enum completion
  for --type; enum flag reimplemented as a pflag.Value.
- Hidden `docs` command generating Markdown/man pages from the tree.
- Switch error handling from golang.org/x/xerrors to go-faster/errors
  (Wrap/Wrapf house style).

Also add ROADMAP.md describing the agent-automatable CLI plan.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 ROADMAP.md           | 238 +++++++++++++++++++++++++++++++++++++++++++
 cmd/tg/app.go        |  82 +++++++++------
 cmd/tg/common.go     |  64 ++++++------
 cmd/tg/completion.go |  29 ++++++
 cmd/tg/docs.go       |  47 +++++++++
 cmd/tg/enum_flag.go  |  41 ++++----
 cmd/tg/init.go       |  94 ++++++++++-------
 cmd/tg/main.go       |  76 +-------------
 cmd/tg/root.go       |  82 +++++++++++++++
 cmd/tg/send.go       |  74 +++++++++-----
 cmd/tg/upload.go     | 237 ++++++++++++++++++++++--------------------
 go.mod               |   9 +-
 go.sum               |  13 +--
 13 files changed, 746 insertions(+), 340 deletions(-)
 create mode 100644 ROADMAP.md
 create mode 100644 cmd/tg/completion.go
 create mode 100644 cmd/tg/docs.go
 create mode 100644 cmd/tg/root.go

diff --git a/ROADMAP.md b/ROADMAP.md
new file mode 100644
index 0000000..d0bcc87
--- /dev/null
+++ b/ROADMAP.md
@@ -0,0 +1,238 @@
+# `tg` Roadmap — Agent-Automatable Telegram CLI
+
+## Vision
+
+Turn `tg` into a single static binary that an AI agent (or any script) can drive to
+automate everyday Telegram work on a **personal account**: message yourself, list and
+triage chats, mark chats as read, reply, upload/download files, search history, and more.
+
+The goal is a broad capability surface — and strong agent ergonomics — delivered as a
+fast, dependency-free Go binary built on [`gotd/td`](https://github.com/gotd/td), exposed
+as composable subcommands. New capability should land as `tg` subcommands.
+
+## The central gap: user-account auth
+
+`tg` today authenticates **only as a bot** (`Config.BotToken`, `client.Auth().Bot(...)`,
+and `app.Before` hard-rejects a config without a bot token). Bots cannot:
+
+- access **Saved Messages** / "message yourself",
+- list **dialogs** (`messages.getDialogs` is unavailable to bots),
+- read arbitrary chat history or mark dialogs as read the way a user can,
+- see the chat/folder list, contacts, or most account state.
+
+**Every automation use case in the request requires a user session.** So user login is
+Phase 0 and gates everything else. `gotd/td` already supports this: `auth.NewFlow` with a
+code-prompt + 2FA handler, and `qrlogin` for QR-based login.
+
+## Agent-first design principles
+
+These cut across every feature and matter as much as the features themselves:
+
+1. **Structured output.** Global `--output json|text` (default `text` for humans, but
+   agents pass `--output json`). Every command emits a stable, documented JSON object on
+   stdout. No data on stderr; logs/progress go to stderr only.
+2. **Non-interactive by default.** Never block on a TTY prompt in agent mode. Auth codes,
+   confirmations, and 2FA come from flags / env / a pre-established session.
+3. **Stable exit codes.** `0` success, distinct non-zero codes for auth failure, peer not
+   found, flood-wait exceeded, permission denied — so agents can branch on them.
+4. **No decorative output in machine mode.** The upload progress bar and typing-action
+   updates must be suppressed under `--output json`.
+5. **Consistent peer resolution.** One shared `--peer` grammar everywhere: `me`/`self`,
+   `@username`, numeric ID, phone, `t.me/...` link. Cache resolved access-hashes in the
+   session dir (StringSession-style sessions have no entity cache — we must keep our own).
+6. **Idempotency & safety.** Destructive actions (delete history, leave, ban, delete
+   account-level state) require `--yes` in agent mode and are clearly marked read-only vs
+   mutating.
+7. **Schema versioning.** Include `"schema": 1` (or similar) in JSON so agents can adapt.
+8. **Account selection.** Every command accepts a global `--account <label>` (env
+   `TG_ACCOUNT`), defaulting to the configured default account. Reserve and thread this
+   flag from day one even while only one account exists, so adding multi-account later is
+   additive and never changes existing command signatures.
+
+## Phased plan
+
+### Phase 0 — Foundations (prerequisite for everything)
+
+- [x] **Adopt [`spf13/cobra`](https://github.com/spf13/cobra) for the CLI** (replacing the
+      current `urfave/cli/v2`). Do this first — every later command is a cobra subcommand, so
+      migrating after the surface grows is costly. Requirements:
+  - **Rich documentation**: every command sets `Short`, a long-form `Long`, and runnable
+    `Example` blocks; group related commands (`cobra.Group`) so `tg --help` reads as a map of
+    the surface. Generate `man` pages and Markdown docs from the command tree
+    (`spf13/cobra/doc`) and publish them, so help stays in sync with the code.
+  - **Thorough autocomplete**: ship `tg completion bash|zsh|fish|powershell` (cobra's built-in
+    `completion` command). Register `ValidArgsFunction` for dynamic completion of the things
+    agents and humans actually type — `--peer` (cached dialogs/usernames from the peer cache),
+    `--account` labels, `--output` values, enum flags — and mark file-taking flags
+    (`upload`/`download`) with `MarkFlagFilename`. Completions must work without a network
+    round-trip where possible (read from the local session/peer cache).
+  - Use `cobra.Command.RunE` (error-returning) throughout; wire global flags as persistent
+    flags on the root; pair with `spf13/pflag` for GNU-style `--flag`/`-f` parsing.
+- [ ] **QR login (primary)**: `tg login` defaults to QR, following
+      `gotd/td`'s `examples/qrauth.go` + `examples/userbot`. Wiring:
+  - `dispatcher := tg.NewUpdateDispatcher()` and
+    `loggedIn := qrlogin.OnLoginToken(&dispatcher)` — the channel fires on
+    `tg.UpdateLoginToken` when the code is scanned.
+  - `client.QR().Auth(ctx, loggedIn, show)`, where `show` renders the QR to stderr via
+    `github.com/mdp/qrterminal/v3` **and** also prints `token.URL()` (the
+    `tg://login?token=...` link) so it can be opened/rendered elsewhere — agent-friendly.
+  - 2FA fallback: on `SESSION_PASSWORD_NEEDED`, call `client.Auth().Password(ctx, pwd)`
+    (retry on `auth.ErrPasswordInvalid`).
+  - **Requires updates enabled.** Today `app.go` sets `NoUpdates: true` and registers no
+    `UpdateHandler`, so `loggedIn` would never be notified. The login path must register
+    the dispatcher as `UpdateHandler` and not disable updates; make `NoUpdates` and the
+    dispatcher conditional on the command.
+  - UX: scan once (Settings → Devices → Link Desktop Device); the session persists in
+    `session.FileStorage`, so all later agent invocations are headless.
+- [ ] **Phone login (fallback)**: `tg login --phone` using `auth.NewFlow` (code + 2FA), for
+      environments where scanning a QR is inconvenient.
+- [ ] Persist the user session alongside the existing bot session. Extend `Config`/`init`
+      to support a user session path; relax `app.Before` so a bot token is no longer
+      mandatory.
+- [ ] **Auth mode selection**: allow a single config to hold both; commands pick user vs
+      bot session (most new commands are user-only).
+- [ ] **`--output json` plumbing**: a small result-writer used by all commands; move logs
+      and progress to stderr.
+- [ ] **Peer resolver + access-hash cache** in the session directory.
+- [ ] **Proxy support (global)**: a single `--proxy` flag (config + `TG_PROXY` env)
+      accepting a URL, threaded into `telegram.Options.Resolver`:
+  - `socks5://`, `socks4://`, `http(s)://` → `dcs.Plain` with a
+    `golang.org/x/net/proxy` dialer (already in the module graph via `x/net`; no new dep).
+      Honor user:password and remote-DNS.
+  - `tg://proxy?server=&port=&secret=` / MTProxy → native `dcs.MTProxy(addr, secret, …)`,
+    reusing the link + secret (hex/base64url) parsing from
+    `gotd/td`'s `examples/mtproxy-connect`.
+  - Wire it at client construction so every command benefits; per-account overrides come in
+    Phase 7.
+- [ ] **`tg whoami`**: smallest end-to-end user-session command to validate auth.
+
+### Phase 1 — Core agent loop (the explicit asks)
+
+These directly cover "upload files to myself, list chats, mark chats as read, replies".
+
+- [ ] `tg chats list` — list dialogs (paged), with unread counts, pinned/muted/archived
+      flags, last message preview.
+- [ ] `tg messages list <peer>` / `tg history <peer>` — read recent messages.
+- [ ] `tg send <peer> <text>` — already exists; extend to default `me` and JSON output.
+- [ ] `tg reply <peer> <message-id> <text>` — reply to a specific message.
+- [ ] `tg read <peer>` — mark a chat as read.
+- [ ] `tg upload` to `me` / Saved Messages — already exists; ensure `me` peer + JSON +
+      silent progress.
+- [ ] `tg download <peer> <message-id> [--out path]` — download media.
+
+### Phase 2 — Messaging depth
+
+- [ ] `edit`, `delete` (single + bulk), `delete-history`.
+- [ ] `forward` (single + multiple).
+- [ ] `pin` / `unpin` / `unpin-all` / `pinned`.
+- [ ] Reactions: `react` / `unreact` / `reactions`.
+- [ ] Drafts: `draft set` / `drafts` / `draft clear`.
+- [ ] Scheduled messages: `schedule` send / list / delete.
+- [ ] Search: `search <peer> <query>` and `search --global <query>`.
+- [ ] Polls: `poll create`.
+- [ ] Message context / links: `context`, `link`.
+- [ ] Albums, voice, stickers, GIFs.
+
+### Phase 3 — Chats & contacts
+
+- [ ] `chat get` / `chat full`.
+- [ ] `mute` / `unmute` / `archive` / `unarchive`.
+- [ ] `resolve <username>`, `search-public <query>`, `subscribe`.
+- [ ] Contacts: list / search / add / delete / block / unblock / blocked / import / export.
+
+### Phase 4 — Groups & channels admin
+
+- [ ] Create group/channel, invite, leave, participants, admins, banned.
+- [ ] Admin/moderation: promote/demote, ban/unban, permissions, slow mode, admin rights, recent actions.
+- [ ] Edit chat title/photo/about, invite links (export/import/join by link).
+- [ ] Forum topics.
+
+### Phase 5 — Profile & folders
+
+- [ ] Profile: get me, update profile, profile photo set/delete, privacy get/set, user info/photos/status.
+- [ ] Folders / dialog filters: list / get / create / add-chat / remove-chat / delete / reorder.
+
+### Phase 6 — Realtime (high value for agents)
+
+- [ ] `tg watch <peer>` — stream new messages as JSON lines; the agent's input loop.
+- [ ] `tg wait` — block until a new (or settled) incoming message, with timeout.
+- [ ] Backed by `gotd/td` update handlers; `NoUpdates: true` (set in `app.go` today) must
+      become conditional.
+
+### Phase 7 — Multiple concurrent accounts
+
+The `--account` selector (design principle 8) ships from Phase 0, but real multi-account —
+several sessions usable, and **live simultaneously** — lands here: a `label -> client` map,
+an `--account <label>` selector, and a `tg accounts` listing.
+
+- [ ] **Config for N accounts**: named accounts in the config (or env
+      `TG_SESSION_<LABEL>`), each with its own `session.FileStorage` file, peer-cache, and
+      `floodwait.Waiter`. Keep a backward-compatible single "default" account.
+- [ ] **`tg accounts`** — list configured accounts + auth status.
+- [ ] **`tg login --account <label>`** — mint/refresh a session per label (QR or phone).
+- [ ] **Concurrent runtime**: hold a `map[label]*telegram.Client`, each running under its
+      own waiter; a command resolves `--account` to one client. Clients are independent and
+      safe to run in parallel — one flood-wait or reconnect must not stall the others.
+- [ ] **Fan-out where it makes sense**: `--account all` (or repeated `--account`) for
+      read/broadcast commands (e.g. `chats list`, `send`, `watch`) — results keyed by label
+      in JSON. Strictly opt-in; single-account stays the default.
+- [ ] **Realtime across accounts**: Phase 6 `watch`/`wait` can observe multiple accounts
+      concurrently (one dispatcher + update loop per client), merged into one JSON stream.
+- [ ] **Per-account proxy**: per-label override of the global proxy (Phase 0), so each
+      account can route through its own SOCKS5/HTTP/MTProxy.
+
+## Capability groups (reference)
+
+The surface breaks into groups: `accounts`, `chats`, `messages`, `media`, `contacts`,
+`groups`, `profile`, `folders`, `events`. The phases above fold each group in: Phase 1
+covers the daily-driver subset of `chats`/`messages`/`media`; Phase 2 the rest of
+`messages`+`media`; Phase 3 `chats`+`contacts`; Phase 4 `groups`; Phase 5
+`profile`+`folders`; Phase 6 `events`; Phase 7 generalizes the whole surface to multiple
+concurrent accounts (the `accounts` group).
+
+## Technical notes
+
+- **CLI framework:** `spf13/cobra` (+ `spf13/pflag`), replacing `urfave/cli/v2`. Chosen for
+  first-class shell completion (`bash`/`zsh`/`fish`/`powershell` with dynamic
+  `ValidArgsFunction` hooks) and doc generation (`spf13/cobra/doc` → man + Markdown). One
+  `*cobra.Command` per subcommand with `RunE`; global flags are persistent flags on the root;
+  the existing `app`/`Before` wiring moves into `PersistentPreRunE`.
+- **Library:** `gotd/td` (`telegram`, `tg`, `telegram/message`, `telegram/uploader`,
+  `telegram/downloader`, `telegram/query` for dialog/history pagination, `auth`,
+  `auth/qrlogin`, `telegram/peers` for resolution/caching).
+- **QR login** adds one dependency: `github.com/mdp/qrterminal/v3` (terminal QR rendering),
+  matching `gotd/td`'s `examples/qrauth.go`. The QR flow is also a forcing function to
+  introduce an update dispatcher (`tg.NewUpdateDispatcher`) and turn off the current
+  `NoUpdates: true` for commands that need it — which Phase 6 (realtime) needs anyway.
+- **Flood-wait** is already handled via the `floodwait.Waiter` middleware — keep it; add a
+  distinct exit code when retries are exhausted.
+- **Proxy** is configured through `telegram.Options.Resolver` (`dcs.Resolver`), not a global
+  dialer: `dcs.Plain{Dial: <x/net/proxy dialer>.DialContext}` for SOCKS/HTTP, or
+  `dcs.MTProxy(addr, secret, …)` for MTProxy. See `gotd/td`'s `telegram/dcs/example_test.go`
+  and `examples/mtproxy-connect`. Each account builds its own resolver, so per-account
+  proxies fall out naturally in Phase 7.
+- **Sessions:** keep using `session.FileStorage` (per-account file); the user session lives
+  beside the existing bot session. Consider an export-to-string command for portability.
+- **Multi-account isolation (Phase 7):** one `telegram.Client` per label, each with its own
+  session file, peer-cache, and `floodwait.Waiter` — no shared mutable state between
+  accounts, so they run concurrently without one blocking another. The runtime owns a
+  `map[label]*telegram.Client`; commands select by `--account`. Single-account remains the
+  default and costs nothing.
+- **Pagination:** dialog and history listing must page (`page`/`page_size`); use
+  `query.GetDialogs`/`query.Messages` iterators.
+- **Output stability:** define Go structs for each command's JSON result; never leak raw
+  MTProto types into the contract.
+
+## Open questions
+
+1. **Login UX for agents:** interactive `tg login` once to mint a session, then agents reuse
+   it headless — or support a fully headless code-delivery path? (Recommend: interactive
+   one-time login, headless reuse.)
+2. **Keep bot support?** Recommend yes — some flows (channel posting) are fine as a bot — but
+   make user the default for the agent commands.
+3. **Scope of v1:** propose shipping Phases 0–1 as the first milestone, since they cover the
+   exact asks (message self, list chats, mark read, reply, upload).
+4. **Multi-account timing:** ship single-account first but reserve `--account` from Phase 0,
+   so full concurrent multi-account (Phase 7) is purely additive. Should fan-out
+   (`--account all`) be in scope, or only explicit single-label selection?
+</content>
diff --git a/cmd/tg/app.go b/cmd/tg/app.go
index 869235b..57343db 100644
--- a/cmd/tg/app.go
+++ b/cmd/tg/app.go
@@ -3,14 +3,13 @@ package main
 import (
 	"context"
 	"crypto/md5" // #nosec
-	"errors"
 	"fmt"
 	"os"
 	"path/filepath"
 
-	"github.com/urfave/cli/v2"
+	"github.com/go-faster/errors"
+	"github.com/spf13/cobra"
 	"go.uber.org/zap"
-	"golang.org/x/xerrors"
 	"gopkg.in/yaml.v3"
 
 	"github.com/gotd/contrib/middleware/floodwait"
@@ -23,7 +22,20 @@ import (
 	"github.com/gotd/cli/internal/pretty"
 )
 
+// Config is the persisted CLI configuration.
+type Config struct {
+	AppID    int    `yaml:"app_id"`
+	AppHash  string `yaml:"app_hash"`
+	BotToken string `yaml:"bot_token"`
+}
+
+// app holds shared state and the values of the global (persistent) flags.
 type app struct {
+	// Global flags, bound to the root command's persistent flags.
+	configPath   string
+	debugInvoker bool
+	testServer   bool
+
 	cfg    Config
 	log    *zap.Logger
 	waiter *floodwait.Waiter
@@ -56,22 +68,22 @@ func newApp() *app {
 	}
 }
 
-func (p *app) run(ctx context.Context, f func(ctx context.Context, api *tg.Client) error) error {
-	if p.debug {
-		p.opts.Middlewares = append(p.opts.Middlewares, pretty.Middleware())
+func (a *app) run(ctx context.Context, f func(ctx context.Context, api *tg.Client) error) error {
+	if a.debug {
+		a.opts.Middlewares = append(a.opts.Middlewares, pretty.Middleware())
 	}
 
-	client := telegram.NewClient(p.cfg.AppID, p.cfg.AppHash, p.opts)
+	client := telegram.NewClient(a.cfg.AppID, a.cfg.AppHash, a.opts)
 
-	if err := p.waiter.Run(ctx, func(ctx context.Context) error {
+	if err := a.waiter.Run(ctx, func(ctx context.Context) error {
 		return client.Run(ctx, func(ctx context.Context) error {
 			s, err := client.Auth().Status(ctx)
 			if err != nil {
-				return xerrors.Errorf("check auth status: %w", err)
+				return errors.Wrap(err, "check auth status")
 			}
 			if !s.Authorized {
-				if _, err := client.Auth().Bot(ctx, p.cfg.BotToken); err != nil {
-					return xerrors.Errorf("check auth status: %w", err)
+				if _, err := client.Auth().Bot(ctx, a.cfg.BotToken); err != nil {
+					return errors.Wrap(err, "check auth status")
 				}
 			}
 			return f(ctx, tg.NewClient(client))
@@ -83,42 +95,54 @@ func (p *app) run(ctx context.Context, f func(ctx context.Context, api *tg.Clien
 	return nil
 }
 
-func (p *app) Before(c *cli.Context) error {
-	// HACK for init.
-	if c.Command.Name == "init" {
+// skipConfigCommands are commands that must run without a loaded config/session.
+func skipConfig(cmd *cobra.Command) bool {
+	for c := cmd; c != nil; c = c.Parent() {
+		switch c.Name() {
+		case "init", "docs", "completion", "help",
+			cobra.ShellCompRequestCmd, cobra.ShellCompNoDescRequestCmd:
+			return true
+		}
+	}
+	return false
+}
+
+// before loads config and prepares client options. It is wired as the root
+// command's PersistentPreRunE, so it runs before every subcommand.
+func (a *app) before(cmd *cobra.Command) error {
+	if skipConfig(cmd) {
 		return nil
 	}
 
-	cfgPath := c.String("config")
-	if cfgPath == "" {
-		return xerrors.Errorf("no config path provided")
+	if a.configPath == "" {
+		return errors.New("no config path provided")
 	}
 
-	data, err := os.ReadFile(cfgPath) // #nosec G304 // path provided via flag
+	data, err := os.ReadFile(a.configPath) // #nosec G304 // path provided via flag
 	if err != nil {
 		return err
 	}
 
-	if err := yaml.Unmarshal(data, &p.cfg); err != nil {
+	if err := yaml.Unmarshal(data, &a.cfg); err != nil {
 		return err
 	}
 
-	if p.cfg.BotToken == "" {
-		return xerrors.Errorf("no bot token provided")
+	if a.cfg.BotToken == "" {
+		return errors.New("no bot token provided")
 	}
 
 	// Default to same directory (near with config).
 	// Probably there is better way to handle this.
-	sessionName := fmt.Sprintf("gotd.session.%x.json", md5.Sum([]byte(p.cfg.BotToken))) // #nosec
-	p.opts.Logger = logzap.New(p.log.Named("tg"))
-	p.opts.SessionStorage = &session.FileStorage{
-		Path: filepath.Join(filepath.Dir(cfgPath), sessionName),
+	sessionName := fmt.Sprintf("gotd.session.%x.json", md5.Sum([]byte(a.cfg.BotToken))) // #nosec
+	a.opts.Logger = logzap.New(a.log.Named("tg"))
+	a.opts.SessionStorage = &session.FileStorage{
+		Path: filepath.Join(filepath.Dir(a.configPath), sessionName),
 	}
-	if c.Bool("test") {
-		p.opts.DCList = dcs.Test()
+	if a.testServer {
+		a.opts.DCList = dcs.Test()
 	}
-	if c.Bool("debug-invoker") {
-		p.debug = true
+	if a.debugInvoker {
+		a.debug = true
 	}
 
 	return nil
diff --git a/cmd/tg/common.go b/cmd/tg/common.go
index 1c96700..1fb067e 100644
--- a/cmd/tg/common.go
+++ b/cmd/tg/common.go
@@ -3,58 +3,54 @@ package main
 import (
 	"time"
 
-	"github.com/urfave/cli/v2"
+	"github.com/spf13/pflag"
 
 	"github.com/gotd/td/telegram/message"
 	"github.com/gotd/td/telegram/message/html"
 	"github.com/gotd/td/telegram/message/styling"
 )
 
-// messageFlags returns common flags for send and upload.
-func messageFlags() []cli.Flag {
-	return []cli.Flag{
-		&cli.BoolFlag{
-			Name:  "html",
-			Usage: "use HTML styling",
-		},
-		&cli.BoolFlag{
-			Name:  "silent",
-			Usage: "send this message silently (no notifications for the receivers)",
-		},
-		&cli.BoolFlag{
-			Name:  "nowebpage",
-			Usage: "disable generation of the webpage preview",
-		},
-		&cli.DurationFlag{
-			Name:  "schedule",
-			Usage: "scheduled message date for scheduled messages",
-		},
-	}
+// messageOptions holds flags shared by the send and upload commands.
+type messageOptions struct {
+	html      bool
+	silent    bool
+	noWebpage bool
+	schedule  time.Duration
+}
+
+// register binds the shared message flags onto the given flag set.
+func (o *messageOptions) register(fs *pflag.FlagSet) {
+	fs.BoolVar(&o.html, "html", false, "use HTML styling")
+	fs.BoolVar(&o.silent, "silent", false,
+		"send this message silently (no notifications for the receivers)")
+	fs.BoolVar(&o.noWebpage, "nowebpage", false,
+		"disable generation of the webpage preview")
+	fs.DurationVar(&o.schedule, "schedule", 0,
+		"schedule the message to be sent after this delay")
 }
 
-func applyMessageFlags(
-	c *cli.Context,
+// apply mutates the request builder according to the flags and returns the
+// builder together with the styled text options for the message body.
+func (o *messageOptions) apply(
 	r *message.RequestBuilder,
 	msg string,
 ) (*message.Builder, []styling.StyledTextOption) {
-	p := &r.Builder
+	b := &r.Builder
 
-	if c.Bool("silent") {
-		p = p.Silent()
+	if o.silent {
+		b = b.Silent()
 	}
-
-	if c.Bool("nowebpage") {
-		p = p.NoWebpage()
+	if o.noWebpage {
+		b = b.NoWebpage()
 	}
-
-	if d := c.Duration("schedule"); c.IsSet("schedule") {
-		p = p.Schedule(time.Now().Add(d))
+	if o.schedule > 0 {
+		b = b.Schedule(time.Now().Add(o.schedule))
 	}
 
 	option := styling.Plain(msg)
-	if c.Bool("html") {
+	if o.html {
 		option = html.String(nil, msg)
 	}
 
-	return p, []styling.StyledTextOption{option}
+	return b, []styling.StyledTextOption{option}
 }
diff --git a/cmd/tg/completion.go b/cmd/tg/completion.go
new file mode 100644
index 0000000..b7578f5
--- /dev/null
+++ b/cmd/tg/completion.go
@@ -0,0 +1,29 @@
+package main
+
+import (
+	"github.com/spf13/cobra"
+)
+
+// registerPeerCompletion wires dynamic shell completion for a peer-taking flag.
+//
+// TODO(Phase 0): read resolved dialogs/usernames from the local peer cache so
+// completion reflects the user's actual chats without a network round-trip. For
+// now it offers the always-valid self aliases.
+func registerPeerCompletion(cmd *cobra.Command, flag string) {
+	_ = cmd.RegisterFlagCompletionFunc(flag,
+		func(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
+			return []string{
+					"me\tSaved Messages (yourself)",
+					"self\tSaved Messages (yourself)",
+				},
+				cobra.ShellCompDirectiveNoFileComp
+		},
+	)
+}
+
+// registerEnumCompletion offers the allowed values of an enum flag.
+func registerEnumCompletion(cmd *cobra.Command, flag string, allowed []string) {
+	_ = cmd.RegisterFlagCompletionFunc(flag,
+		cobra.FixedCompletions(allowed, cobra.ShellCompDirectiveNoFileComp),
+	)
+}
diff --git a/cmd/tg/docs.go b/cmd/tg/docs.go
new file mode 100644
index 0000000..6509acb
--- /dev/null
+++ b/cmd/tg/docs.go
@@ -0,0 +1,47 @@
+package main
+
+import (
+	"os"
+
+	"github.com/go-faster/errors"
+	"github.com/spf13/cobra"
+	"github.com/spf13/cobra/doc"
+)
+
+// newDocsCmd generates documentation for the whole command tree. It is hidden
+// because it is a maintenance/release tool, not an end-user command.
+func newDocsCmd(root *cobra.Command) *cobra.Command {
+	var (
+		dir    string
+		format string
+	)
+
+	cmd := &cobra.Command{
+		Use:   "docs",
+		Short: "Generate command-tree documentation (Markdown or man pages)",
+		Long: `Generate reference documentation for every command from the command tree,
+so the published docs always match the code.`,
+		Hidden: true,
+		Args:   cobra.NoArgs,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			if err := os.MkdirAll(dir, 0o750); err != nil {
+				return err
+			}
+			switch format {
+			case "markdown", "md":
+				return doc.GenMarkdownTree(root, dir)
+			case "man":
+				return doc.GenManTree(root, &doc.GenManHeader{Title: "TG", Section: "1"}, dir)
+			default:
+				return errors.Errorf("unknown format %q (want markdown or man)", format)
+			}
+		},
+	}
+
+	fs := cmd.Flags()
+	fs.StringVar(&dir, "dir", "docs", "output directory")
+	fs.StringVar(&format, "format", "markdown", "output format: markdown or man")
+	registerEnumCompletion(cmd, "format", []string{"markdown", "man"})
+
+	return cmd
+}
diff --git a/cmd/tg/enum_flag.go b/cmd/tg/enum_flag.go
index 7d4ce6f..5f08c09 100644
--- a/cmd/tg/enum_flag.go
+++ b/cmd/tg/enum_flag.go
@@ -1,38 +1,35 @@
 package main
 
 import (
-	"flag"
 	"strings"
 
-	"github.com/urfave/cli/v2"
-	"golang.org/x/xerrors"
+	"github.com/go-faster/errors"
 )
 
-// EnumFlag is a simple wrapper for StringFlag to make a string enum flag.
-type EnumFlag struct {
-	cli.StringFlag
-	Allowed []string
+// enumValue is a pflag.Value that only accepts one of a fixed set of strings.
+// It powers both validation and shell completion for enum-style flags.
+type enumValue struct {
+	value   string
+	allowed []string
 }
 
-// GetUsage returns the usage string for the flag
-func (e *EnumFlag) GetUsage() string {
-	return e.Usage + "(" + "allowed: " + strings.Join(e.Allowed, ", ") + ")"
+func newEnumValue(def string, allowed ...string) *enumValue {
+	return &enumValue{value: def, allowed: allowed}
 }
 
-// Apply implements cli.Flag.
-func (e *EnumFlag) Apply(set *flag.FlagSet) error {
-	if err := e.StringFlag.Apply(set); err != nil {
-		return err
-	}
-
-	if !e.HasBeenSet {
-		return nil
-	}
+// String implements pflag.Value.
+func (e *enumValue) String() string { return e.value }
 
-	for i := range e.Allowed {
-		if e.Value == e.Allowed[i] {
+// Set implements pflag.Value.
+func (e *enumValue) Set(v string) error {
+	for _, a := range e.allowed {
+		if v == a {
+			e.value = v
 			return nil
 		}
 	}
-	return xerrors.Errorf("allowed values are %s", strings.Join(e.Allowed, ", "))
+	return errors.Errorf("must be one of: %s", strings.Join(e.allowed, ", "))
 }
+
+// Type implements pflag.Value.
+func (e *enumValue) Type() string { return "string" }
diff --git a/cmd/tg/init.go b/cmd/tg/init.go
index 1cc3aa2..4be08c3 100644
--- a/cmd/tg/init.go
+++ b/cmd/tg/init.go
@@ -5,46 +5,24 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"strconv"
 
-	"github.com/urfave/cli/v2"
-	"golang.org/x/xerrors"
+	"github.com/go-faster/errors"
+	"github.com/spf13/cobra"
 	"gopkg.in/yaml.v3"
 )
 
-func initFlags() []cli.Flag {
-	return []cli.Flag{
-		&cli.IntFlag{
-			Name:     "app-id",
-			Required: true,
-			Usage:    "telegram app ID",
-			EnvVars:  []string{"APP_ID"},
-		},
-		&cli.StringFlag{
-			Name:     "app-hash",
-			Required: true,
-			Usage:    "telegram app hash",
-			EnvVars:  []string{"APP_HASH"},
-		},
-		&cli.StringFlag{
-			Name:     "token",
-			Required: true,
-			Usage:    "telegram bot token",
-			EnvVars:  []string{"BOT_TOKEN"},
-		},
-	}
-}
-
 func writeConfig(cfgPath string, cfg Config) error {
 	buf := new(bytes.Buffer)
 	e := yaml.NewEncoder(buf)
 	e.SetIndent(2)
 
 	if err := e.Encode(cfg); err != nil {
-		return xerrors.Errorf("encode: %w", err)
+		return errors.Wrap(err, "encode")
 	}
 
 	if _, err := os.Stat(cfgPath); err == nil {
-		return xerrors.Errorf("file %s exist", cfgPath)
+		return errors.Errorf("file %s exist", cfgPath)
 	}
 
 	if err := os.MkdirAll(filepath.Dir(cfgPath), 0o700); err != nil {
@@ -52,24 +30,62 @@ func writeConfig(cfgPath string, cfg Config) error {
 	}
 
 	if err := os.WriteFile(cfgPath, buf.Bytes(), 0o600); err != nil {
-		return xerrors.Errorf("write: %w", err)
+		return errors.Wrap(err, "write")
 	}
 
 	return nil
 }
 
-func initCmd(c *cli.Context) error {
-	sampleCfg := Config{
-		AppID:    c.Int("app-id"),
-		AppHash:  c.String("app-hash"),
-		BotToken: c.String("token"),
-	}
+// envInt returns the integer value of the environment variable, or 0.
+func envInt(key string) int {
+	v, _ := strconv.Atoi(os.Getenv(key))
+	return v
+}
+
+func newInitCmd(a *app) *cobra.Command {
+	var (
+		appID   int
+		appHash string
+		token   string
+	)
+
+	cmd := &cobra.Command{
+		Use:     "init",
+		Short:   "Create the config file",
+		GroupID: groupAuth,
+		Long: `Create the config file at the path given by the global --config flag.
+
+Each value may instead be supplied via environment variable: APP_ID, APP_HASH,
+and BOT_TOKEN.`,
+		Example: `  tg init --app-id 10 --app-hash abcd --token <bot-token>`,
+		Args:    cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			if a.configPath == "" {
+				return errors.New("no config path provided")
+			}
+			if appID == 0 || appHash == "" || token == "" {
+				return errors.New("app-id, app-hash and token are required " +
+					"(via flags or APP_ID/APP_HASH/BOT_TOKEN env)")
+			}
 
-	cfgPath := c.String("config")
-	if cfgPath == "" {
-		return xerrors.Errorf("no config path provided")
+			cfg := Config{
+				AppID:    appID,
+				AppHash:  appHash,
+				BotToken: token,
+			}
+			if err := writeConfig(a.configPath, cfg); err != nil {
+				return err
+			}
+
+			_, err := fmt.Fprintln(cmd.OutOrStdout(), "Wrote config to", a.configPath)
+			return err
+		},
 	}
 
-	defer fmt.Println("Wrote config to", cfgPath)
-	return writeConfig(cfgPath, sampleCfg)
+	fs := cmd.Flags()
+	fs.IntVar(&appID, "app-id", envInt("APP_ID"), "telegram app ID")
+	fs.StringVar(&appHash, "app-hash", os.Getenv("APP_HASH"), "telegram app hash")
+	fs.StringVar(&token, "token", os.Getenv("BOT_TOKEN"), "telegram bot token")
+
+	return cmd
 }
diff --git a/cmd/tg/main.go b/cmd/tg/main.go
index 381a0dc..605c8f3 100644
--- a/cmd/tg/main.go
+++ b/cmd/tg/main.go
@@ -5,86 +5,14 @@ import (
 	"fmt"
 	"os"
 	"os/signal"
-	"path/filepath"
-
-	"github.com/urfave/cli/v2"
 )
 
-type Config struct {
-	AppID    int    `yaml:"app_id"`
-	AppHash  string `yaml:"app_hash"`
-	BotToken string `yaml:"bot_token"`
-}
-
-func defaultConfigPath() string {
-	dir, err := os.UserConfigDir()
-	if err != nil {
-		return ""
-	}
-
-	return filepath.Join(dir, "gotd", "gotd.cli.yaml")
-}
-
 func main() {
-	p := newApp()
-	app := &cli.App{
-		Name:  "tg",
-		Usage: "Telegram CLI",
-		Flags: []cli.Flag{
-			&cli.StringFlag{
-				Name:    "config",
-				Aliases: []string{"c"},
-				Value:   defaultConfigPath(),
-				Usage:   "config to use",
-			},
-			&cli.BoolFlag{
-				Name:  "debug-invoker",
-				Usage: "use pretty-printing debug invoker",
-			},
-			&cli.BoolFlag{
-				Name:    "test",
-				Aliases: []string{"staging"},
-				Usage:   "connect to telegram test server",
-			},
-		},
-
-		Commands: []*cli.Command{
-			{
-				Name:  "init",
-				Usage: "Creates config file",
-				Description: `Command init creates config file at the given path.
-Example:
-	tg init --app-id 10 --app-hash abcd --token token
-`,
-				Flags:  initFlags(),
-				Action: initCmd,
-			},
-			{
-				Name:      "send",
-				Usage:     "Sends message to peer",
-				ArgsUsage: "[message]",
-				Flags:     p.sendFlags(),
-				Action:    p.sendCmd,
-			},
-			{
-				Name:      "upload",
-				Aliases:   []string{"up"},
-				Usage:     "Uploads file to peer",
-				ArgsUsage: "[path]",
-				Flags:     p.uploadFlags(),
-				Action:    p.uploadCmd,
-			},
-		},
-	}
-	for _, cmd := range app.Commands {
-		cmd.Before = p.Before
-	}
-
 	ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt)
 	defer cancel()
 
-	if err := app.RunContext(ctx, os.Args); err != nil {
-		fmt.Printf("%+v\n", err)
+	if err := newRootCmd().ExecuteContext(ctx); err != nil {
+		fmt.Fprintf(os.Stderr, "%+v\n", err)
 		os.Exit(1)
 	}
 }
diff --git a/cmd/tg/root.go b/cmd/tg/root.go
new file mode 100644
index 0000000..d0afefe
--- /dev/null
+++ b/cmd/tg/root.go
@@ -0,0 +1,82 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+)
+
+// Command groups shown in `tg --help`.
+const (
+	groupAuth      = "auth"
+	groupMessaging = "messaging"
+)
+
+func defaultConfigPath() string {
+	dir, err := os.UserConfigDir()
+	if err != nil {
+		return ""
+	}
+
+	return filepath.Join(dir, "gotd", "gotd.cli.yaml")
+}
+
+// normalizeFlag maps deprecated/alternate flag names to their canonical form so
+// older invocations keep working after the cobra migration.
+func normalizeFlag(_ *pflag.FlagSet, name string) pflag.NormalizedName {
+	switch name {
+	case "staging": // --staging -> --test
+		name = "test"
+	case "target": // --target -> --peer
+		name = "peer"
+	case "msg": // --msg -> --message
+		name = "message"
+	case "as": // --as -> --type
+		name = "type"
+	}
+	return pflag.NormalizedName(name)
+}
+
+func newRootCmd() *cobra.Command {
+	a := newApp()
+
+	root := &cobra.Command{
+		Use:   "tg",
+		Short: "Telegram CLI for humans and agents",
+		Long: `tg is a single static binary for driving a Telegram account from the
+command line or an AI agent: send messages, upload and download files, and more.
+
+Run "tg init" once to write a config, then use the subcommands. Global flags
+below apply to every command.`,
+		// We print errors ourselves in main; don't let cobra dump usage on every
+		// runtime error (only on genuine flag/usage mistakes).
+		SilenceUsage:  true,
+		SilenceErrors: true,
+		PersistentPreRunE: func(cmd *cobra.Command, _ []string) error {
+			return a.before(cmd)
+		},
+	}
+
+	root.SetGlobalNormalizationFunc(normalizeFlag)
+
+	pf := root.PersistentFlags()
+	pf.StringVarP(&a.configPath, "config", "c", defaultConfigPath(), "config file to use")
+	pf.BoolVar(&a.debugInvoker, "debug-invoker", false, "use pretty-printing debug invoker")
+	pf.BoolVar(&a.testServer, "test", false, "connect to the telegram test server")
+
+	root.AddGroup(
+		&cobra.Group{ID: groupAuth, Title: "Authentication & setup:"},
+		&cobra.Group{ID: groupMessaging, Title: "Messaging:"},
+	)
+
+	root.AddCommand(
+		newInitCmd(a),
+		a.newSendCmd(),
+		a.newUploadCmd(),
+	)
+	root.AddCommand(newDocsCmd(root))
+
+	return root
+}
diff --git a/cmd/tg/send.go b/cmd/tg/send.go
index 8e6edea..f2f7eca 100644
--- a/cmd/tg/send.go
+++ b/cmd/tg/send.go
@@ -3,37 +3,63 @@ package main
 import (
 	"context"
 
-	"github.com/urfave/cli/v2"
-	"golang.org/x/xerrors"
+	"github.com/go-faster/errors"
+	"github.com/spf13/cobra"
 
 	"github.com/gotd/td/telegram/message"
 	"github.com/gotd/td/tg"
 )
 
-func (p *app) sendFlags() []cli.Flag {
-	return append([]cli.Flag{
-		&cli.StringFlag{
-			Name:    "peer",
-			Aliases: []string{"p", "target"},
-			Usage:   "peer to write (e.g. channel name or username, phone number or deep link)",
-		},
-	}, messageFlags()...)
-}
+func (a *app) newSendCmd() *cobra.Command {
+	var (
+		peer string
+		msg  messageOptions
+	)
+
+	cmd := &cobra.Command{
+		Use:     "send [flags] [text]",
+		Short:   "Send a message to a peer",
+		GroupID: groupMessaging,
+		Long: `Send a text message. With no --peer, the message goes to your own
+Saved Messages, which is handy for notes and agent self-messaging.`,
+		Example: `  # Message yourself (Saved Messages)
+  tg send "hello"
+
+  # Message a channel or user
+  tg send --peer @durov "hi there"
 
-func (p *app) sendCmd(c *cli.Context) error {
-	return p.run(c.Context, func(ctx context.Context, api *tg.Client) error {
-		sender := message.NewSender(api)
+  # HTML formatting, sent silently
+  tg send --peer @durov --html --silent "<b>bold</b>"`,
+		Args: cobra.MaximumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			var text string
+			if len(args) > 0 {
+				text = args[0]
+			}
 
-		builder := sender.Self()
-		if targetDomain := c.String("peer"); targetDomain != "" {
-			builder = sender.Resolve(targetDomain)
-		}
+			return a.run(cmd.Context(), func(ctx context.Context, api *tg.Client) error {
+				sender := message.NewSender(api)
+
+				builder := sender.Self()
+				if peer != "" {
+					builder = sender.Resolve(peer)
+				}
+
+				b, options := msg.apply(builder, text)
+				if _, err := b.StyledText(ctx, options...); err != nil {
+					return errors.Wrap(err, "send")
+				}
+
+				return nil
+			})
+		},
+	}
 
-		b, options := applyMessageFlags(c, builder, c.Args().First())
-		if _, err := b.StyledText(ctx, options...); err != nil {
-			return xerrors.Errorf("send: %w", err)
-		}
+	fs := cmd.Flags()
+	fs.StringVarP(&peer, "peer", "p", "",
+		"peer to write (channel name or username, phone number or deep link); default: yourself")
+	msg.register(fs)
+	registerPeerCompletion(cmd, "peer")
 
-		return nil
-	})
+	return cmd
 }
diff --git a/cmd/tg/upload.go b/cmd/tg/upload.go
index 16b2c17..1c2e202 100644
--- a/cmd/tg/upload.go
+++ b/cmd/tg/upload.go
@@ -2,7 +2,6 @@ package main
 
 import (
 	"context"
-	"errors"
 	"io"
 	"io/fs"
 	"os"
@@ -11,11 +10,11 @@ import (
 	"time"
 
 	"github.com/gabriel-vasile/mimetype"
+	"github.com/go-faster/errors"
 	"github.com/schollz/progressbar/v3"
-	"github.com/urfave/cli/v2"
+	"github.com/spf13/cobra"
 	"go.uber.org/zap"
 	"golang.org/x/sync/errgroup"
-	"golang.org/x/xerrors"
 
 	"github.com/gotd/td/clock"
 	"github.com/gotd/td/telegram/message"
@@ -24,71 +23,48 @@ import (
 	"github.com/gotd/td/tg"
 )
 
-func (p *app) uploadFlags() []cli.Flag {
-	return append([]cli.Flag{
-		&cli.StringFlag{
-			Name:    "peer",
-			Aliases: []string{"p", "target"},
-			Usage:   "peer to write (channel name, username, phone number or deep link)",
-		},
-		&cli.StringFlag{
-			Name:    "message",
-			Aliases: []string{"m", "msg"},
-			Usage:   "text message to send with file",
-		},
-		&cli.StringFlag{
-			Name:        "filename",
-			Usage:       "value of filename attribute (not set if empty)",
-			DefaultText: "uses name from given path",
-		},
-		&EnumFlag{
-			StringFlag: cli.StringFlag{
-				Name:        "type",
-				Aliases:     []string{"as"},
-				Usage:       "type of uploaded document",
-				DefaultText: "uses MIME type to detect",
-			},
-			Allowed: []string{"file", "video", "audio", "voice", "gif", "sticker"},
-		},
-		&cli.IntFlag{
-			Name:    "threads",
-			Aliases: []string{"j"},
-			Value:   1,
-			Usage:   "concurrency limit",
-		},
-	}, messageFlags()...)
+// uploadFlags are the parsed flag values for the upload command.
+type uploadFlags struct {
+	peer     string
+	message  string
+	filename string
+	docType  *enumValue
+	threads  int
+	msg      messageOptions
+}
+
+// documentTypes are the allowed values of the --type flag.
+func documentTypes() []string {
+	return []string{"file", "video", "audio", "voice", "gif", "sticker"}
 }
 
 func detectMIME(f io.ReadSeeker) (*mimetype.MIME, error) {
 	mime, err := mimetype.DetectReader(f)
 	if err != nil {
-		return nil, xerrors.Errorf("detect MIME: %w", err)
+		return nil, errors.Wrap(err, "detect MIME")
 	}
 
 	if _, err := f.Seek(0, io.SeekStart); err != nil {
-		return nil, xerrors.Errorf("seek to start: %w", err)
+		return nil, errors.Wrap(err, "seek to start")
 	}
 
 	return mime, nil
 }
 
 func prepareFile(
-	c *cli.Context,
+	uf *uploadFlags,
 	fileInput tg.InputFileClass,
 	option []styling.StyledTextOption,
 	fileName, mime string,
 ) message.MediaOption {
 	file := message.UploadedDocument(fileInput, option...)
-	if c.IsSet("filename") {
-		if userFileName := c.String("filename"); userFileName != "" {
-			file = file.Filename(userFileName)
-		}
+	if uf.filename != "" {
+		file = file.Filename(uf.filename)
 	} else {
 		file = file.Filename(fileName)
 	}
 
-	if c.IsSet("type") {
-		v := c.String("type")
+	if v := uf.docType.value; v != "" {
 		switch v {
 		case "file":
 			return file.ForceFile(true).MIME(mime)
@@ -121,17 +97,17 @@ func prepareFile(
 	}
 }
 
-func (p *app) updateStatus(
+func (a *app) updateStatus(
 	ctx context.Context,
 	done chan struct{},
 	builder *message.RequestBuilder,
 	bar *progressbar.ProgressBar,
 ) error {
 	sendProgress := func() {
-		a := builder.TypingAction()
+		act := builder.TypingAction()
 		percent := int(bar.State().CurrentPercent * 100)
-		if err := a.UploadDocument(ctx, percent); err != nil && !errors.Is(err, context.Canceled) {
-			p.log.Error("Action failed", zap.Error(err))
+		if err := act.UploadDocument(ctx, percent); err != nil && !errors.Is(err, context.Canceled) {
+			a.log.Error("Action failed", zap.Error(err))
 		}
 	}
 
@@ -152,74 +128,119 @@ func (p *app) updateStatus(
 	}
 }
 
-func (p *app) uploadCmd(c *cli.Context) error {
-	return p.run(c.Context, func(ctx context.Context, api *tg.Client) error {
-		arg := c.Args().First()
-		if arg == "" {
-			return errors.New("no file name provided")
-		}
+func (a *app) uploadOne(
+	ctx context.Context,
+	uf *uploadFlags,
+	upld *uploader.Uploader,
+	builder *message.RequestBuilder,
+	path string,
+	info fs.FileInfo,
+) error {
+	f, err := os.Open(filepath.Clean(path)) // #nosec G304 // path comes from user-provided upload target
+	if err != nil {
+		return errors.Wrapf(err, "open %q", path)
+	}
+	defer func() {
+		_ = f.Close()
+	}()
+
+	m, err := detectMIME(f)
+	if err != nil {
+		return err
+	}
+
+	fileName := filepath.Base(path)
+	bar := progressbar.DefaultBytes(info.Size(), "upload "+fileName)
+
+	uploadFileName := fileName
+	if uf.filename != "" {
+		uploadFileName = uf.filename
+	}
+	upload := uploader.NewUpload(uploadFileName, io.TeeReader(f, bar), info.Size())
 
-		upld := uploader.NewUploader(api).
-			WithThreads(c.Int("threads")).
-			WithPartSize(uploader.MaximumPartSize)
-		sender := message.NewSender(api).WithUploader(upld)
+	g, ctx := errgroup.WithContext(ctx)
+	done := make(chan struct{})
+	g.Go(func() error {
+		return a.updateStatus(ctx, done, builder, bar)
+	})
+
+	g.Go(func() error {
+		defer close(done)
 
-		builder := sender.Self()
-		if targetDomain := c.String("peer"); targetDomain != "" {
-			builder = sender.Resolve(targetDomain)
+		fileInput, err := upld.Upload(ctx, upload)
+		if err != nil {
+			return errors.Wrapf(err, "upload %q", path)
 		}
 
-		return filepath.Walk(arg, func(path string, info fs.FileInfo, err error) error {
-			// Stop if got error, skip if current file is directory.
-			if info.IsDir() || err != nil {
-				return err
-			}
-
-			f, err := os.Open(filepath.Clean(path)) // #nosec G122 // path comes from user-provided upload target
-			if err != nil {
-				return xerrors.Errorf("open %q: %w", path, err)
-			}
-			defer func() {
-				_ = f.Close()
-			}()
-
-			m, err := detectMIME(f)
-			if err != nil {
-				return err
-			}
-
-			fileName := filepath.Base(path)
-			bar := progressbar.DefaultBytes(info.Size(), "upload "+fileName)
-
-			uploadFileName := fileName
-			if f := c.String("filename"); f != "" {
-				uploadFileName = c.String("filename")
-			}
-			upload := uploader.NewUpload(uploadFileName, io.TeeReader(f, bar), info.Size())
-
-			g, ctx := errgroup.WithContext(ctx)
-			done := make(chan struct{})
-			g.Go(func() error {
-				return p.updateStatus(ctx, done, builder, bar)
-			})
+		b, options := uf.msg.apply(builder, uf.message)
+		if _, err := b.Media(ctx, prepareFile(uf, fileInput, options, fileName, m.String())); err != nil {
+			return errors.Wrapf(err, "send %q", path)
+		}
 
-			g.Go(func() error {
-				defer close(done)
+		return nil
+	})
 
-				fileInput, err := upld.Upload(ctx, upload)
-				if err != nil {
-					return xerrors.Errorf("upload %q: %w", path, err)
-				}
+	return g.Wait()
+}
 
-				b, options := applyMessageFlags(c, builder, c.String("message"))
-				if _, err := b.Media(ctx, prepareFile(c, fileInput, options, fileName, m.String())); err != nil {
-					return xerrors.Errorf("send %q: %w", path, err)
+func (a *app) newUploadCmd() *cobra.Command {
+	uf := &uploadFlags{docType: newEnumValue("", documentTypes()...)}
+
+	cmd := &cobra.Command{
+		Use:     "upload [flags] <path>",
+		Aliases: []string{"up"},
+		Short:   "Upload a file (or directory of files) to a peer",
+		GroupID: groupMessaging,
+		Long: `Upload a file to a peer. If <path> is a directory, every file under it is
+uploaded. With no --peer, files go to your own Saved Messages.
+
+The document type is detected from the file's MIME type unless --type is set.`,
+		Example: `  # Upload a file to Saved Messages
+  tg upload ./report.pdf
+
+  # Upload as a video to a chat
+  tg upload --peer @me --type video clip.mp4
+
+  # Upload with a caption
+  tg upload --peer @durov --message "here you go" photo.jpg`,
+		Args: cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			arg := args[0]
+
+			return a.run(cmd.Context(), func(ctx context.Context, api *tg.Client) error {
+				upld := uploader.NewUploader(api).
+					WithThreads(uf.threads).
+					WithPartSize(uploader.MaximumPartSize)
+				sender := message.NewSender(api).WithUploader(upld)
+
+				builder := sender.Self()
+				if uf.peer != "" {
+					builder = sender.Resolve(uf.peer)
 				}
 
-				return nil
+				return filepath.Walk(arg, func(path string, info fs.FileInfo, err error) error {
+					// Stop if got error, skip if current file is directory.
+					if info.IsDir() || err != nil {
+						return err
+					}
+					return a.uploadOne(ctx, uf, upld, builder, path, info)
+				})
 			})
+		},
+	}
 
-			return g.Wait()
-		})
-	})
+	flags := cmd.Flags()
+	flags.StringVarP(&uf.peer, "peer", "p", "",
+		"peer to write (channel name, username, phone number or deep link); default: yourself")
+	flags.StringVarP(&uf.message, "message", "m", "", "text message (caption) to send with the file")
+	flags.StringVar(&uf.filename, "filename", "",
+		"value of the filename attribute (defaults to the name from the given path)")
+	flags.Var(uf.docType, "type", "type of uploaded document (default: detect from MIME)")
+	flags.IntVarP(&uf.threads, "threads", "j", 1, "concurrency limit")
+	uf.msg.register(flags)
+
+	registerPeerCompletion(cmd, "peer")
+	registerEnumCompletion(cmd, "type", documentTypes())
+
+	return cmd
 }
diff --git a/go.mod b/go.mod
index 3e6fbb5..fe3c7da 100644
--- a/go.mod
+++ b/go.mod
@@ -4,14 +4,15 @@ go 1.25.0
 
 require (
 	github.com/gabriel-vasile/mimetype v1.4.2
+	github.com/go-faster/errors v0.7.1
 	github.com/gotd/contrib v0.21.1
 	github.com/gotd/log/logzap v0.0.1
 	github.com/gotd/td v0.154.0
 	github.com/schollz/progressbar/v3 v3.19.0
-	github.com/urfave/cli/v2 v2.27.7
+	github.com/spf13/cobra v1.10.2
+	github.com/spf13/pflag v1.0.9
 	go.uber.org/zap v1.28.0
 	golang.org/x/sync v0.21.0
-	golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1
 	gopkg.in/yaml.v3 v3.0.1
 )
 
@@ -24,7 +25,6 @@ require (
 	github.com/dlclark/regexp2 v1.11.5 // indirect
 	github.com/fatih/color v1.19.0 // indirect
 	github.com/ghodss/yaml v1.0.0 // indirect
-	github.com/go-faster/errors v0.7.1 // indirect
 	github.com/go-faster/jx v1.2.0 // indirect
 	github.com/go-faster/xor v1.0.0 // indirect
 	github.com/go-faster/yaml v0.4.6 // indirect
@@ -32,6 +32,7 @@ require (
 	github.com/gotd/ige v0.2.2 // indirect
 	github.com/gotd/log v0.0.1 // indirect
 	github.com/gotd/neo v0.1.5 // indirect
+	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/klauspost/compress v1.18.6 // indirect
 	github.com/mattn/go-colorable v0.1.14 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
@@ -42,12 +43,12 @@ require (
 	github.com/russross/blackfriday/v2 v2.1.0 // indirect
 	github.com/segmentio/asm v1.2.1 // indirect
 	github.com/shopspring/decimal v1.4.0 // indirect
-	github.com/xrash/smetrics v0.0.0-20240521201337-686a1a2994c1 // indirect
 	go.opentelemetry.io/otel v1.44.0 // indirect
 	go.opentelemetry.io/otel/metric v1.44.0 // indirect
 	go.opentelemetry.io/otel/trace v1.44.0 // indirect
 	go.uber.org/atomic v1.11.0 // indirect
 	go.uber.org/multierr v1.11.0 // indirect
+	go.yaml.in/yaml/v3 v3.0.4 // indirect
 	golang.org/x/crypto v0.53.0 // indirect
 	golang.org/x/exp v0.0.0-20230725093048-515e97ebf090 // indirect
 	golang.org/x/mod v0.37.0 // indirect
diff --git a/go.sum b/go.sum
index 76a01d7..75cc5c6 100644
--- a/go.sum
+++ b/go.sum
@@ -8,6 +8,7 @@ github.com/chengxilo/virtualterm v1.0.4 h1:Z6IpERbRVlfB8WkOmtbHiDbBANU7cimRIof7m
 github.com/chengxilo/virtualterm v1.0.4/go.mod h1:DyxxBZz/x1iqJjFxTFcr6/x+jSpqN0iwWCOK1q10rlY=
 github.com/coder/websocket v1.8.14 h1:9L0p0iKiNOibykf283eHkKUHHrpG7f65OE3BhhO7v9g=
 github.com/coder/websocket v1.8.14/go.mod h1:NX3SzP+inril6yawo5CQXx8+fk145lPDC6pumgx0mVg=
+github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
 github.com/cpuguy83/go-md2man/v2 v2.0.7 h1:zbFlGlXEAKlwXpmvle3d8Oe3YnkKIK4xSRTd3sHPnBo=
 github.com/cpuguy83/go-md2man/v2 v2.0.7/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
@@ -49,6 +50,8 @@ github.com/gotd/neo v0.1.5 h1:oj0iQfMbGClP8xI59x7fE/uHoTJD7NZH9oV1WNuPukQ=
 github.com/gotd/neo v0.1.5/go.mod h1:9A2a4bn9zL6FADufBdt7tZt+WMhvZoc5gWXihOPoiBQ=
 github.com/gotd/td v0.154.0 h1:LPfqo8W+V3BbYYpvgtR45QTeV6vWSvVzmfUgXwrw7MA=
 github.com/gotd/td v0.154.0/go.mod h1:pVVlJYiMUMinSR/5uDfCSUoB3DyqxftanMWYLP16riY=
+github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
+github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
 github.com/klauspost/compress v1.18.6 h1:2jupLlAwFm95+YDR+NwD2MEfFO9d4z4Prjl1XXDjuao=
 github.com/klauspost/compress v1.18.6/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
 github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
@@ -81,12 +84,12 @@ github.com/segmentio/asm v1.2.1 h1:DTNbBqs57ioxAD4PrArqftgypG4/qNpXoJx8TVXxPR0=
 github.com/segmentio/asm v1.2.1/go.mod h1:BqMnlJP91P8d+4ibuonYZw9mfnzI9HfxselHZr5aAcs=
 github.com/shopspring/decimal v1.4.0 h1:bxl37RwXBklmTi0C79JfXCEBD1cqqHt0bbgBAGFp81k=
 github.com/shopspring/decimal v1.4.0/go.mod h1:gawqmDU56v4yIKSwfBSFip1HdCCXN8/+DMd9qYNcwME=
+github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
+github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
+github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY=
+github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
-github.com/urfave/cli/v2 v2.27.7 h1:bH59vdhbjLv3LAvIu6gd0usJHgoTTPhCFib8qqOwXYU=
-github.com/urfave/cli/v2 v2.27.7/go.mod h1:CyNAG/xg+iAOg0N4MPGZqVmv2rCoP267496AOXUZjA4=
-github.com/xrash/smetrics v0.0.0-20240521201337-686a1a2994c1 h1:gEOO8jv9F4OT7lGCjxCBTO/36wtF6j2nSip77qHd4x4=
-github.com/xrash/smetrics v0.0.0-20240521201337-686a1a2994c1/go.mod h1:Ohn+xnUBiLI6FVj/9LpzZWtj1/D6lUovWYBkxHVV3aM=
 github.com/xyproto/randomstring v1.0.5 h1:YtlWPoRdgMu3NZtP45drfy1GKoojuR7hmRcnhZqKjWU=
 github.com/xyproto/randomstring v1.0.5/go.mod h1:rgmS5DeNXLivK7YprL0pY+lTuhNQW3iGxZ18UQApw/E=
 go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
@@ -127,8 +130,6 @@ golang.org/x/text v0.38.0 h1:sXmwo9DwP3OK9EZ7PqAdaooSGozfl/3a6/xJcbzPRhE=
 golang.org/x/text v0.38.0/go.mod h1:YXZt3QhHUKYT53r2lLKFIVi6Ao1jdzrTR/KQ09qyxF4=
 golang.org/x/tools v0.46.0 h1:7jTurBkPZu4moS/Uy4OQT1M+QBlsj3wejyZwsT8Z7rk=
 golang.org/x/tools v0.46.0/go.mod h1:FrD85F8l+NWL+9XWBSyVSHO6Ne4jutsfIFba7AWQ5Ys=
-golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1 h1:go1bK/D/BFZV2I8cIQd1NKEZ+0owSTG1fDTci4IqFcE=
-golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15 h1:YR8cESwS4TdDjEe65xsg0ogRM/Nc3DYOhEAlW+xobZo=
 gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=