使用指南

中文

快速开始

# 发送文件：密码自动生成，打印链接和密码
$ ttl send secret.pdf
No password provided. Generate one? [Y/n]:
Generated password: aB3kL9mXq7Rt
·✧★◉ Thank goodness, secret.pdf is in orbit (1.2 MB)
IMPORTANT! Save your password — required to download and decrypt the file.
Password: aB3kL9mXq7Rt
https://ttl.space/aBcDeFgHiJ

# 下载：交互式提示输入密码
$ ttl get https://ttl.space/aBcDeFgHiJ
Enter password: ********
Password verified
◉★✧· Phew, secret.pdf landed safe and sound (1.2 MB)

CLI 自动处理加密、上传、下载和解密。服务器永远看不到您的密码或明文数据。

安装

Homebrew (macOS)

$ brew install tweenietomatoes/ttl/ttl

Scoop (Windows)

$ scoop bucket add ttl https://github.com/tweenietomatoes/scoop-ttl
$ scoop install ttl

预编译二进制文件

# 从发布页面下载适合您平台的版本
$ curl -Lo ttl.tar.gz \
  https://github.com/tweenietomatoes/ttl/releases/download/v1.6.0/ttl_1.6.0_linux_amd64.tar.gz
$ tar xzf ttl.tar.gz && sudo mv ttl /usr/local/bin/

Go install

$ go install github.com/tweenietomatoes/ttl/cmd/ttl@latest

从源码编译

$ git clone https://github.com/tweenietomatoes/ttl
$ cd ttl && go build -o ttl ./cmd/ttl/
$ sudo mv ttl /usr/local/bin/

验证

$ ttl version
ttl 1.6.0

发送文件

基本发送

# 自动生成密码，默认 7 天 TTL
$ ttl send report.xlsx

在终端中未提供密码时，CLI 会询问：

No password provided. Generate one? [Y/n]:

按 Enter 或输入 y 自动生成。

自定义密码

$ ttl send -p mySecretPass -t 1h document.pdf

阅后即焚

# 首次下载开始的那一刻即被用掉；中断后只有该次下载可以继续
$ ttl send -b photo.jpg

自定义 TTL

$ ttl send -t 5m temp-credentials.txt   # 5 分钟后过期
$ ttl send -t 30m meeting-link.txt      # 30 分钟后过期
$ ttl send -t 6h backup.tar.gz          # 6 小时后过期
$ ttl send -t 1d daily-report.pdf       # 1 天后过期
$ ttl send -t 3d project-archive.zip    # 3 天后过期
$ ttl send -t 5d design-assets.zip      # 5 天后过期
$ ttl send report.xlsx                  # 7 天后过期（默认）

下载文件

交互式（终端）

$ ttl get https://ttl.space/aBcDeFgHiJ
Enter password: ********
Password verified
◉★✧· Phew, document.pdf landed safe and sound (4.2 MB)

密码不会显示在终端中。原始文件名会被保留；如果输出目录中已存在同名文件，则不会覆盖它，而是保存为 name (1).ext。

仅使用令牌

# 可以只使用 10 位令牌，无需完整 URL
$ ttl get aBcDeFgHiJ

输出目录

$ ttl get -o ~/Downloads aBcDeFgHiJ

默认情况下，文件保存到当前目录。使用 -o / --output 指定其他目录。

使用密码参数

$ ttl get -p mySecretPass https://ttl.space/aBcDeFgHiJ

浏览器

您也可以通过直接访问链接在浏览器中下载和解密文件。Web 界面使用相同的文件格式和算法（Argon2id、XChaCha20-Poly1305），并提示输入密码。无需安装任何软件。

密码管理

密码是加密密钥的种子。它永远不会离开您的设备，也永远不会发送到服务器。有六种方式提供密码：

1. 自动生成（仅发送时）

$ ttl send notes.txt
No password provided. Generate one? [Y/n]: y
Generated password: aB3kL9mXq7Rt

从 [0-9A-Za-z] 字符集生成加密安全的 12 位随机密码。仅在执行 send 时可用（交互式，或在 --json 模式下自动生成）。

2. 交互式提示

$ ttl send notes.txt
No password provided. Generate one? [Y/n]: n
Enter password: ********
Confirm password: ********

$ ttl get https://ttl.space/aBcDeFgHiJ
Enter password: ********

密码不会回显到终端。send 时会先询问是否自动生成；如果您自行输入密码，需要再次确认。get 时直接提示输入。

3. 参数：-p / --password

$ ttl send -p mySecretPass file.zip
$ ttl get --password mySecretPass https://ttl.space/aBcDeFgHiJ

4. 标准输入：--password-stdin

# 通过 echo 管道传递
$ echo "mySecretPass" | ttl send --password-stdin backup.tar.gz

# 从密码管理器管道传递
$ pass show ttl/key | ttl send --password-stdin data.zip

# 从环境变量管道传递
$ printenv MY_SECRET | ttl get --password-stdin https://ttl.space/aBcDeFgHiJ

# heredoc
$ ttl send --password-stdin report.pdf <<<"mySecretPass"

从标准输入读取第一行。适用于脚本、CI/CD 流水线和自动化。当标准输入不是终端且未提供密码来源时，CLI 会报错退出（除非使用 --json，此时会自动生成密码）。

5. 文件：--password-file

$ ttl send --password-file /run/secrets/key report.xlsx
$ ttl get --password-file ~/.ttl-key https://ttl.space/aBcDeFgHiJ

读取文件的第一行（末尾换行符会被去除）。兼容 Docker secrets（/run/secrets/）、Vault agent 文件及类似模式。

