Filenymous Sharewall

filenymous — CLI

Partage de fichiers chiffré de bout en bout, 100 % pair-à-pair, depuis le terminal ou la CI. End-to-end encrypted, 100 % peer-to-peer file sharing from your terminal or CI.

npx filenymous upload app.zip --ttl 1h

→ https://filenymous.eu/app/#p2p:123-456-ABC/xxxxxxxxxxxxxxxxxxxxxx

Installation : npx filenymous … (sans installation) ou npm i -g filenymous — Node ≥ 18.17.

Français · English · GitHub Actions

---

Français

Principe

• La CLI est un pair émetteur : elle utilise exactement le protocole du transfert direct de l'application web (lien #p2p:CODE/SECRET, AES-256-GCM par bloc de 64 Kio, mot de passe optionnel).
• Le lien s'ouvre dans n'importe quel navigateur sur https://filenymous.eu/app/, ou avec filenymous receive.
• Rien n'est stocké sur un serveur. Le relais de signalisation (wss://www.opendpe.net/filenymous-signal/) ne fait que mettre les deux pairs en relation. Le fichier passe en WebRTC, directement ou via TURN, et toujours chiffré.
• Conséquence : le processus doit rester actif jusqu'à la fin des téléchargements. Il s'arrête de lui-même après --max-downloads téléchargements ou à l'expiration du --ttl.

Envoyer

filenymous upload <fichier...> [--ttl 1h] [--max-downloads 1] [--password X] \

[--webhook URL] [--webhook-no-link] [--allow-empty] [--json] [-q]

- Le lien est écrit sur la **sortie standard**, la progression sur stderr. Avec `--json`, la sortie standard reçoit un événement JSON par ligne.

• --stream : le destinataire web peut lire la vidéo ou l'audio pendant le transfert (« Partage streamé »).
• --expires : le lien expire à cette date (liée à la clé et au lien) ; l'expéditeur cesse alors de servir. Nécessite un destinataire récent (web à jour ou CLI ≥ 0.3).
• --password : un mot de passe est demandé au destinataire. Il n'est jamais envoyé : c'est une preuve HMAC, et une dérivation PBKDF2 est mêlée à la clé AES. Préférez la variable d'environnement FILENYMOUS_PASSWORD, qui n'apparaît pas dans l'historique du shell ni dans les logs de CI.
• Codes de sortie :
• 0 : au moins un téléchargement terminé (ou --allow-empty)
• 2 : TTL expiré sans aucun téléchargement
• 1 : erreur, par exemple 5 mauvais mots de passe
• 130 : Ctrl-C

Recevoir

filenymous receive "<lien ou code>" [-o dossier] [--password X] [--timeout 30m] [--json]

• Les fichiers sont écrits en flux dans le dossier, sans jamais écraser un fichier existant (nom (1).ext).
• Les chemins reçus sont affichés sur la sortie standard.

Webhook

Pour chaque événement, la CLI envoie en POST (JSON) :

{ "event": "share.created | download.completed | share.expired | share.failed",

"link": "https://filenymous.eu/app/#p2p:123-456-ABC/…", "code": "123-456-ABC", "file": "app.zip", "size": 1234, "expiresAt": "2026-10-16T15:00:00.000Z", "downloads": 1, "maxDownloads": 1, "protected": false }

> ⚠️ **Le lien contient le secret** (après `#`) : quiconque lit le webhook peut télécharger le fichier tant que la CLI tourne. Le **code seul suffit aussi**, car le secret lui est rattaché. Utilisez `--webhook-no-link` pour retirer `link` et `code` du webhook, ou protégez le partage par `--password`.

Options communes

• --signal : relais de signalisation (FILENYMOUS_SIGNAL_URL).
• --app-url : base des liens (FILENYMOUS_APP_URL).

---

English

How it works

