tglfs 0.1.0

package/man/tglfs-inspect.1

@@ -0,0 +1,34 @@
+.TH TGLFS-INSPECT 1 "March 2026" "tglfs 0.1.0" "User Commands"
+.SH NAME
+tglfs-inspect \- inspect file-card metadata and chunk references
+.SH SYNOPSIS
+.B tglfs inspect
+[\fIOPTIONS\fR] \fIufid\fR
+.SH DESCRIPTION
+Shows the file-card metadata and checks whether each referenced chunk message exists and is a Telegram document. Use
+.B --probe
+to run the expensive full current-vs-legacy integrity probe, which downloads, decrypts, and validates the file data.
+.SH OPTIONS
+.TP
+.B --peer <peer>
+Peer to inspect instead of Saved Messages.
+.TP
+.B --probe
+Run the full current-vs-legacy integrity probe.
+.TP
+.B --password <password>
+Password to use for current-vs-legacy probing.
+.TP
+.B --password-env [name]
+Read the probe password from an environment variable. If no name is provided, the command uses
+.B TGLFS_INSPECT_PASSWORD.
+.TP
+.B --password-stdin
+Read the probe password from standard input.
+.TP
+.B --json
+Emit machine-readable JSON.
+.SH ENVIRONMENT
+.TP
+.B TGLFS_INSPECT_PASSWORD
+Default environment variable for the probe password.

package/man/tglfs-login.1

@@ -0,0 +1,53 @@
+.TH TGLFS-LOGIN 1 "March 2026" "tglfs 0.1.0" "User Commands"
+.SH NAME
+tglfs-login \- authenticate with Telegram and persist a TGLFS session
+.SH SYNOPSIS
+.B tglfs login
+[\fIOPTIONS\fR]
+.SH DESCRIPTION
+Authenticates with Telegram as a user account and stores both TGLFS config and the Telegram session for later commands.
+.PP
+If no API ID or API hash is supplied, the CLI uses the same bundled Telegram app credentials as the web client. Explicit flags and environment variables still override those defaults.
+.SH OPTIONS
+.TP
+.B --api-id <id>
+Telegram API ID.
+.TP
+.B --api-hash <hash>
+Telegram API hash.
+.TP
+.B --phone <phone>
+Telegram phone number.
+.TP
+.B --code <code>
+Telegram login code.
+.TP
+.B --code-stdin
+Read the Telegram login code from standard input.
+.TP
+.B --password <password>
+Telegram two-factor password.
+.TP
+.B --password-stdin
+Read the Telegram two-factor password from standard input.
+.TP
+.B --json
+Emit machine-readable JSON.
+.SH ENVIRONMENT
+.TP
+.B TGLFS_API_ID
+Telegram API ID.
+.TP
+.B TGLFS_API_HASH
+Telegram API hash.
+.TP
+.B TGLFS_PHONE
+Telegram phone number.
+.TP
+.B TGLFS_LOGIN_CODE
+Telegram login code.
+.TP
+.B TGLFS_2FA_PASSWORD
+Telegram two-factor password.
+.SH AI AGENT NOTES
+If no login code or two-factor password source is supplied and the command is attached to a TTY, the CLI prompts for the missing value. In a non-interactive session, the agent must provide the secret via flags, environment variables, or standard input.

package/man/tglfs-logout.1

@@ -0,0 +1,17 @@
+.TH TGLFS-LOGOUT 1 "March 2026" "tglfs 0.1.0" "User Commands"
+.SH NAME
+tglfs-logout \- remove persisted TGLFS auth state
+.SH SYNOPSIS
+.B tglfs logout
+[\fB--all\fR] [\fB--json\fR]
+.SH DESCRIPTION
+Removes the saved Telegram session. With
+.B --all
+it also removes the persisted TGLFS config.
+.SH OPTIONS
+.TP
+.B --all
+Delete config as well as the session.
+.TP
+.B --json
+Emit machine-readable JSON.

package/man/tglfs-receive.1

