Mercurial > libervia-backend

comparison doc/libervia-cli/file.rst @ 3488:c80a0f864b5d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: updated doc following global renaming
author Goffi <goffi@goffi.org>
date Sun, 21 Mar 2021 18:23:58 +0100
parents doc/jp/file.rst@c3cb18236bdf
children 267e4987b58b
comparison
equal deleted inserted replaced
3487:75427f0a5445 3488:c80a0f864b5d
1 ========================================
2 file: files sending/receiving/management
3 ========================================
4
5 ``file`` group all commands related to file management, and allows you to send easily a
6 file to a contact or device from the command line.
7
8 send
9 ====
10
11 Send a file to a contact.
12
13 The file will be sent using best available method (which is Jingle File Transfer when
14 available), and will try to send the file in P2P when possible. If P2P is possible, the
15 signal is sent through the server (metadata, negotiation, etc.), while the file itself
16 goes directly from the source device to the target device. When P2P is not possible, the
17 file may go through the server or an other one (if a proxy is used for instance).
18
19 When sending a file, you specify one or more file(s) to send, and the either the bare jid
20 or the full jid of the target device. If bare jid is specified, the main resource will be
21 used.
22
23 You'll usually want to see the progression of the transfer, use ``-P, --progress`` for
24 that.
25
26 If you send several files at once, you may want to use ``-b, --bz2`` to group them in a
27 single compressed ``tar.bz2`` archive (the client receiving the files will then receive a
28 single file, than the user can then decompress).
29
30 By default the name of the source file is used, but you use ``-n NAME, --name NAME`` to
31 specify another one.
32
33 The path and namespace (set with ``-d PATH, --path PATH`` and ``-N NAMESPACE, --namespace
34 NAMESPACE``) are non-standard metadata used by SàT to organise files (``PATH`` being like
35 a file path on locale file system, and ``NAMESPACE`` being a name to associate to a group
36 of files, for instance for a photo album).
37
38 examples
39 --------
40
41 Send a file to Louise, with a progress bar::
42
43 $ li file send -P some_file.ext louise@example.org
44
45 Send a picture to a file sharing component, putting it in the ``holidays`` namespace, in
46 the ``/some/path`` path::
47
48 $ li file send -P -N holidays -d /some/path some_photo.jpg files.example.org
49
50 .. _libervia-cli_file_request:
51
52 request
53 =======
54
55 Ask to get a file from a device/sharing service. A file is requested using one or more
56 metadata, which can be the file name (with ``-n NAME, --name NAME``), its hash (with ``-H
57 HASH, --hash HASH`` and the algorithm may be specified with ``-a HASH_ALGO, --hash-algo
58 HASH_ALGO``), its path (with ``-d PATH, --path PATH``) and its namespace (with ``-N
59 NAMESPACE, --namespace NAMESPACE``). Note that ``PATH`` and ``NAMESPACE`` are SàT specific
60 and not (yet?) XMPP standards.
61
62 If you already know the hash, it's the most efficient and recommended way to retrieve a
63 file.
64
65 You need to specify the full jid of the device or the sharing service as a positional
66 argument.
67
68 By default the file is downloaded in current directory, but you can specify an other one
69 (and an other filename) with ``-D DEST, --dest DEST``.
70
71 If you want to see progression of the transfer, use ``-P, --progress``.
72
73 examples
74 --------
75
76 Request a file names ``some_file.jpg`` in path ``/photos/demo_album`` at service
77 ``files.example.org``, with a progress bar::
78
79 $ li file request -P -d photos/demo_album -n some_file.jpg files.example.org
80
81 Request file with given ``sha-256`` hash (which is default hash algorithm, so we don't
82 specify it), and save it to file ``dest_file.txt``::
83
84 $ li file request -H f2ca1bb6c7e907d06dafe4687e579fce76b37e4e93b7605022da52e6ccc26fd2 -D dest_file.txt files.example.org
85
86 receive
87 =======
88
89 Wait for a file (or several ones) to be received, and accept it if it match criteria.
90
91 You should specify which jid you are expecting a file from, using the positional
92 arguments. If you don't, all files will be accepted, which can be dangerous if some
93 malicious user send you a file at this moment.
94
95 To see progression (this is recommended), you can use the ``-P, --progress`` options.
96
97 By default, if a file with the same name as the proposed one exists, the transfer will be
98 denied. You can override this behaviour with ``-f, --force``, but be sure to absolutely
99 trust the sender in this case, as the name is chosen by her, and could be malicious, or it
100 could override an important file.
101
102 If you expect several files, you can use the ``-m, --multiple``, in this case the command
103 won't stop after the file received file, and you'll have to manually stop it with
104 ``Ctrl-C`` or by sending a ``SIGTERM``.
105
106 File(s) will be written in the current directory, but you may specify an other destination
107 with ``--path DIR``.
108
109 examples
110 --------
111
112 Accept and receive the next file, save it to local directory and show a progress bar::
113
114 $ li file receive --progress
115
116 Several files are expected from Louise, accept them and store them do
117 ``~/Downloads/Louise``::
118
119 $ li file receive --multiple --path ~/Downloads/Louise louise@example.org
120
121 get
122 ===
123
124 Download a file from an URI. This commands handle URI scheme common with XMPP, so in
125 addition to ``http`` and ``https``, you can use it with ``aesgcm`` scheme (encrypted files
126 with key in URL, this is notably used with OMEMO encryption).
127
128 As usual, you can use ``-P, --progress`` to see a progress bar.
129
130 example
131 -------
132
133 Download an encrypted file with a progress bar, and save it to current working directory
134 with the same name as in the URL (``some_image.jpg``). The URL fragment part (after ``#``)
135 is used for decryption, so be sure to not leak the URL when you manipulate one::
136
137 $ li file get -P "aesgcm://upload.example.org/wvgSUlURU_UPspAv/some_image.jpg#7d8509c43479591f8d8492f84369875ca983db58f43225c40229eb06d05b2037c841b2346c9642a88ba4a91aa96a0e8f"
138
139 upload
140 ======
141
142 Upload a file to your XMPP server (or an other entity if specified). The upload will be
143 done using `XEP-0363 (HTTP File Upload)`_, and the public URL to retrieve the file will be
144 printed. Note that anybody knowing this URL can download the file you've uploaded.
145
146 The path to the file to upload is expected as first argument, then optionally the entity
147 of the service to upload too (by default, this is autodetected if your server offers this
148 feature).
149
150 As usual, you can use ``-P, --progress`` to see a progress bar.
151
152 You can encrypt the file using ``AES GCM`` with the ``-e, --encrypt`` argument. You will
153 then get an ``aesgcm://`` link instead of the usual ``https``, this link contains the
154 decryption key (in the fragment part) so be sure to not leak it and to transmit it only
155 over encrypted communication channels.
156
157 .. _XEP-0363 (HTTP File Upload): XEP-0363: HTTP File Upload
158
159 example
160 -------
161
162 Upload a document to a server::
163
164 $ li file upload -P ~/Documents/something_interesting.odt
165
166 Encrypt and upload a document to server::
167
168 $ li file upload -P -e ~/Documents/something_secret.odt
169
170 share
171 =====
172
173 Subcommands for advanced file sharing. Please check :ref:`libervia-cli_file_share`.