Hướng dẫn sử dụng

Tiếng Việt

Bắt đầu nhanh

# gửi một tệp: mật khẩu được tạo tự động, in ra liên kết + mật khẩu
$ 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

# tải xuống: hỏi mật khẩu theo kiểu tương tác
$ ttl get https://ttlspaceusercontent.com/aBcDeFgHiJ
Enter password: ********
Password verified
◉★✧· Phew, secret.pdf landed safe and sound (1.2 MB)

CLI xử lý mã hóa, tải lên, tải xuống và giải mã. Máy chủ không bao giờ nhìn thấy mật khẩu hay dữ liệu gốc (chưa mã hóa) của bạn.

Cài đặt

Homebrew (macOS)

$ brew install tweenietomatoes/ttl/ttl

Scoop (Windows)

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

Tệp nhị phân dựng sẵn

# tải bản dành cho nền tảng của bạn từ trang phát hành
$ 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

Từ mã nguồn

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

Kiểm tra

$ ttl version
ttl 1.6.2

Gửi tệp

Gửi cơ bản

# tự tạo mật khẩu, TTL mặc định 7 ngày
$ ttl send report.xlsx

Khi không có mật khẩu nào được cung cấp trong terminal, CLI sẽ hỏi:

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

Nhấn Enter hoặc gõ y để tự động tạo mật khẩu.

Mật khẩu tùy chỉnh

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

Đọc xong tự hủy

# bị xóa sau khi được tải xuống; lượt tải bị gián đoạn có thể tiếp tục và không làm mất lượt dùng
$ ttl send -b photo.jpg

TTL tùy chỉnh

$ ttl send -t 5m temp-credentials.txt   # hết hạn sau 5 phút
$ ttl send -t 30m meeting-link.txt      # hết hạn sau 30 phút
$ ttl send -t 6h backup.tar.gz          # hết hạn sau 6 giờ
$ ttl send -t 1d daily-report.pdf       # hết hạn sau 1 ngày
$ ttl send -t 3d project-archive.zip    # hết hạn sau 3 ngày
$ ttl send -t 5d design-assets.zip      # hết hạn sau 5 ngày
$ ttl send report.xlsx                  # hết hạn sau 7 ngày (mặc định)

Tệp lớn

Tệp tối đa 16 MiB được gửi trong một yêu cầu; tệp lớn hơn được gửi theo từng phần 16 MiB có thể tiếp tục, mỗi lần hai phần. Mỗi yêu cầu được kiểm tra bằng mã băm SHA-256, và yêu cầu nào lỗi giữa chừng sẽ được gửi lại; các phần đã gửi được giữ nguyên. Ctrl-C hủy gọn gàng.

Tải xuống tệp

Tương tác (terminal)

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

Mật khẩu không được hiển thị khi gõ trên terminal. Tên tệp gốc được giữ nguyên; nếu tên đó đã tồn tại trong thư mục đầu ra, tệp sẽ được lưu thành name (1).ext thay vì ghi đè lên tệp cũ.

Chỉ dùng mã token

# bạn có thể chỉ dùng mã token gồm 10 ký tự thay cho toàn bộ URL
$ ttl get aBcDeFgHiJ

Thư mục đầu ra

$ ttl get -o ~/Downloads aBcDeFgHiJ

Theo mặc định, tệp được lưu vào thư mục hiện tại. Dùng -o / --output để chỉ định thư mục khác.

Với cờ mật khẩu

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

Tải xuống bị gián đoạn

Lượt tải bị đứt sẽ tiếp tục từ byte cuối cùng đã nhận; mỗi khối 64 KiB được xác thực riêng, nên kết quả giống hệt một lần truyền không bị đứt. Tệp dùng một lần (đọc xong tự hủy) chỉ bị dùng mất lượt khi một lượt tải đã lấy trọn vẹn tệp: lượt tải bị đứt giữa chừng sẽ tiếp tục từ chỗ đã dừng, và tệp vẫn còn để thử lại.

Trình duyệt

Bạn cũng có thể tải xuống và giải mã tệp trong trình duyệt bằng cách truy cập thẳng vào liên kết. Giao diện web dùng cùng định dạng tệp và thuật toán (Argon2id, XChaCha20-Poly1305) và sẽ hỏi mật khẩu của bạn. Không cần cài đặt phần mềm.