@@ -0,0 +1,26 @@
+.TH TGLFS-RECEIVE 1 "March 2026" "tglfs 0.1.0" "User Commands"
+.SH NAME
+tglfs-receive \- receive one or more TGLFS files from another peer into Saved Messages
+.SH SYNOPSIS
+.B tglfs receive
+[\fB--json\fR] \fIsource\fR \fIufids...\fR
+.SH DESCRIPTION
+For each UFID, forwards the source peer's chunk messages into Saved Messages, rewrites the chunk ids in a new local file card, and stores that new file card in Saved Messages.
+.SH SOURCE RESOLUTION
+The
+.I source
+value is passed directly to Telegram/GramJS entity resolution. Users, groups, and channels can all work. In practice, use a public username such as
+.B alice
+or
+.BR @alice ,
+.BR @mygroup ,
+or
+.BR @mychannel ,
+.B me
+for Saved Messages, or a phone number that the current Telegram account can already resolve, typically a saved contact. If Telegram cannot resolve the value, the command fails.
+.PP
+Private users, groups, and channels can also work if Telegram can already resolve them for the current account, which usually means that account already has access to the dialog or entity.
+.PP
+The
+.I source
+identifies the chat or mailbox that currently contains the TGLFS file card and chunk messages you want to receive. It is not necessarily the original uploader's personal account.

package/man/tglfs-rename.1

@@ -0,0 +1,8 @@
+.TH TGLFS-RENAME 1 "March 2026" "tglfs 0.1.0" "User Commands"
+.SH NAME
+tglfs-rename \- rename an owned TGLFS file card in Saved Messages
+.SH SYNOPSIS
+.B tglfs rename
+[\fB--json\fR] \fIufid\fR \fInew-name\fR
+.SH DESCRIPTION
+Renames the Saved Messages file card for the given UFID. Chunk messages are not modified.

package/man/tglfs-search.1

@@ -0,0 +1,37 @@
+.TH TGLFS-SEARCH 1 "March 2026" "tglfs 0.1.0" "User Commands"
+.SH NAME
+tglfs-search \- search TGLFS file cards in Saved Messages or another peer mailbox
+.SH SYNOPSIS
+.B tglfs search
+[\fIOPTIONS\fR] [\fIquery\fR]
+.SH DESCRIPTION
+Looks up TGLFS file cards in Telegram Saved Messages or another peer mailbox. With no query, the command lists the first page of all file cards. Search results include complete and incomplete file cards.
+.SH OPTIONS
+.TP
+.B --peer <peer>
+Peer to search instead of Saved Messages.
+.TP
+.B --limit <n>
+Maximum number of file cards to fetch. Default:
+.B 50.
+.TP
+.B --offset-id <msgId>
+Resume from a Telegram message-id cursor returned by a previous search page.
+.TP
+.B --sort <sort>
+Sort the current result window. Values:
+.BR date_desc ,
+.BR date_asc ,
+.BR name_asc ,
+.BR name_desc ,
+.BR size_desc ,
+.BR size_asc .
+.TP
+.B --json
+Emit machine-readable JSON.
+.SH AI AGENT NOTES
+The plain-text output is for humans. Agents should prefer
+.B --json
+and can paginate statelessly with
+.B --offset-id.
+The search cursor follows Telegram message order, even when the displayed page is client-side sorted.

package/man/tglfs-send.1

@@ -0,0 +1,22 @@
+.TH TGLFS-SEND 1 "March 2026" "tglfs 0.1.0" "User Commands"
+.SH NAME
+tglfs-send \- send one or more owned TGLFS files to another peer
+.SH SYNOPSIS
+.B tglfs send
+[\fB--json\fR] \fIufids...\fR \fB--to\fR \fIpeer\fR
+.SH DESCRIPTION
+Forwards the referenced chunk messages in batches to the target peer, rewrites the chunk ids in a new file card, and sends the rewritten file card to that peer.
+.SH PEER RESOLUTION
+The
+.I peer
+value is passed directly to Telegram/GramJS entity resolution. Users, groups, and channels can all work. In practice, use a public username such as
+.B alice
+or
+.BR @alice ,
+.BR @mygroup ,
+or
+.BR @mychannel ,
+.B me
+for Saved Messages, or a phone number that the current Telegram account can already resolve, typically a saved contact. If Telegram cannot resolve the value, the command fails.
+.PP
+Private users, groups, and channels can also work if Telegram can already resolve them for the current account, which usually means that account already has access to the dialog or entity.

