使用指南
繁體中文(台灣)
快速入門
# 傳送檔案:自動產生密碼,並印出連結與密碼 $ 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 印出一次(在 --json 中為 manage_key)。伺服器只保存它的雜湊值。在任何方案中,您都可以用它追蹤上傳狀態,或提早結束上傳;持有這組金鑰的人可以刪除該筆上傳,所以請像保管密碼一樣保管它。
# 自己上傳之檔案的狀態、下載次數與到期時間 $ 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 | 伺服器 URL | https://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
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 方案。檔案必須屬於所提供的金鑰。
錯誤回應
| 狀態 | 意義 |
|---|---|
401 | API 金鑰無效或已過期 |
403 | 此功能需要 Orbit 方案 |
404 | 找不到檔案,或檔案不屬於此金鑰 |
429 | 超過速率限制 |
500 | 伺服器內部錯誤,請稍後再試 |
502 | 儲存服務暫時無法使用,請稍後再試 |
限制
| 項目 | 免費 | Orbit |
|---|---|---|
| 檔案大小上限 | 6 GB | 50 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,驗證下載者知道正確的密碼。