使用指南

繁體中文(香港)

快速入門

# 傳送檔案:自動產生密碼,並印出連結與密碼
$ ttl send secret.pdf
No password provided. Generate one? [Y/n]:
Generated password: aB3kL9mXq7Rt
·✧★◉ Thank goodness, secret.pdf is in orbit (1.2 MB, expires 2026-10-08 12:00)
IMPORTANT! Save your password — required to download and decrypt the file.
Password: aB3kL9mXq7Rt
Manage key: k7Qm2vXpL9aR4tB8cD1eF6gH3jK5mN0oP2qS4uV7wYz (ttl status / ttl delete -k)
https://ttlspaceusercontent.com/aBcDeFgHiJ

# 下載:以互動方式提示輸入密碼
$ ttl get https://ttlspaceusercontent.com/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

預先編譯的執行檔

# 從 releases 頁面下載適合你平台的版本
$ curl -Lo ttl.tar.gz \
  https://github.com/tweenietomatoes/ttl/releases/download/v1.6.2/ttl_1.6.2_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.2

傳送檔案

基本傳送

# 自動產生密碼,預設 TTL 為 7d
$ 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 天後到期(預設)

大型檔案

16 MiB 以內的檔案會以單一請求傳送;更大的檔案則分成可續傳的 16 MiB 區段,一次傳送兩個。每個請求都會以 SHA-256 摘要驗證,途中失敗的請求會重新傳送;已經傳送完成的區段會保留。按下 Ctrl-C 即可乾淨地取消。

下載檔案

互動式(終端機)

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

輸入的密碼不會顯示在終端機上。原始檔名會被保留;如果輸出目錄中已有同名檔案,檔案會存成 name (1).ext,而不會覆寫原有的檔案。

僅使用 token

# 也可以只使用 10 個字元的 token,不必輸入完整 URL
$ ttl get aBcDeFgHiJ

輸出目錄

$ ttl get -o ~/Downloads aBcDeFgHiJ

預設會將檔案儲存到目前的目錄。使用 -o / --output 可指定其他目錄。

使用密碼選項

$ ttl get -p mySecretPass https://ttlspaceusercontent.com/aBcDeFgHiJ

中斷的下載

中斷的下載會從最後收到的字節繼續;每個 64 KiB 區塊都會各自獨立驗證,因此結果與不中斷的傳輸完全相同。一次性(閱後即焚)檔案要等某次下載完整取得後才會失效:中途斷掉的下載會從停止處接續,檔案也會保留,供下次再試。

瀏覽器

你也可以直接開啟連結,在瀏覽器中下載並解密檔案。網頁介面使用相同的檔案格式與演算法(Argon2id、XChaCha20-Poly1305),並會提示你輸入密碼。不需要安裝任何軟件。

管理密鑰

每次上載都會附帶一組管理密鑰,由 ttl send 印出一次(manage_key 欄位,見於 --json 模式)。伺服器只保存它的雜湊值。在任何計劃中,你都可以用它追蹤上載狀態,或提早結束上載;持有這組密鑰的人可以刪除該筆上載,所以請像保管密碼一樣保管它。

# 自己上載之檔案的狀態、下載次數與到期時間
$ ttl status aBcDeFgHiJ -k k7Qm2vXpL9aR4tB8cD1eF6gH3jK5mN0oP2qS4uV7wYz
Token:      aBcDeFgHiJ
State:      active
Size:       4.2 MB
Created:    2026-10-01 12:00
Expires:    2026-10-08 12:00
Downloads:  1 (last 2026-10-02 09:12)

# 提早刪除
$ ttl delete aBcDeFgHiJ -k k7Qm2vXpL9aR4tB8cD1eF6gH3jK5mN0oP2qS4uV7wYz
Deleted: aBcDeFgHiJ

狀態為 active、expired、burned 或 deleted 其中之一。

密碼處理方式

密碼是加密密鑰的種子。它絕不會離開你的裝置,也絕不會傳送到伺服器。共有六種提供方式:

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://ttlspaceusercontent.com/aBcDeFgHiJ
Enter password: ********

輸入的密碼不會顯示。執行 send 時,你可以選擇是否自動產生;若自行輸入,則需再確認一次。執行 get 時,會直接提示你輸入。

3. 選項:-p / --password

$ ttl send -p mySecretPass file.zip
$ ttl get --password mySecretPass https://ttlspaceusercontent.com/aBcDeFgHiJ
-p / --password 會顯示在 ps aux 的輸出中,也可能被記錄在 shell 歷史記錄(~/.bash_history)裡。請避免在共用環境和腳本中使用,改用 --password-stdin 或 --password-file。

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://ttlspaceusercontent.com/aBcDeFgHiJ

# 使用 here-string
$ 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://ttlspaceusercontent.com/aBcDeFgHiJ

讀取檔案的第一行(會去掉結尾的換行字元)。可搭配 Docker secrets(/run/secrets/)、Vault agent 檔案及類似做法使用。

6. 自動偵測的檔案:ttl.password

若未明確指定密碼,CLI 會先在執行檔旁邊尋找 ttl.password 檔案,接著尋找 ~/.ttl/password。檔案的第一行會作為密碼。

一次只能使用一種明確指定的密碼來源。同時使用 -p / --password、--password-stdin 與 --password-file 會發生錯誤。只有在這些都沒有提供時,才會檢查自動偵測的 ttl.password 檔案。密碼長度至少需要 8 個字元。

選項參考

傳送選項