Khóa quản lý

Mỗi lượt tải lên đều đi kèm một khóa quản lý, được ttl send in ra đúng một lần (manage_key trong --json). Máy chủ chỉ giữ giá trị băm của khóa. Ở mọi gói, khóa cho phép bạn theo dõi lượt tải lên hoặc kết thúc nó sớm; ai giữ khóa cũng có thể xóa lượt tải lên đó, nên hãy bảo quản khóa như mật khẩu.

# trạng thái, lượt tải xuống và thời hạn của lượt tải lên của chính bạn
$ 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)

# xóa sớm
$ ttl delete aBcDeFgHiJ -k k7Qm2vXpL9aR4tB8cD1eF6gH3jK5mN0oP2qS4uV7wYz
Deleted: aBcDeFgHiJ

Trạng thái là một trong các giá trị active, expired, burned hoặc deleted.

Xử lý mật khẩu

Mật khẩu là hạt giống của khóa mã hóa. Mật khẩu không bao giờ rời khỏi thiết bị của bạn và không bao giờ được gửi đến máy chủ. Có sáu cách để cung cấp mật khẩu:

1. Tự động tạo (chỉ khi gửi)

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

Tạo mật khẩu ngẫu nhiên an toàn về mặt mật mã gồm 12 ký tự từ [0-9A-Za-z]. Chỉ dùng được khi chạy send (theo kiểu tương tác, hoặc tự động ở chế độ --json).

2. Nhắc nhập tương tác

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

$ ttl get https://ttlspaceusercontent.com/aBcDeFgHiJ
Enter password: ********

Mật khẩu không được hiển thị khi gõ. Khi send, bạn chọn có tự động tạo hay không; nếu tự gõ mật khẩu, bạn phải xác nhận lại. Khi get, bạn được hỏi trực tiếp.

3. Cờ: -p / --password

$ ttl send -p mySecretPass file.zip
$ ttl get --password mySecretPass https://ttlspaceusercontent.com/aBcDeFgHiJ
-p / --password hiển thị trong kết quả của ps aux và có thể được lưu trong lịch sử shell (~/.bash_history). Hãy tránh dùng trong môi trường dùng chung và trong script. Thay vào đó, hãy dùng --password-stdin hoặc --password-file.

4. Stdin: --password-stdin

# chuyển qua pipe từ echo
$ echo "mySecretPass" | ttl send --password-stdin backup.tar.gz

# chuyển qua pipe từ trình quản lý mật khẩu
$ pass show ttl/key | ttl send --password-stdin data.zip

# chuyển qua pipe từ biến môi trường
$ printenv MY_SECRET | ttl get --password-stdin https://ttlspaceusercontent.com/aBcDeFgHiJ

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

Đọc dòng đầu tiên từ stdin. Hữu ích trong script, quy trình CI/CD và tự động hóa. Khi stdin không phải là terminal và không có nguồn mật khẩu nào được cung cấp, CLI thoát với lỗi (trừ khi dùng --json, chế độ này tự động tạo mật khẩu).

5. Tệp: --password-file

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

Đọc dòng đầu tiên của tệp (bỏ ký tự xuống dòng ở cuối). Tương thích với Docker secrets (/run/secrets/), các tệp của Vault agent và những mẫu tương tự.

6. Tệp được tự động phát hiện: ttl.password

Nếu không có mật khẩu nào được chỉ định rõ, CLI sẽ tìm tệp ttl.password cạnh tệp thực thi, rồi đến ~/.ttl/password. Dòng đầu tiên được dùng làm mật khẩu.

Mỗi lần chỉ có thể dùng một nguồn mật khẩu được chỉ định rõ. Kết hợp -p / --password, --password-stdin và --password-file là lỗi. Tệp ttl.password được tự động phát hiện chỉ được kiểm tra khi không có nguồn nào ở trên được dùng. Độ dài mật khẩu tối thiểu là 8 ký tự.

Tham chiếu tùy chọn

Cờ của lệnh send

