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