Update README
[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 `HTTP_Request2 <http://pear.php.net/package/HTTP_Request2>`_
28 - PEAR's `MIME_Type <http://pear.php.net/package/MIME_Type>`_
29 - PEAR's `NET_URL2 <http://pear.php.net/package/Net_URL2>`_
30
31
32 =============
33 Initial setup
34 =============
35 ::
36
37     $ ./bin/shpub.php connect http://mywebsite
38
39 Different user::
40
41     $ ./bin/shpub.php connect http://mywebsite http://mywebsite/user
42
43 If you pass a third parameter, then it will be the name of the connection.
44 You can select a specific server/connection with ``-s`` on all commands.
45
46
47 List configured servers/connections
48 ===================================
49 ::
50
51     $ ./bin/shpub.php server
52     rr
53     test
54     anoweco.bogo
55     local2
56
57 Also try ``server -v`` which lists server and user URLs.
58
59
60 =============
61 Post creation
62 =============
63 shpub has support for the following post types:
64
65 - `article <http://indieweb.org/article>`_
66 - `bookmark <http://indieweb.org/bookmark>`_
67 - `like <http://indieweb.org/like>`_
68 - `note <http://indieweb.org/note>`_
69 - `reply <http://indieweb.org/reply>`_
70 - `repost <http://indieweb.org/repost>`_
71 - `rsvp <http://indieweb.org/rsvp>`_
72
73 ``shpub`` sends data form-encoded by default.
74 To send JSON requests, use the ``--json`` option.
75
76
77 Create a like
78 =============
79 ::
80
81     $ ./bin/shpub.php like http://example.org/
82     Like created at server
83     http://anoweco.bogo/comment/23.htm
84
85 Create a reply
86 ==============
87 ::
88
89     $ ./bin/shpub.php reply http://example.org/ "Hey, cool!"
90     Reply created at server
91     http://anoweco.bogo/comment/42.htm
92
93
94 Create a note
95 =============
96 A normal note::
97
98     $ ./bin/shpub.php note "oh this is cool!"
99     Note created at server
100     http://known.bogo/2016/oh-this-is-cool.htm
101
102 Note with an image::
103
104     $ ./bin/shpub.php note -f image.jpg "this is so cute"
105     Note created at server
106     http://known.bogo/2016/this-is-so-cute
107
108 You can use ``-f`` several times to upload multiple files.
109
110 URL image upload::
111
112     $ ./bin/shpub.php note -f http://example.org/1.jpg "img url!"
113     Note created at server
114     http://known.bogo/2016/img-url
115
116
117 ===============
118 Delete/Undelete
119 ===============
120 You may delete and restore posts on micropub servers::
121
122     $ ./bin/shpub.php delete http://known.bogo/2016/like
123
124 Restore a deleted post::
125
126     $ ./bin/shpub.php undelete http://known.bogo/2016/like
127
128
129 =======
130 Updates
131 =======
132 Existing posts can be modified if the `server supports this`__::
133
134     $ ./bin/shpub update --add category=foo category=bar\
135                          --replace slug=differentslug\
136                          --delete category=oldcat\
137                          http://known.bogo/2016/post
138
139 __ https://indieweb.org/Micropub/Servers#Implementation_status
140
141
142 ============
143 File uploads
144 ============
145 Most post types allow file uploads. Simply use ``-f``::
146
147     $ ./bin/shpub.php note -f path/to/image.jpg "image test"
148     Note created at server
149     http://known.bogo/2016/image-test
150
151 The media endpoint is used automatically if the micropub endpoint has one.
152 To force shpub to directly upload the file and skip the media endpoint,
153 use the ``--direct-upload`` option::
154
155     $ ./bin/shpub.php note --direct-upload -f path/to/image.jpg "direct upload"
156
157 Use the ``upload`` command to upload files to the media endpoint without
158 creating a post::
159
160     $ ./bin/shpub.php upload /path/to/file.jpg /path/to/file2.jpg
161     Uploaded file /path/to/file.jpg
162     http://test.bogo/micropub-media-endpoint/1474362040.2941/file.jpg
163     Uploaded file /path/to/file2.jpg
164     http://test.bogo/micropub-media-endpoint/1474362040.3383/file2.jpg
165
166
167 =========
168 Debugging
169 =========
170 To debug ``shpub`` or your micropub endpoint, use the ``--debug`` option
171 to see ``curl`` command equivalents to the shpub HTTP requests::
172
173     $ ./bin/shpub.php -s known -d note "a simple note"
174     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'
175     Post created at server
176     http://known.bogo/2016/a-simple-note
177
178
179 ===========
180 About shpub
181 ===========
182 shpub's homepage is http://cweiske.de/shpub.htm
183
184
185 Source code
186 ===========
187 shpub's source code is available from http://git.cweiske.de/shpub.git
188 or the `mirror on github`__.
189
190 __ https://github.com/cweiske/shpub
191
192
193 License
194 =======
195 shpub is licensed under the `AGPL v3 or later`__.
196
197 __ http://www.gnu.org/licenses/agpl.html
198
199
200 Author
201 ======
202 shpub was written by `Christian Weiske`__.
203
204 __ http://cweiske.de/