6. 自动检测文件：ttl.password

如果未显式提供密码，CLI 会先查找可执行文件旁的 ttl.password 文件，然后查找 ~/.ttl/password。第一行将用作密码。

选项参考

发送参数

下载参数

TTL 值

免费版：5m 10m 15m 30m 1h 2h 3h 6h 12h 24h 1d 2d 3d 4d 5d 6d 7d

Orbit 额外支持：14d 15d 28d 30d permanent

超时

默认：无。停滞的传输会自动恢复，无法继续时才会放弃。如需设置上限，可使用 --timeout 30m 或 --timeout 2h。

示例

脚本：备份并上传

#!/bin/bash
tar czf /tmp/backup.tar.gz /data
echo "$BACKUP_KEY" | ttl send --password-stdin -t 6h /tmp/backup.tar.gz
rm /tmp/backup.tar.gz

复制链接到剪贴板 (macOS)

$ ttl send -p mypass123 file.pdf | pbcopy

复制链接到剪贴板 (Linux)

$ ttl send -p mypass123 file.pdf | xclip -sel clip

阅后即焚：一次性密文

$ echo "$DB_PASSWORD" | ttl send --password-stdin -b -t 5m credentials.env
# 链接仅可使用一次，5 分钟后过期

JSON 模式（脚本和 AI 代理）

# 发送：JSON 模式下密码自动生成
$ ttl --json send report.pdf
{"ok":true,"link":"https://ttl.space/xK9mQ2vLpA","filename":"report.pdf","size":2097152,"ttl":"7d","burn":false,"uploader_only":false,"is_permanent":false,"password":"aB3kL9mXq7Rt"}

# 下载
$ ttl --json get -p aB3kL9mXq7Rt xK9mQ2vLpA
{"ok":true,"filename":"report.pdf","size":2097152,"saved_to":"/home/user/report.pdf"}

# 错误返回 ok:false
{"ok":false,"error":"Link not found"}

在 --json 模式下，所有输出都是结构化 JSON 并输出到 stdout。发送时如果未提供密码，将自动生成并包含在响应中。退出码：成功为 0，错误为 1。

Orbit 计划

Orbit 解锁更大文件（10 GB）、更长保留期（30 天或永久）、仅上传者可下载的文件（只有您的 API 密钥可以下载）和文件管理（列表和删除）。完整对比：Features。

API 密钥自动检测来源：TTL_API_KEY 环境变量、可执行文件旁的 ttl.key 或 ~/.ttl/key。使用 ttl activate 保存密钥，或手动写入上述位置。

# 激活您的密钥：输入时不回显，因此不会留在 shell 历史记录中
$ ttl activate
Enter Orbit API key: ********
Orbit plan activated. Key saved to /usr/local/bin/ttl.key
# 非交互式：ttl activate --key-stdin  |  ttl activate --key-file F

# 查看计划和用量
$ ttl plan
Plan: orbit
Max file size: 10.0 GB
Max TTL: 30 days (or permanent)
Uploads per day: 1000000

Usage:
  Uploads today: 3
  Active storage: 1.2 GB / 500.0 GB

# 使用延长的 TTL 发送
$ ttl send -t 30d large-backup.tar.gz
# 永久文件（仅限 Orbit）：无过期时间，一直保留，直到您删除它或订阅结束
$ ttl send -t permanent archive.tar.gz
# 发送私密文件：仅您的 API 密钥可以下载（仅限 Orbit）
$ ttl send -u payroll.xlsx

# 列出最近上传的文件
$ ttl list
  xK9mQ2vLpA    4.2 MB  2026-03-16 10:30 → 2026-04-15 10:30  [active]
  https://ttl.space/xK9mQ2vLpA
  rT7bNw3KpF  912.0 KB  2026-03-15 14:20 → 2026-03-17 14:20  [active (burn)]
  https://ttl.space/rT7bNw3KpF

# 提前删除文件
$ ttl delete xK9mQ2vLpA
Deleted: xK9mQ2vLpA

# 移除已保存的密钥
$ ttl deactivate
Key file removed: /usr/local/bin/ttl.key

HTTP API

列出文件（Orbit）

$ curl https://ttl.space/v1/files -H "X-API-Key: ttl_orbit_..."
{"files":[{"token":"xK9mQ2vLpA","link":"https://ttl.space/xK9mQ2vLpA","size_bytes":1048576,"created_at":1711800600,"expires_at":1714392600,"burn":false,"expired":false,"uploader_only":false,"is_permanent":false,"is_note":false,"perm_grace_until":0}],"has_more":false}

# 下一页：仅当 has_more 为 true 时使用；传入上一次响应中的 next_cursor
$ curl "https://ttl.space/v1/files?cursor=1711800600123456" -H "X-API-Key: ttl_orbit_..."

返回使用该密钥上传的文件，按从新到旧排列，每页 20 个。当 has_more 为 true 时，响应中还会包含 next_cursor；将其作为 ?cursor= 传入即可获取下一页。需要 Orbit 计划。

删除文件（Orbit）

$ curl -X DELETE https://ttl.space/v1/files/xK9mQ2vLpA -H "X-API-Key: ttl_orbit_..."

成功时返回 204 No Content。需要 Orbit 计划。文件必须属于该密钥。

错误响应

限制

加密

文件在上传前在您的设备上加密。服务器仅存储密文，无法解密您的文件。

对密文的任何修改都会导致解密失败。服务器在释放密文前，会使用从加密密钥派生的单向令牌验证下载者是否知道正确的密码。