Guida all'uso

Avvio rapido

# invia un file: password generata automaticamente, stampa link + password
$ 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

# scarica: chiede la password in modo interattivo
$ ttl get https://ttl.space/aBcDeFgHiJ
Enter password: ********
Password verified
◉★✧· Phew, secret.pdf landed safe and sound (1.2 MB)

La CLI gestisce crittografia, upload, download e decrittografia. Il server non vede mai la tua password né i dati in chiaro.

Installazione

Homebrew (macOS)

$ brew install tweenietomatoes/ttl/ttl

Scoop (Windows)

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

Binario precompilato

# scarica per la tua piattaforma dalla pagina delle release
$ 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

Da sorgente

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

Verifica

$ ttl version
ttl 1.6.0

Invio di file

Invio base

# genera password automaticamente, TTL predefinito 7d
$ ttl send report.xlsx

Quando non viene fornita una password nel terminale, la CLI chiede:

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

Premi Invio o digita y per generare automaticamente.

Password personalizzata

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

Brucia dopo la lettura

# consumato nel momento in cui inizia il primo download; dopo un'interruzione solo quel download può riprendere
$ ttl send -b photo.jpg

TTL personalizzato

$ ttl send -t 5m temp-credentials.txt   # scade in 5 minuti
$ ttl send -t 30m meeting-link.txt      # scade in 30 minuti
$ ttl send -t 6h backup.tar.gz          # scade in 6 ore
$ ttl send -t 1d daily-report.pdf       # scade in 1 giorno
$ ttl send -t 3d project-archive.zip    # scade in 3 giorni
$ ttl send -t 5d design-assets.zip      # scade in 5 giorni
$ ttl send report.xlsx                  # scade in 7 giorni (predefinito)

Download dei file

Interattivo (terminale)

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

La password non viene mostrata nel terminale. Il nome del file originale viene preservato; se nella directory di output esiste già un file con quel nome, il file viene salvato come name (1).ext invece di sovrascriverlo.

Solo token

# puoi usare solo il token di 10 caratteri al posto dell'URL completo
$ ttl get aBcDeFgHiJ

Directory di output

$ ttl get -o ~/Downloads aBcDeFgHiJ

Per impostazione predefinita, i file vengono salvati nella directory corrente. Usa -o / --output per specificare una directory diversa.

Con flag password

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

Browser

Puoi anche scaricare e decrittografare i file nel browser visitando il link direttamente. L'interfaccia web utilizza lo stesso formato di file e gli stessi algoritmi (Argon2id, XChaCha20-Poly1305) e chiede la password. Non è necessaria l'installazione di software.

Gestione della password

La password è il seme della chiave di crittografia. Non lascia mai il tuo dispositivo e non viene mai inviata al server. Ci sono sei modi per fornirla:

1. Generazione automatica (solo invio)

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

Genera una password crittograficamente casuale di 12 caratteri da [0-9A-Za-z]. Disponibile solo durante send (in modo interattivo, oppure automaticamente in modalità --json).

2. Prompt interattivo

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

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

La password non viene mostrata. Durante send, prima scegli se generarla automaticamente. Durante get, il prompt viene mostrato direttamente.

3. Flag: -p / --password

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

4. Stdin: --password-stdin

# pipe da echo
$ echo "mySecretPass" | ttl send --password-stdin backup.tar.gz

# pipe da gestore di password
$ pass show ttl/key | ttl send --password-stdin data.zip

# pipe da variabile d'ambiente
$ printenv MY_SECRET | ttl get --password-stdin https://ttl.space/aBcDeFgHiJ

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

Legge la prima riga da stdin. Utile negli script, nelle pipeline CI/CD e nell'automazione. Se stdin non è un terminale e non è stata fornita alcuna fonte di password, il CLI termina con un errore (tranne con --json, che genera automaticamente una password).

5. File: --password-file

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

Legge la prima riga del file (il ritorno a capo finale viene rimosso). Compatibile con i secret Docker (/run/secrets/), file dell'agente Vault e pattern simili.