package/man/tglfs-status.1

@@ -0,0 +1,12 @@
+.TH TGLFS-STATUS 1 "March 2026" "tglfs 0.1.0" "User Commands"
+.SH NAME
+tglfs-status \- show persisted TGLFS config and Telegram authorization status
+.SH SYNOPSIS
+.B tglfs status
+[\fB--json\fR]
+.SH DESCRIPTION
+Shows whether TGLFS config exists, whether a Telegram session file exists, and whether the saved session is currently authorized.
+.SH OPTIONS
+.TP
+.B --json
+Emit machine-readable JSON.

package/man/tglfs-unsend.1

@@ -0,0 +1,37 @@
+.TH TGLFS-UNSEND 1 "March 2026" "tglfs 0.1.0" "User Commands"
+.SH NAME
+tglfs-unsend \- delete one or more received TGLFS files from another peer mailbox
+.SH SYNOPSIS
+.B tglfs unsend
+[\fB--yes\fR] [\fB--json\fR] \fIsource\fR \fIufids...\fR
+.SH DESCRIPTION
+Deletes the referenced chunk messages from the source peer mailbox in batches, then deletes the matching file card message.
+.SH SOURCE RESOLUTION
+The
+.I source
+value is passed directly to Telegram/GramJS entity resolution. Users, groups, and channels can all work. In practice, use a public username such as
+.B alice
+or
+.BR @alice ,
+.BR @mygroup ,
+or
+.BR @mychannel ,
+.B me
+for Saved Messages, or a phone number that the current Telegram account can already resolve, typically a saved contact. If Telegram cannot resolve the value, the command fails.
+.PP
+Private users, groups, and channels can also work if Telegram can already resolve them for the current account, which usually means that account already has access to the dialog or entity.
+.PP
+The
+.I source
+identifies the chat or mailbox that currently contains the received TGLFS file card and chunk messages you want to remove. It is not necessarily the original uploader's personal account.
+.SH OPTIONS
+.TP
+.B --yes
+Skip the confirmation prompt.
+.TP
+.B --json
+Emit machine-readable JSON.
+.SH AI AGENT NOTES
+Agents should pass
+.B --yes
+in non-interactive sessions.

package/man/tglfs-upload.1

@@ -0,0 +1,28 @@
+.TH TGLFS-UPLOAD 1 "March 2026" "tglfs 0.1.0" "User Commands"
+.SH NAME
+tglfs-upload \- upload one file, or archive multiple files, into Telegram Saved Messages
+.SH SYNOPSIS
+.B tglfs upload
+[\fIOPTIONS\fR] \fIpaths...\fR
+.SH DESCRIPTION
+Uploads one file directly into Saved Messages, or packages multiple files into a tar archive using the same naming convention as the web app before uploading.
+.SH OPTIONS
+.TP
+.B --password <password>
+Encryption password.
+.TP
+.B --password-env [name]
+Read the encryption password from an environment variable. If no name is provided, the command uses
+.B TGLFS_UPLOAD_PASSWORD.
+.TP
+.B --password-stdin
+Read the encryption password from standard input.
+.TP
+.B --json
+Emit machine-readable JSON.
+.SH ENVIRONMENT
+.TP
+.B TGLFS_UPLOAD_PASSWORD
+Default environment variable for the upload encryption password.
+.SH AI AGENT NOTES
+TTY uploads render separate UFID and upload progress bars. In non-interactive sessions, agents should provide the encryption password via flags, environment variables, or standard input when needed.

package/man/tglfs.1

