Fix CS
[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 Dependencies
22 ============
23 When using the git version, you need to have the following dependencies
24 installed on your system:
25
26 - PHP 5.4+
27 - PEAR's `Console_CommandLine <http://pear.php.net/package/Console_CommandLine>`_
28 - PEAR's `HTTP_Request2 <http://pear.php.net/package/HTTP_Request2>`_
29 - PEAR's `MIME_Type <http://pear.php.net/package/MIME_Type>`_
30 - PEAR's `NET_URL2 <http://pear.php.net/package/Net_URL2>`_
31
32
33 =============
34 Initial setup
35 =============
36 ::
37
38     $ ./bin/shpub.php connect http://mywebsite
39
40 Different user::
41
42     $ ./bin/shpub.php connect http://mywebsite http://mywebsite/user
43
44 If you pass a third parameter, then it will be the name of the connection.
45 You can select a specific server/connection with ``-s`` on all commands.
46
47
48 List configured servers/connections
49 ===================================
50 ::
51
52     $ ./bin/shpub.php server
53     rr
54     test
55     anoweco.bogo
56     local2
57
58 Also try ``server -v`` which lists server and user URLs.
59
60
61 =============
62 Post creation
63 =============
64 shpub has support for the following post types:
65
66 - `article <http://indieweb.org/article>`_
67 - `bookmark <http://indieweb.org/bookmark>`_
68 - `like <http://indieweb.org/like>`_
69 - `note <http://indieweb.org/note>`_
70 - `reply <http://indieweb.org/reply>`_
71 - `repost <http://indieweb.org/repost>`_
72 - `rsvp <http://indieweb.org/rsvp>`_
73
74 ``shpub`` sends data form-encoded by default.
75 To send JSON requests, use the ``--json`` option.
76
77
78 Create a like
79 =============
80 ::
81
82     $ ./bin/shpub.php like http://example.org/
83     Like created at server
84     http://anoweco.bogo/comment/23.htm
85
86 Create a reply
87 ==============
88 ::
89
90     $ ./bin/shpub.php reply http://example.org/ "Hey, cool!"
91     Reply created at server
92     http://anoweco.bogo/comment/42.htm
93
94
95 Create a note
96 =============
97 A normal note::
98
99     $ ./bin/shpub.php note "oh this is cool!"
100     Note created at server
101     http://known.bogo/2016/oh-this-is-cool.htm
102
103 Note with an image::
104
105     $ ./bin/shpub.php note -f image.jpg "this is so cute"
106     Note created at server
107     http://known.bogo/2016/this-is-so-cute
108
109 You can use ``-f`` several times to upload multiple files.
110
111 URL image upload::
112
113     $ ./bin/shpub.php note -f http://example.org/1.jpg "img url!"
114     Note created at server
115     http://known.bogo/2016/img-url
116
117 Load note content from a file::
118
119     $ ./bin/shpub.php note - < /path/to/file.txt
120     Note created at server
121     http://known.bogo/2017/some-note
122
123
124 Custom post types
125 =================
126 You may create custom post types with the ``x`` command.
127 This is useful if your micropub endpoint supports additional types,
128 like known's ``annotation`` type (comments and likes for posts).
129
130 Create a comment to a known post::
131
132     $ ./bin/shpub.php x annotation\
133         -x url=http://known.bogo/2016/example-domain-1\
134         -x type=reply\
135         -x username=barryf\
136         -x userurl=http://example.org/~barryf\
137         -x userphoto=http://example.org/~barryf/avatar.jpg\
138         -x content="There is a typo in paragraph 1. 'Fou' should be 'Foo'"
139
140
141 ===============
142 Delete/Undelete
143 ===============
144 You may delete and restore posts on micropub servers::
145
146     $ ./bin/shpub.php delete http://known.bogo/2016/like
147
148 Restore a deleted post::
149
150     $ ./bin/shpub.php undelete http://known.bogo/2016/like
151
152
153 =======
154 Updates
155 =======
156 Existing posts can be modified if the `server supports this`__::
157
158     $ ./bin/shpub update --add category=foo category=bar\
159                          --replace slug=differentslug\
160                          --delete category=oldcat\
161                          http://known.bogo/2016/post
162
163 __ https://indieweb.org/Micropub/Servers#Implementation_status
164
165
166 ===================
167 Syndication targets
168 ===================
169 You may list the syndication targets defined on the server::
170
171     $ ./bin/shpub.php targets
172     IndieNews
173      https://news.indieweb.org/en
174
175 Then specify it when creating a post::
176
177     $ ./bin/shpub.php article -x mp-syndicate-to=https://news.indieweb.org/en title text
178
179 ============
180 File uploads
181 ============
182 Most post types allow file uploads. Simply use ``-f``::
183
184     $ ./bin/shpub.php note -f path/to/image.jpg "image test"
185     Note created at server
186     http://known.bogo/2016/image-test
187
188 The media endpoint is used automatically if the micropub endpoint has one.
189 To force shpub to directly upload the file and skip the media endpoint,
190 use the ``--direct-upload`` option::
191
192     $ ./bin/shpub.php note --direct-upload -f path/to/image.jpg "direct upload"
193
194 Use the ``upload`` command to upload files to the media endpoint without
195 creating a post::
196
197     $ ./bin/shpub.php upload /path/to/file.jpg /path/to/file2.jpg
198     Uploaded file /path/to/file.jpg
199     http://test.bogo/micropub-media-endpoint/1474362040.2941/file.jpg
200     Uploaded file /path/to/file2.jpg
201     http://test.bogo/micropub-media-endpoint/1474362040.3383/file2.jpg
202
203
204 =========
205 Debugging
206 =========
207 To debug ``shpub`` or your micropub endpoint, use the ``--debug`` option
208 to see ``curl`` command equivalents to the shpub HTTP requests::
209
210     $ ./bin/shpub.php -s known -d note "a simple note"
211     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'
212     Post created at server
213     http://known.bogo/2016/a-simple-note
214
215
216 ===========
217 About shpub
218 ===========
219 shpub's homepage is http://cweiske.de/shpub.htm
220
221
222 Source code
223 ===========
224 shpub's source code is available from http://git.cweiske.de/shpub.git
225 or the `mirror on github`__.
226
227 __ https://github.com/cweiske/shpub
228
229
230 License
231 =======
232 shpub is licensed under the `AGPL v3 or later`__.
233
234 __ http://www.gnu.org/licenses/agpl.html
235
236
237 Author
238 ======
239 shpub was written by `Christian Weiske`__.
240
241 __ http://cweiske.de/