Do not require "me" parameter in connection callback
[shpub.git] / README.rst
1 **************************************
2 shpub - micropub client for your shell
3 **************************************
4 Command line `micropub <https://micropub.net/>`_ client written in PHP.
5
6
7 .. contents::
8
9 ========
10 Download
11 ========
12 shpub is released as self-contained ``.phar`` file that includes
13 all dependencies.
14
15 .. LATESTRELEASE
16
17 See `shpub downloads page <http://cweiske.de/shpub-download.htm>`_
18 for all released versions.
19
20
21 Installation
22 ============
23 After downloading ``shpub-x.y.z.phar``, you can either use it directly::
24
25     $ php /path/to/shpub-x.y.z.phar --version
26
27 or make it more easily accessible::
28
29     $ mv /path/to/shpub-x.y.z.phar /usr/local/bin/shpub
30     $ chmod +x /usr/local/bin/shpub
31     $ shpub --version
32
33 You might need ``sudo`` to be able to copy it into the ``/usr/local/bin/``
34 directory.
35
36 If you're running from the git checkout, start it as follows::
37
38     $ ./bin/shpub.php --version
39
40
41 Dependencies
42 ============
43 When using the git version, you need to have the following dependencies
44 installed on your system:
45
46 - PHP 5.4+
47 - PEAR's `Console_CommandLine <http://pear.php.net/package/Console_CommandLine>`_
48 - PEAR's `HTTP_Request2 <http://pear.php.net/package/HTTP_Request2>`_
49 - PEAR's `MIME_Type <http://pear.php.net/package/MIME_Type>`_
50 - PEAR's `NET_URL2 <http://pear.php.net/package/Net_URL2>`_
51
52
53 =============
54 Initial setup
55 =============
56 ::
57
58     $ shpub connect http://mywebsite
59
60 In case there are multiple users on the same server::
61
62     $ shpub connect http://sharedwebsite http://shareswebsite/user
63
64 If you pass a third parameter, then that will be the name of the connection.
65 You can select a specific server/connection with ``-s`` on all commands.
66
67
68 List configured servers/connections
69 ===================================
70 ::
71
72     $ shpub server
73     rr
74     test
75     anoweco.bogo
76     local2
77
78 Also try ``server -v`` which lists server and user URLs.
79
80
81 =============
82 Post creation
83 =============
84 shpub has support for the following post types:
85
86 - `article <http://indieweb.org/article>`_
87 - `bookmark <http://indieweb.org/bookmark>`_
88 - `like <http://indieweb.org/like>`_
89 - `note <http://indieweb.org/note>`_
90 - `reply <http://indieweb.org/reply>`_
91 - `repost <http://indieweb.org/repost>`_
92 - `rsvp <http://indieweb.org/rsvp>`_
93
94 By default ``shpub`` sends data form-encoded.
95 To send JSON requests, use the ``--json`` option.
96
97
98 Create a like
99 =============
100 ::
101
102     $ shpub like http://example.org/
103     Like created at server
104     http://anoweco.bogo/comment/23.htm
105
106 Create a reply
107 ==============
108 ::
109
110     $ shpub reply http://example.org/ "Hey, cool!"
111     Reply created at server
112     http://anoweco.bogo/comment/42.htm
113
114
115 Create a note
116 =============
117 A normal note::
118
119     $ shpub note "oh this is cool!"
120     Note created at server
121     http://known.bogo/2016/oh-this-is-cool.htm
122
123 Note with an image::
124
125     $ shpub note -f image.jpg "this is so cute"
126     Note created at server
127     http://known.bogo/2016/this-is-so-cute
128
129 You can use ``-f`` several times to upload multiple files.
130
131 URL image upload::
132
133     $ shpub note -f http://example.org/1.jpg "img url!"
134     Note created at server
135     http://known.bogo/2016/img-url
136
137 Load note content from a file::
138
139     $ shpub note - < /path/to/file.txt
140     Note created at server
141     http://known.bogo/2017/some-note
142
143
144 Custom post types
145 =================
146 You may create custom post types with the ``x`` command.
147 This is useful if your micropub endpoint supports additional types,
148 like `known <http://withknown.com/>`__'s
149 `"annotation" type <https://cweiske.de/tagebuch/micropub-comments-known.htm>`__
150 (comments and likes for posts).
151
152 Create a comment to a known post::
153
154     $ shpub x annotation\
155         -x url=http://known.bogo/2016/example-domain-1\
156         -x type=reply\
157         -x username=barryf\
158         -x userurl=http://example.org/~barryf\
159         -x userphoto=http://example.org/~barryf/avatar.jpg\
160         -x content="There is a typo in paragraph 1. 'Fou' should be 'Foo'"
161
162
163 ===============
164 Delete/Undelete
165 ===============
166 You may delete and restore posts on micropub servers::
167
168     $ shpub delete http://known.bogo/2016/like
169
170 Restore a deleted post::
171
172     $ shpub undelete http://known.bogo/2016/like
173
174
175 =======
176 Updates
177 =======
178 Existing posts can be modified if the `server supports this`__::
179
180     $ ./bin/shpub update --add category=foo category=bar\
181                          --replace slug=differentslug\
182                          --delete category=oldcat\
183                          http://known.bogo/2016/post
184
185 __ https://indieweb.org/Micropub/Servers#Implementation_status
186
187
188 ===================
189 Syndication targets
190 ===================
191 You may list the syndication targets defined on the server::
192
193     $ shpub targets
194     IndieNews
195      https://news.indieweb.org/en
196
197 Then specify it when creating a post::
198
199     $ shpub article -x mp-syndicate-to=https://news.indieweb.org/en title text
200
201 ============
202 File uploads
203 ============
204 Most post types allow file uploads. Simply use ``-f``::
205
206     $ shpub note -f path/to/image.jpg "image test"
207     Note created at server
208     http://known.bogo/2016/image-test
209
210 The media endpoint is used automatically if the micropub endpoint has one.
211 To force ``shpub`` to directly upload the file and skip the media endpoint,
212 use the ``--direct-upload`` option::
213
214     $ shpub note --direct-upload -f path/to/image.jpg "direct upload"
215
216 Use the ``upload`` command to upload files to the media endpoint without
217 creating a post::
218
219     $ shpub upload /path/to/file.jpg /path/to/file2.jpg
220     Uploaded file /path/to/file.jpg
221     http://test.bogo/micropub-media-endpoint/1474362040.2941/file.jpg
222     Uploaded file /path/to/file2.jpg
223     http://test.bogo/micropub-media-endpoint/1474362040.3383/file2.jpg
224
225
226 =========
227 Debugging
228 =========
229 To debug ``shpub`` or your micropub endpoint, use the ``--debug`` option
230 to see ``curl`` command equivalents to the shpub HTTP requests::
231
232     $ shpub -s known -d note "a simple note"
233     curl -X POST -H 'User-Agent: shpub' -H 'Content-Type: application/x-www-form-urlencoded' -H 'Authorization: Bearer abc' -d 'h=entry' -d 'content=a simple note' 'http://known.bogo/micropub/endpoint'
234     Post created at server
235     http://known.bogo/2016/a-simple-note
236
237
238 See curl commands only
239 ======================
240 You may use the ``--dry-run`` option to make shpub not send any modifying
241 HTTP requests (e.g. POST and PUT).
242
243 Together with ``--debug`` you can use this to get curl commands without sending
244 anything to the server::
245
246     $ shpub --debug --dry-run like example.org
247     curl -X POST -H 'User-Agent: shpub' -H 'Content-Type: application/x-www-form-urlencoded' -H 'Authorization: Bearer cafe' -d 'h=entry' -d 'like-of=http://example.org' 'http://anoweco.bogo/micropub.php'
248     Like created at server
249     http://example.org/fake-response
250
251
252 Server information
253 ==================
254 To see which server, user and endpoint URLs ``shpub`` uses, pass the
255 server name to the ``server`` command::
256
257     $ shpub server commentpara.de
258     commentpara.de
259      URL:   http://commentpara.de
260      User:  https://commentpara.de/user/3.htm
261      Endpoints:
262       micropub:      https://commentpara.de/micropub.php
263       media:
264       token:         https://commentpara.de/token.php
265       authorization: https://commentpara.de/auth.php
266
267
268 ===========
269 Development
270 ===========
271
272 Releasing a new version
273 =======================
274
275 #. Add notes to ``ChangeLog``
276 #. Update version number in ``build.xml`` and ``src/shpub/Cli.php``
277 #. Run ``phing``
278 #. Commit and tag the version
279 #. In the ``cweiske.de`` directory, run ``./scripts/update-shpub.sh``
280
281
282 ===========
283 About shpub
284 ===========
285 shpub's homepage is http://cweiske.de/shpub.htm
286
287
288 Source code
289 ===========
290 shpub's source code is available from http://git.cweiske.de/shpub.git
291 or the `mirror on github`__.
292
293 __ https://github.com/cweiske/shpub
294
295
296 License
297 =======
298 shpub is licensed under the `AGPL v3 or later`__.
299
300 __ http://www.gnu.org/licenses/agpl.html
301
302
303 Author
304 ======
305 shpub was written by `Christian Weiske`__.
306
307 __ http://cweiske.de/