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