6. File rilevato automaticamente: ttl.password

Se non viene fornita una password esplicita, la CLI cerca un file ttl.password accanto al binario, poi ~/.ttl/password. La prima riga viene usata come password.

Riferimento opzioni

Flag di invio

Flag di download

Valori TTL

Gratuito: 5m 10m 15m 30m 1h 2h 3h 6h 12h 24h 1d 2d 3d 4d 5d 6d 7d

Orbit aggiunge: 14d 15d 28d 30d permanent

Timeout

Predefinito: nessun limite. Un trasferimento che si blocca riprende da solo e si interrompe se non riesce più ad avanzare. Per impostare un limite: --timeout 30m o --timeout 2h.

Esempi

Script: backup e upload

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

Copia il link negli appunti (macOS)

$ ttl send -p mypass123 file.pdf | pbcopy

Copia il link negli appunti (Linux)

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

Brucia: segreto monouso

$ echo "$DB_PASSWORD" | ttl send --password-stdin -b -t 5m credentials.env
# il link funziona una sola volta, scade in 5 minuti

Modalità JSON (script & agenti IA)

# invio: password generata automaticamente in modalità 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"}

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

# gli errori restituiscono ok:false
{"ok":false,"error":"Link not found"}

In modalità --json, tutto l'output è JSON strutturato su stdout. Se non viene fornita una password durante l'invio, ne viene generata una automaticamente e inclusa nella risposta. Il codice di uscita è 0 in caso di successo, 1 in caso di errore.

Piano Orbit

Orbit sblocca file più grandi (10 GB), conservazione più lunga (30 giorni o permanente), file riservati a chi li carica (solo la tua chiave API può scaricarli) e gestione dei file (elenco ed eliminazione). Confronto completo: Features.

La chiave API viene rilevata automaticamente: variabile d'ambiente TTL_API_KEY, ttl.key accanto al binario o ~/.ttl/key. Usa ttl activate per salvare la chiave o scrivila manualmente in una di queste posizioni.

# attivare la chiave: richiesta senza eco, così non finisce nella cronologia della shell
$ ttl activate
Enter Orbit API key: ********
Orbit plan activated. Key saved to /usr/local/bin/ttl.key
# non interattivo: ttl activate --key-stdin  |  ttl activate --key-file F

# verificare piano e utilizzo
$ 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

# inviare con TTL esteso
$ ttl send -t 30d large-backup.tar.gz
# file permanente (solo Orbit): nessuna scadenza, conservato finché non lo elimini o finché il tuo abbonamento non termina
$ ttl send -t permanent archive.tar.gz
# invia un file privato: solo la tua chiave API può scaricarlo (solo Orbit)
$ ttl send -u payroll.xlsx

# elencare i caricamenti recenti
$ 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

# eliminare un file
$ ttl delete xK9mQ2vLpA
Deleted: xK9mQ2vLpA

# rimuovere la chiave salvata
$ ttl deactivate
Key file removed: /usr/local/bin/ttl.key

HTTP API

Elenco file (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}

# pagina successiva: solo quando has_more è true; passa il next_cursor della risposta precedente
$ curl "https://ttl.space/v1/files?cursor=1711800600123456" -H "X-API-Key: ttl_orbit_..."

Restituisce i file caricati con questa chiave, dal più recente, 20 per pagina. Quando has_more è true la risposta include anche next_cursor; passalo come ?cursor= per ottenere la pagina successiva. Richiede il piano Orbit.

Elimina file (Orbit)

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

Restituisce 204 No Content in caso di successo. Richiede il piano Orbit. Il file deve appartenere a questa chiave.

Risposte di errore

Limiti

Crittografia

I file vengono crittografati sul tuo dispositivo prima dell'upload. Il server conserva solo il testo cifrato e non può decrittografare i tuoi file.

Qualsiasi modifica al testo cifrato causa il fallimento della decrittografia. Il server verifica che chi scarica conosca la password corretta prima di rilasciare il testo cifrato, utilizzando un token unidirezionale derivato dalla chiave di crittografia.