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/