CờMô tảMặc định
-p, --password PMật khẩu mã hóatương tác
--password-stdinĐọc mật khẩu từ stdin
--password-file FĐọc mật khẩu từ tệp
-t, --ttl DURThời gian tồn tại7d
-b, --burnĐọc xong tự hủy (chỉ tải xuống một lần)tắt
-u, --uploader-onlyChỉ tài khoản của bạn mới tải xuống được: qua trang tài khoản hoặc bất kỳ khóa API nào của tài khoản (Orbit; bí danh --private)tắt
--timeout DURThời gian chờ truyềnkhông có
--server URLURL máy chủhttps://ttl.space
-h3, --http3Thử HTTP/3 (QUIC), quay về TCP nếu không đượctắt
--jsonXuất JSON ra stdout (cho script và tác nhân AI)tắt

Cờ của lệnh get

CờMô tảMặc định
-p, --password PMật khẩu giải mãtương tác
--password-stdinĐọc mật khẩu từ stdin
--password-file FĐọc mật khẩu từ tệp
-o, --output DIRThư mục đầu rathư mục hiện tại
--timeout DURThời gian chờ truyềnkhông có
--server URLMáy chủ khi chỉ dùng mã tokenhttps://ttl.space
-h3, --http3Thử HTTP/3 (QUIC), quay về TCP nếu không đượctắt
--jsonXuất JSON ra stdout (cho script và tác nhân AI)tắt

Giá trị TTL

Miễn phí: 5m 10m 15m 30m 1h 2h 3h 6h 12h 24h 1d 2d 3d 4d 5d 6d 7d

Orbit bổ sung: 14d 15d 28d 30d permanent

Thời gian chờ

Mặc định: không có. Một lần truyền bị đình trệ sẽ tự tiếp tục, và sẽ bỏ cuộc nếu không thể tiếp tục. Đặt giới hạn bằng --timeout 30m hoặc --timeout 2h.

Ví dụ

Script: sao lưu và tải lên

#!/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

Chuyển liên kết vào bộ nhớ tạm (macOS)

$ ttl send -p mypass123 file.pdf | pbcopy

Chuyển liên kết vào bộ nhớ tạm (Linux)

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

Đọc xong tự hủy: bí mật dùng một lần

$ echo "$DB_PASSWORD" | ttl send --password-stdin -b -t 5m credentials.env
# liên kết chỉ dùng được đúng một lần, hết hạn sau 5 phút

Chế độ JSON (script & tác nhân AI)

# gửi: mật khẩu được tạo tự động ở chế độ 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"}

# tải xuống
$ ttl --json get -p aB3kL9mXq7Rt xK9mQ2vLpA
{"ok":true,"token":"xK9mQ2vLpA","filename":"report.pdf","size":2097152,"saved_to":"/home/user/report.pdf"}

# xem trạng thái bằng khóa quản lý
$ 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}}

# lỗi trả về ok:false
{"ok":false,"error":"Link not found. The file may have expired, been downloaded already (burn after reading), or be private (uploader-only)"}

Ở chế độ --json, toàn bộ đầu ra là JSON có cấu trúc trên stdout. Nếu không có mật khẩu nào được cung cấp khi gửi, một mật khẩu sẽ được tạo tự động và đưa vào phản hồi. Mã thoát là 0 khi thành công, 1 khi có lỗi.

Gói Orbit

Orbit mở khóa tệp lớn hơn (50 GB), thời gian lưu lâu hơn (30 ngày, hoặc vĩnh viễn với gói đăng ký), tệp gắn với tài khoản của bạn (chỉ tài khoản của bạn mới tải xuống được) và quản lý tệp (xem danh sách & xóa). So sánh đầy đủ: Tính năng.

Khóa API được tự động phát hiện từ biến môi trường TTL_API_KEY, tệp ttl.key cạnh tệp thực thi, hoặc ~/.ttl/key. Dùng ttl activate để lưu khóa, hoặc tự ghi khóa vào bất kỳ vị trí nào trong số này.

# kích hoạt khóa của bạn: khóa được hỏi mà không hiển thị khi gõ, nên không lọt vào lịch sử shell
$ ttl activate
Enter Orbit API key: ********
Orbit plan activated. Key saved to /usr/local/bin/ttl.key
# không tương tác: ttl activate --key-stdin  |  ttl activate --key-file F

