Add command to create custom types
[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
118 Custom post types
119 =================
120 You may create custom post types with the ``x`` command.
121 This is useful if your micropub endpoint supports additional types,
122 like known's ``annotation`` type (comments and likes for posts).
123
124 Create a comment to a known post::
125
126     $ ./bin/shpub.php x annotation\
127         -x url=http://known.bogo/2016/example-domain-1\
128         -x type=reply\
129         -x username=barryf\
130         -x userurl=http://example.org/~barryf\
131         -x userphoto=http://example.org/~barryf/avatar.jpg\
132         -x content="There is a typo in paragraph 1. 'Fou' should be 'Foo'"
133
134
135 ===============
136 Delete/Undelete
137 ===============
138 You may delete and restore posts on micropub servers::
139
140     $ ./bin/shpub.php delete http://known.bogo/2016/like
141
142 Restore a deleted post::
143
144     $ ./bin/shpub.php undelete http://known.bogo/2016/like
145
146
147 =======
148 Updates
149 =======
150 Existing posts can be modified if the `server supports this`__::
151
152     $ ./bin/shpub update --add category=foo category=bar\
153                          --replace slug=differentslug\
154                          --delete category=oldcat\
155                          http://known.bogo/2016/post
156
157 __ https://indieweb.org/Micropub/Servers#Implementation_status
158
159
160 ===================
161 Syndication targets
162 ===================
163 You may list the syndication targets defined on the server::
164
165     $ ./bin/shpub.php targets
166     IndieNews
167      https://news.indieweb.org/en
168
169 Then specify it when creating a post::
170
171     $ ./bin/shpub.php article -x mp-syndicate-to=https://news.indieweb.org/en title text
172
173 ============
174 File uploads
175 ============
176 Most post types allow file uploads. Simply use ``-f``::
177
178     $ ./bin/shpub.php note -f path/to/image.jpg "image test"
179     Note created at server
180     http://known.bogo/2016/image-test
181
182 The media endpoint is used automatically if the micropub endpoint has one.
183 To force shpub to directly upload the file and skip the media endpoint,
184 use the ``--direct-upload`` option::
185
186     $ ./bin/shpub.php note --direct-upload -f path/to/image.jpg "direct upload"
187
188 Use the ``upload`` command to upload files to the media endpoint without
189 creating a post::
190
191     $ ./bin/shpub.php upload /path/to/file.jpg /path/to/file2.jpg
192     Uploaded file /path/to/file.jpg
193     http://test.bogo/micropub-media-endpoint/1474362040.2941/file.jpg
194     Uploaded file /path/to/file2.jpg
195     http://test.bogo/micropub-media-endpoint/1474362040.3383/file2.jpg
196
197
198 =========
199 Debugging
200 =========
201 To debug ``shpub`` or your micropub endpoint, use the ``--debug`` option
202 to see ``curl`` command equivalents to the shpub HTTP requests::
203
204     $ ./bin/shpub.php -s known -d note "a simple note"
205     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'
206     Post created at server
207     http://known.bogo/2016/a-simple-note
208
209
210 ===========
211 About shpub
212 ===========
213 shpub's homepage is http://cweiske.de/shpub.htm
214
215
216 Source code
217 ===========
218 shpub's source code is available from http://git.cweiske.de/shpub.git
219 or the `mirror on github`__.
220
221 __ https://github.com/cweiske/shpub
222
223
224 License
225 =======
226 shpub is licensed under the `AGPL v3 or later`__.
227
228 __ http://www.gnu.org/licenses/agpl.html
229
230
231 Author
232 ======
233 shpub was written by `Christian Weiske`__.
234
235 __ http://cweiske.de/