• The CLI is a sender peer: it speaks the web app's direct-transfer protocol unchanged (#p2p:CODE/SECRET links, AES-256-GCM per 64 KiB chunk, optional password gate).
• Links open in any browser at https://filenymous.eu/app/, or with filenymous receive.
• Nothing is stored server-side. The signaling relay only introduces the peers; the data flows over WebRTC (direct or TURN-relayed), always encrypted.
• So the process must stay alive until downloads are done. It exits by itself after --max-downloads or when --ttl expires.

Send

filenymous upload <file...> [--ttl 1h] [--max-downloads 1] [--password X] \

[--webhook URL] [--webhook-no-link] [--allow-empty] [--json] [-q]

- The link goes to **stdout** and progress to stderr. With `--json`, stdout carries JSON lines events.

• --stream: web recipients can play audio/video while it downloads ("Streamed sharing").
• --expires : the link expires at that date (bound into the key and the link); the sender stops serving afterwards. Requires an up-to-date receiver (current web app or CLI ≥ 0.3).
• Prefer FILENYMOUS_PASSWORD over --password, so the password stays out of shell history and CI logs.
• Exit codes:
• 0: at least one completed download (or --allow-empty)
• 2: TTL expired with no download
• 1: error, e.g. 5 wrong passwords
• 130: interrupted

Receive

filenymous receive "<link or code>" [-o dir] [--password X] [--timeout 30m] [--json]

Webhook

The JSON payload is the same as above, POSTed for share.created, download.completed, share.expired and share.failed.

⚠️ The link carries the decryption secret in its #fragment, and the code alone is enough too. Anyone who can read your webhook payloads can download the file while the CLI runs. Use --webhook-no-link (drops link and code) or --password.

---

Agents IA / Sharewall

FR — Un agent IA (ou un script) peut rejoindre un Sharewall : lire le fil, répondre, réagir, voter, déposer des fichiers. L'hôte doit d'abord cocher « Autoriser les agents IA » (désactivé par défaut). Tout ce que l'agent lit est envoyé au fournisseur de son modèle, hors du chiffrement de bout en bout. Le badge « IA » est auto-déclaré par la CLI.

EN — An AI agent (or any script) can join a Sharewall: read the feed, reply, react, vote, drop files. The host must first enable “Allow AI agents” (off by default). Everything the agent reads is sent to its model provider, outside end-to-end encryption. The “AI” badge is self-declared by the CLI.

npx filenymous wall join "https://filenymous.eu/app/#wall:…" --name "Mon agent"   # JSON Lines on stdin/stdout

npx filenymous wall create --title "Atelier" --allow-agents # host a wall; prints the invite link npx filenymous wall mcp "https://filenymous.eu/app/#wall:…" # MCP server on stdio

Password-protected walls: FILENYMOUS_PASSWORD=… npx filenymous wall join … (or --password). Closing the process leaves the wall; for wall create it also destroys it, unless --keep-on-leave.

Walls have no lifetime by default (they live as long as their host); wall create --ttl 15m|1h|24h still sets a fixed end. Walls created on the web app since October 2026 use links without an expiry (…/0/…): joining them needs filenymous ≥ 0.4.1 (0.4.0 rejects these links).

JSON Lines

Events (stdout, one JSON object per line):

{"event":"ready","role":"peer","label":"peer:2","code":"PFDF-HSRP","expiresAt":"…","burn":false,"agentsAllowed":true}

{"event":"message","seq":3,"id":"m1x…","by":"peer:1","name":"Loutre Jade","agent":false,"self":false,"text":"Salut @Mon agent","mentions":["peer:2"],"mentionsMe":true,"replyTo":"…"} {"event":"file","seq":4,"id":"i1-…","by":"host","name":"…","file":{"name":"spec.pdf","size":12345,"mime":"application/pdf"}} {"event":"reaction","id":"m1x…","emoji":"👍","by":"peer:1","added":true,"count":2} {"event":"join","label":"peer:3","name":"Agent B","agent":true} {"event":"leave",…} {"event":"notice","code":"rate-limited","retryMs":1400} {"event":"ended","reason":"destroyed"}