@@ -0,0 +1,70 @@
+.TH TGLFS 1 "March 2026" "tglfs 0.1.0" "User Commands"
+.SH NAME
+tglfs \- authenticate with Telegram, manage TGLFS file cards, transfer files, and download TGLFS files by UFID
+.SH SYNOPSIS
+.B tglfs
+[\fIOPTIONS\fR] [\fICOMMAND\fR]
+.SH DESCRIPTION
+.B tglfs
+is a global command-line client for authenticating with Telegram, uploading files, managing TGLFS file cards, transferring files between peers, searching mailboxes, and downloading current-format or legacy TGLFS files by UFID.
+.PP
+Run
+.B tglfs help <command>
+for subcommand-specific help.
+.SH COMMANDS
+.TP
+.B upload <paths...>
+Upload one file, or archive multiple files, into Saved Messages.
+.TP
+.B login
+Authenticate with Telegram and persist the resulting session.
+.TP
+.B status
+Show current config and Telegram authorization state.
+.TP
+.B logout
+Remove the saved Telegram session.
+.TP
+.B search [query]
+Search TGLFS file cards in Saved Messages or another peer mailbox.
+.TP
+.B download <ufid>
+Download a current-format or legacy TGLFS file by UFID.
+.TP
+.B rename <ufid> <new-name>
+Rename an owned TGLFS file card.
+.TP
+.B delete <ufid...>
+Delete one or more owned TGLFS files.
+.TP
+.B send <ufid...> --to <peer>
+Send one or more owned TGLFS files to another peer. Users, groups, and channels can all work if Telegram/GramJS can resolve the value, including public usernames and many already-accessible private dialogs.
+.TP
+.B receive <source> <ufid...>
+Receive one or more TGLFS files from another peer into Saved Messages. The source value names the mailbox to search, not necessarily the original uploader.
+.TP
+.B unsend <source> <ufid...>
+Delete one or more received TGLFS files from another peer mailbox. The source value names the mailbox to modify, not necessarily the original uploader.
+.TP
+.B inspect <ufid>
+Inspect file-card metadata and chunk references; use
+.B --probe
+for a full current-vs-legacy integrity check.
+.TP
+.B help [command]
+Display help for a command.
+.SH FILES
+The CLI stores config and session files in OS-standard per-user app directories.
+.SH SEE ALSO
+.BR tglfs-login (1),
+.BR tglfs-status (1),
+.BR tglfs-logout (1),
+.BR tglfs-upload (1),
+.BR tglfs-search (1),
+.BR tglfs-download (1),
+.BR tglfs-rename (1),
+.BR tglfs-delete (1),
+.BR tglfs-send (1),
+.BR tglfs-receive (1),
+.BR tglfs-unsend (1),
+.BR tglfs-inspect (1)

package/package.json

@@ -0,0 +1,66 @@
+{
+    "name": "tglfs",
+    "version": "0.1.0",
+    "description": "Global CLI for authenticating with Telegram, uploading and managing TGLFS files, transferring them between Telegram chats, and downloading them by UFID.",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/hinsley/tglfs.git",
+        "directory": "packages/tglfs-cli"
+    },
+    "homepage": "https://github.com/hinsley/tglfs#readme",
+    "bugs": {
+        "url": "https://github.com/hinsley/tglfs/issues"
+    },
+    "keywords": [
+        "telegram",
+        "cli",
+        "files",
+        "storage",
+        "backup",
+        "tui",
+        "gramjs",
+        "npm"
+    ],
+    "type": "module",
+    "bin": {
+        "tglfs": "./dist/cli.js"
+    },
+    "man": [
+        "./man/tglfs.1",
+        "./man/tglfs-login.1",
+        "./man/tglfs-status.1",
+        "./man/tglfs-logout.1",
+        "./man/tglfs-upload.1",
+        "./man/tglfs-search.1",
+        "./man/tglfs-download.1",
+        "./man/tglfs-rename.1",
+        "./man/tglfs-delete.1",
+        "./man/tglfs-send.1",
+        "./man/tglfs-receive.1",
+        "./man/tglfs-unsend.1",
+        "./man/tglfs-inspect.1"
+    ],
+    "files": ["dist", "man", "README.md"],
+    "engines": {
+        "node": ">=22.0.0"
+    },
+    "scripts": {
+        "clean": "rm -rf dist",
+        "build": "tsc -p tsconfig.build.json",
+        "prepack": "npm run clean && npm run build",
+        "test": "node --import tsx --test test/**/*.test.ts"
+    },
+    "dependencies": {
+        "commander": "^14.0.3",
+        "env-paths": "^4.0.0",
+        "prompts": "^2.4.2",
+        "telegram": "^2.21.2"
+    },
+    "devDependencies": {
+        "@types/node": "^25.5.0",
+        "@types/prompts": "^2.4.9",
+        "tsx": "^4.21.0",
+        "typescript": "^5.4.3"
+    }
+}