# kiểm tra gói và mức sử dụng
$ 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

# gửi với TTL kéo dài
$ ttl send -t 30d large-backup.tar.gz
# tệp vĩnh viễn (chỉ Orbit): không hết hạn, được giữ cho đến khi bạn xóa hoặc gói đăng ký kết thúc
$ ttl send -t permanent archive.tar.gz
# gửi tệp riêng tư: chỉ tài khoản của bạn mới tải xuống được (chỉ Orbit)
$ ttl send -u payroll.xlsx

# xem danh sách các lượt tải lên gần đây
$ 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

# xóa tệp sớm (ttl list duyệt qua mọi trang; -n 5 dừng sau năm tệp)
$ ttl delete xK9mQ2vLpA
Deleted: xK9mQ2vLpA
# hoặc bằng khóa quản lý của lượt tải lên, ở mọi gói: ttl delete xK9mQ2vLpA -k KEY

# gỡ khóa đã lưu
$ ttl deactivate
Key file removed: /usr/local/bin/ttl.key

HTTP API

Tải lên và tải xuống cần có quy trình mã hóa của CLI (Argon2id + XChaCha20-Poly1305 + AEAD theo khối). Hãy dùng ttl send / ttl get hoặc chế độ --json để viết script. Các endpoint bên dưới dành cho việc quản lý tệp Orbit.

Liệt kê tệp (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}

# trang tiếp theo: chỉ khi has_more là true; truyền next_cursor lấy từ phản hồi trước
$ curl "https://ttl.space/v1/files?cursor=1711800600123456" -H "X-API-Key: ttl_orbit_..."

Trả về các tệp được tải lên bằng khóa này, mới nhất trước, 20 tệp mỗi trang. Khi has_more là true, phản hồi cũng có thêm next_cursor; hãy truyền giá trị đó làm ?cursor= để lấy trang tiếp theo. Yêu cầu gói Orbit.

Xóa tệp (Orbit)

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

Trả về 204 No Content khi thành công. Yêu cầu gói Orbit. Tệp phải thuộc về khóa được cung cấp.

Phản hồi lỗi

Trạng tháiÝ nghĩa
401Khóa API không hợp lệ hoặc đã hết hạn
403Tính năng này yêu cầu gói Orbit
404Không tìm thấy tệp hoặc tệp không thuộc về khóa này
429Vượt quá giới hạn tốc độ
500Lỗi máy chủ nội bộ, hãy thử lại sau
502Bộ lưu trữ tạm thời không khả dụng, hãy thử lại sau

Giới hạn

Ràng buộcMiễn phíOrbit
Dung lượng tệp tối đa6 GB50 GB
TTL tối đa7 ngày30 ngày hoặc vĩnh viễn
Lượt tải lên mỗi ngày4Không giới hạn
Tổng dung lượng tải lên mỗi ngày (mỗi IP)6 GBKhông giới hạn
Lượt tải lên đồng thời2 mỗi IP4 mỗi khóa API
Hạn mức lưu trữ✗1 TB
Xem danh sách tệp✗✓
Xóa sớm✓✓
Tệp chỉ người tải lên mới tải xuống được✗✓
Độ dài mật khẩu tối thiểu8 ký tự
Yêu cầu mỗi IP300 mỗi 10 giây
Kết nối mỗi IP100 đồng thời

Mã hóa

Tệp được mã hóa trên thiết bị của bạn trước khi tải lên. Máy chủ chỉ lưu bản mã hóa và không thể giải mã tệp của bạn.

Thành phầnThuật toán / Giá trị
Dẫn xuất khóaArgon2id (time=3, memory=64 MiB, parallelism=1)
Thuật toán mã hóaXChaCha20-Poly1305 AEAD

Bất kỳ thay đổi nào đối với bản mã hóa đều khiến việc giải mã thất bại. Trước khi trả về bản mã hóa, máy chủ xác minh rằng người tải xuống biết đúng mật khẩu, bằng một mã thông báo một chiều được dẫn xuất từ khóa mã hóa.