選項說明預設值
-p, --password P加密密碼互動式
--password-stdin從標準輸入讀取密碼
--password-file F從檔案讀取密碼
-t, --ttl DUR存活時間7d
-b, --burn閱後即焚(僅能下載一次)關閉
-u, --uploader-only僅限你的帳戶下載:帳戶頁面或其任何 API 密鑰(Orbit;別名 --private)關閉
--timeout DUR傳輸逾時無
--server URL伺服器 URLhttps://ttl.space
-h3, --http3嘗試使用 HTTP/3 (QUIC),失敗時退回 TCP關閉
--json將 JSON 輸出到標準輸出(供腳本與 AI 代理使用)關閉

下載選項

選項說明預設值
-p, --password P解密密碼互動式
--password-stdin從標準輸入讀取密碼
--password-file F從檔案讀取密碼
-o, --output DIR輸出目錄目前的目錄
--timeout DUR傳輸逾時無
--server URL僅提供 token 時使用的伺服器https://ttl.space
-h3, --http3嘗試使用 HTTP/3 (QUIC),失敗時退回 TCP關閉
--json將 JSON 輸出到標準輸出(供腳本與 AI 代理使用)關閉

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://ttlspaceusercontent.com/xK9mQ2vLpA","token":"xK9mQ2vLpA","filename":"report.pdf","size":2097152,"ttl":"7d","expires_in":604800,"expires_at":1760011200,"burn":false,"uploader_only":false,"is_permanent":false,"manage_key":"k7Qm2vXpL9aR4tB8cD1eF6gH3jK5mN0oP2qS4uV7wYz","password":"aB3kL9mXq7Rt"}

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

# 使用管理密鑰查詢狀態
$ ttl --json status xK9mQ2vLpA -k k7Qm2vXpL9aR4tB8cD1eF6gH3jK5mN0oP2qS4uV7wYz
{"ok":true,"token":"xK9mQ2vLpA","status":{"state":"active","size_bytes":2097152,"created_at":1759406400,"expires_at":1760011200,"permanent":false,"burn":false,"note":false,"uploader_only":false,"downloads":1,"last_download_at":1759492800,"part_reads":0,"last_part_at":0}}

# 發生錯誤時會回傳 ok:false
{"ok":false,"error":"Link not found. The file may have expired, been downloaded already (burn after reading), or be private (uploader-only)"}

在 --json 模式下,所有輸出都是標準輸出上的結構化 JSON。傳送時若未提供密碼,會自動產生一組並包含在回應中。成功時結束代碼為 0,發生錯誤時為 1。

Orbit 計劃

Orbit 可解鎖更大的檔案(50 GB)、更長的保存期限(30 天,訂閱則可永久)、帳戶專屬檔案(只有你的帳戶能下載),以及檔案管理功能(列出與刪除)。完整比較請見功能頁面。

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: 50.0 GB
Max TTL: 30 days (or permanent)
Uploads per day: 1000000
Storage quota: 1024.0 GB

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

# 使用延長的 TTL 傳送
$ ttl send -t 30d large-backup.tar.gz
# 永久檔案(僅限 Orbit):不會到期,會保留到你刪除它或訂閱結束為止
$ ttl send -t permanent archive.tar.gz
# 傳送私人檔案:只有你的帳戶能下載(僅限 Orbit)
$ ttl send -u payroll.xlsx

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

# 提早刪除檔案(ttl list 會逐頁走訪;-n 5 會在五個檔案後停止)
$ ttl delete xK9mQ2vLpA
Deleted: xK9mQ2vLpA
# 或使用該筆上載的管理密鑰(任何計劃皆可):ttl delete xK9mQ2vLpA -k KEY

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

HTTP API

上載與下載需要使用 CLI 的加密流程(Argon2id + XChaCha20-Poly1305 + 分塊 AEAD)。若要撰寫腳本,請使用 ttl send / ttl get 或 --json 模式。以下的端點用於 Orbit 檔案管理。

列出檔案(Orbit)

$ curl https://ttl.space/v1/files -H "X-API-Key: ttl_orbit_..."
{"files":[{"token":"xK9mQ2vLpA","link":"https://ttlspaceusercontent.com/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 計劃。檔案必須屬於所提供的密鑰。

錯誤回應

狀態意義
401API 密鑰無效或已過期
403此功能需要 Orbit 計劃
404找不到檔案,或檔案不屬於此密鑰
429超過速率限制
500伺服器內部錯誤,請稍後再試
502儲存服務暫時無法使用,請稍後再試

限制

項目免費Orbit
檔案大小上限6 GB50 GB
TTL 上限7 天30 天或永久
每日上載次數4無限制
每日上載量(每個 IP)6 GB無限制
同時上載數每個 IP 2 個每個 API 密鑰 4 個
儲存配額✗1 TB
檔案列表✗✓
提早刪除✓✓
僅限上載者下載的檔案✗✓
密碼長度下限8 個字元
每個 IP 的請求數每 10 秒 300 次
每個 IP 的連線數同時 100 個

加密

檔案在上載前就會先在你的裝置上加密。伺服器只儲存密文,無法解密你的檔案。

元件演算法 / 數值
密鑰衍生Argon2id (time=3, memory=64 MiB, parallelism=1)
加密演算法XChaCha20-Poly1305 AEAD

對密文做任何修改,都會導致解密失敗。伺服器在釋出密文之前,會使用由加密密鑰衍生的單向 token,驗證下載者知道正確的密碼。