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 Syndication targets
 144 ===================
 145 You may list the syndication targets defined on the server::
 146
 147     $ ./bin/shpub.php targets
 148     IndieNews
 149      https://news.indieweb.org/en
 150
 151 Then specify it when creating a post::
 152
 153     $ ./bin/shpub.php article -x mp-syndicate-to=https://news.indieweb.org/en title text
 154
 155 ============
 156 File uploads
 157 ============
 158 Most post types allow file uploads. Simply use ``-f``::
 159
 160     $ ./bin/shpub.php note -f path/to/image.jpg "image test"
 161     Note created at server
 162     http://known.bogo/2016/image-test
 163
 164 The media endpoint is used automatically if the micropub endpoint has one.
 165 To force shpub to directly upload the file and skip the media endpoint,
 166 use the ``--direct-upload`` option::
 167
 168     $ ./bin/shpub.php note --direct-upload -f path/to/image.jpg "direct upload"
 169
 170 Use the ``upload`` command to upload files to the media endpoint without
 171 creating a post::
 172
 173     $ ./bin/shpub.php upload /path/to/file.jpg /path/to/file2.jpg
 174     Uploaded file /path/to/file.jpg
 175     http://test.bogo/micropub-media-endpoint/1474362040.2941/file.jpg
 176     Uploaded file /path/to/file2.jpg
 177     http://test.bogo/micropub-media-endpoint/1474362040.3383/file2.jpg
 178
 179
 180 =========
 181 Debugging
 182 =========
 183 To debug ``shpub`` or your micropub endpoint, use the ``--debug`` option
 184 to see ``curl`` command equivalents to the shpub HTTP requests::
 185
 186     $ ./bin/shpub.php -s known -d note "a simple note"
 187     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'
 188     Post created at server
 189     http://known.bogo/2016/a-simple-note
 190
 191
 192 ===========
 193 About shpub
 194 ===========
 195 shpub's homepage is http://cweiske.de/shpub.htm
 196
 197
 198 Source code
 199 ===========
 200 shpub's source code is available from http://git.cweiske.de/shpub.git
 201 or the `mirror on github`__.
 202
 203 __ https://github.com/cweiske/shpub
 204
 205
 206 License
 207 =======
 208 shpub is licensed under the `AGPL v3 or later`__.
 209
 210 __ http://www.gnu.org/licenses/agpl.html
 211
 212
 213 Author
 214 ======
 215 shpub was written by `Christian Weiske`__.
 216
 217 __ http://cweiske.de/