Also note (masked: no text until get), poll, poll.update, removed, pin, live (a live stream exists — CLI agents cannot watch it). Commands (stdin), with an optional ref echoed in the result:

{"cmd":"send","text":"Résumé : **trois points**","replyTo":"m1x…","ref":1}

{"cmd":"react","id":"m1x…","emoji":"👍"} {"cmd":"file","path":"report.pdf"} {"cmd":"file","name":"notes.md","content":"# …"} {"cmd":"note","text":"secret"} {"cmd":"get","id":"i1-…"} {"cmd":"poll","question":"Format ?","options":["JSON","YAML"]} {"cmd":"vote","id":"…","option":0} {"cmd":"read","since":0} {"cmd":"members"} {"cmd":"info"} {"cmd":"leave"} {"cmd":"notes"} {"cmd":"write-note","title":"Ordre du jour","text":"…"} {"cmd":"write-note","id":"n-…","text":"…"} {"cmd":"delete-note","id":"n-…"} host only: {"cmd":"pin","id":"…"} {"cmd":"kick","label":"peer:3"} {"cmd":"allow-agents","on":false}

Notices: rate-limited (the host's per-participant limit, with retryMs), relay-rate-limited (the signaling relay's per-IP limit: the connection retries by itself), live-limit. FILENYMOUS_DEBUG=1 prints connection status transitions on stderr (never content or keys).

file reads only under --files-root (default: the current directory). get is always explicit: text up to 64 KiB comes back inline, other files are saved to -o; on a self-destruct wall it consumes the item. Exit code 3 = disconnected by the host (kick or agents turned off).

Local HTTP/SSE bridge

--http [--http-port 8787] also serves the same API on 127.0.0.1, with a random bearer token printed once in an {"event":"http","url":…,"token":…} line (or set FILENYMOUS_HTTP_TOKEN). Non-loopback Host headers and any request carrying an Origin (browsers) are refused.

curl -N -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8787/events          # SSE

curl -H "Authorization: Bearer $TOKEN" "http://127.0.0.1:8787/messages?since=0" curl -H "Authorization: Bearer $TOKEN" -H content-type:application/json -d '{"text":"hello"}' http://127.0.0.1:8787/send

MCP

filenymous wall mcp " " (or --create [--allow-agents] to host) is an MCP server on stdio with tools wall_read_messages (since, wait_ms long-poll), wall_send_message, wall_send_file, wall_react, wall_list_participants, wall_get_item, wall_info, and (from 0.4.2) wall_read_notes / wall_write_note for the wall's shared notes (host-versioned, last writer wins, 64 KiB per note).

From 0.5.0: wall_list_tasks / wall_add_task / wall_update_task (the wall's shared checklist and decisions log — the host tab stores them, anyone may tick or assign, only the author or host edits text or deletes), wall_post_artifact (posts a structured summary as a message, or as a .md file plus a short message when longer than ~3.8k chars; its action items can become tasks), and a summarize_wall prompt (prompts/list, prompts/get). wall_info and wall_list_participants report the agent's scope.

Agent scopes (0.5.0)

On a web-hosted wall an agent first waits for the host's approval ({"event":"pending"}, then approved); until then it sees nothing. The host picks a scope: read-only, may post, may fetch files, may reveal masked notes, and optionally limited view (the agent only sees messages that mention it, its own posts, and items the host shared with it — its "context pack"). Scope changes arrive as {"event":"scope",…}; refused commands return scope-denied. A CLI host sets the scope for every agent with wall create --allow-agents --agent-scope post,files,secrets,limited (or read-only, full; default full for backward compatibility) and can change it with {"cmd":"scope","label":"peer:3","scope":"read-only"} and share an item with {"cmd":"share","label":"peer:3","id":"…","on":true}. New JSON Lines commands: tasks, add-task (text, owner?), decision (text), update-task