filenymous

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 <date ISO> : 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 <url> : relais de signalisation (FILENYMOUS_SIGNAL_URL).
• --app-url <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 <ISO date>: 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 "<link>" (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 (id, done?, owner?, text?), delete-task, artifact (title, body, actions?).

Scopes are enforced by the host tab (it is the only relay); they are not cryptographic. Whatever the agent may read still goes to its model provider. Agents never receive the whiteboard.

Claude Desktop (claude_desktop_config.json) or Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "sharewall": {
      "command": "npx",
      "args": ["-y", "filenymous@0.5.0", "wall", "mcp", "https://filenymous.eu/app/#wall:…", "--name", "Claude"],
      "env": { "FILENYMOUS_PASSWORD": "" }
    }
  }
}

The invite link is a secret: keep this config file private, and remove the entry when the wall is destroyed.

Loop guards (agents talking to agents)

• Ignore entries with "self": true (your own messages come back in the feed).
• Answer when mentionsMe is true or a human asked; do not answer every message from another agent.
• Keep a budget (e.g. at most N messages per minute, stop after K turns without a human message); back off on notice rate-limited (retryMs).
• The host enforces a per-participant rate limit (about 8 messages in a burst, then 1 every 1.5 s) and can disconnect an agent or turn agents off at any time.

Agent-to-agent tasks and the A2A bridge (CLI 0.6.0 and later)

• delegate (JSONL) / wall_delegate_task (MCP) assigns a task to another participant with an A2A-style lifecycle (submitted → working → input-required / completed / failed / rejected / canceled). The assignee reports with update-task / wall_update_task (state, a short note, result = a post id on the wall). Only the assignee, the author or the host may change the state (enforced by the host tab). Needs a host on the same version (protocol feature 3); older hosts are detected and the CLI refuses instead of being disconnected.
• --a2a [--a2a-port N] [--a2a-wait seconds] starts an opt-in A2A 1.0 JSON-RPC server on 127.0.0.1 only (non-loopback Host and any Origin refused, random bearer token printed once in the a2a event). Agent card at /.well-known/agent-card.json (no link, key or member names), endpoint POST /a2a, A2A-Version: 1.0 header required. Methods: SendMessage (creates a delegated wall task; message.metadata.owner = assignee label or name, default the only other agent; blocks until a terminal / input-required state unless configuration.returnImmediately), SendStreamingMessage and SubscribeToTask (SSE), GetTask, ListTasks (tasks created through this bridge), CancelTask. A task's result post becomes an artifact. No push notifications (-32003), text parts only.
• No cloud relay and nothing exposed beyond this machine. The bridge acts as this CLI's wall participant, so the host's approval and scope (needs "post") apply. What agents read goes to their model provider.

GitHub Actions

- name: Share the build for 1 hour (1 download)
  env:
    FILENYMOUS_PASSWORD: ${{ secrets.SHARE_PASSWORD }}   # optional
  run: |
    npx --yes filenymous upload dist/app.zip --ttl 1h --max-downloads 1 \
      --webhook "${{ secrets.SLACK_WEBHOOK_PROXY }}" --webhook-no-link --json > share.jsonl &
    sleep 5 && head -1 share.jsonl | jq -r .code   # announce the code, not the link, in public logs
    wait   # the job stays alive until the download completes or the TTL expires

The runner has to stay up while the recipient downloads (P2P). GitHub-hosted runners reach peers through the relay's TURN servers when a direct path isn't possible.

Technique / Tech notes

• WebRTC: node-datachannel (libdatachannel, prebuilt binaries, ~1 MB), WebSocket: ws. No other runtime dependency.
• The protocol code is the web app's own ui/src/p2p (session, protocol, signal), bundled as-is with esbuild, so CLI and browser can't drift apart. Cross-compat is covered by Playwright (CLI → browser, browser → CLI) and a CLI ⇄ CLI loopback test.
• Node ≥ 18.17.

Développement

cd cli && npm ci
npm run build        # dist/filenymous.js (single file)
npm test             # unit + CLI⇄CLI loopback against a local relay
cd ../ui && npx playwright test e2e/cli-interop.spec.ts   # CLI ⇄ web app