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 Installation
  22 ============
  23 After downloading ``shpub-x.y.z.phar``, you can either use it directly::
  24
  25     $ php /path/to/shpub-x.y.z.phar --version
  26
  27 or make it more easily accessible::
  28
  29     $ mv /path/to/shpub-x.y.z.phar /usr/local/bin/shpub
  30     $ chmod +x /usr/local/bin/shpub
  31     $ shpub --version
  32
  33 You might need ``sudo`` to be able to copy it into the ``/usr/local/bin/``
  34 directory.
  35
  36 If you're running from the git checkout, start it as follows::
  37
  38     $ ./bin/shpub.php --version
  39
  40
  41 Dependencies
  42 ============
  43 When using the git version, you need to have the following dependencies
  44 installed on your system:
  45
  46 - PHP 5.4+
  47 - PEAR's `Console_CommandLine <http://pear.php.net/package/Console_CommandLine>`_
  48 - PEAR's `HTTP_Request2 <http://pear.php.net/package/HTTP_Request2>`_
  49 - PEAR's `MIME_Type <http://pear.php.net/package/MIME_Type>`_
  50 - PEAR's `NET_URL2 <http://pear.php.net/package/Net_URL2>`_
  51
  52
  53 =============
  54 Initial setup
  55 =============
  56 ::
  57
  58     $ shpub connect http://mywebsite
  59
  60 In case there are multiple users on the same server::
  61
  62     $ shpub connect http://sharedwebsite http://shareswebsite/user
  63
  64 If you pass a third parameter, then that will be the name of the connection.
  65 You can select a specific server/connection with ``-s`` on all commands.
  66
  67
  68 List configured servers/connections
  69 ===================================
  70 ::
  71
  72     $ shpub server
  73     rr
  74     test
  75     anoweco.bogo
  76     local2
  77
  78 Also try ``server -v`` which lists server and user URLs.
  79
  80
  81 =============
  82 Post creation
  83 =============
  84 shpub has support for the following post types:
  85
  86 - `article <http://indieweb.org/article>`_
  87 - `bookmark <http://indieweb.org/bookmark>`_
  88 - `like <http://indieweb.org/like>`_
  89 - `note <http://indieweb.org/note>`_
  90 - `reply <http://indieweb.org/reply>`_
  91 - `repost <http://indieweb.org/repost>`_
  92 - `rsvp <http://indieweb.org/rsvp>`_
  93
  94 By default ``shpub`` sends data form-encoded.
  95 To send JSON requests, use the ``--json`` option.
  96
  97
  98 Create a like
  99 =============
 100 ::
 101
 102     $ shpub like http://example.org/
 103     Like created at server
 104     http://anoweco.bogo/comment/23.htm
 105
 106 Create a reply
 107 ==============
 108 ::
 109
 110     $ shpub reply http://example.org/ "Hey, cool!"
 111     Reply created at server
 112     http://anoweco.bogo/comment/42.htm
 113
 114
 115 Create a note
 116 =============
 117 A normal note::
 118
 119     $ shpub note "oh this is cool!"
 120     Note created at server
 121     http://known.bogo/2016/oh-this-is-cool.htm
 122
 123 Note with an image::
 124
 125     $ shpub note -f image.jpg "this is so cute"
 126     Note created at server
 127     http://known.bogo/2016/this-is-so-cute
 128
 129 You can use ``-f`` several times to upload multiple files.
 130
 131 URL image upload::
 132
 133     $ shpub note -f http://example.org/1.jpg "img url!"
 134     Note created at server
 135     http://known.bogo/2016/img-url
 136
 137 Load note content from a file::
 138
 139     $ shpub note - < /path/to/file.txt
 140     Note created at server
 141     http://known.bogo/2017/some-note
 142
 143
 144 Custom post types
 145 =================
 146 You may create custom post types with the ``x`` command.
 147 This is useful if your micropub endpoint supports additional types,
 148 like `known <http://withknown.com/>`__'s
 149 `"annotation" type <https://cweiske.de/tagebuch/micropub-comments-known.htm>`__
 150 (comments and likes for posts).
 151
 152 Create a comment to a known post::
 153
 154     $ shpub x annotation\
 155         -x url=http://known.bogo/2016/example-domain-1\
 156         -x type=reply\
 157         -x username=barryf\
 158         -x userurl=http://example.org/~barryf\
 159         -x userphoto=http://example.org/~barryf/avatar.jpg\
 160         -x content="There is a typo in paragraph 1. 'Fou' should be 'Foo'"
 161
 162
 163 ===============
 164 Delete/Undelete
 165 ===============
 166 You may delete and restore posts on micropub servers::
 167
 168     $ shpub delete http://known.bogo/2016/like
 169
 170 Restore a deleted post::
 171
 172     $ shpub undelete http://known.bogo/2016/like
 173
 174
 175 =======
 176 Updates
 177 =======
 178 Existing posts can be modified if the `server supports this`__::
 179
 180     $ ./bin/shpub update --add category=foo category=bar\
 181                          --replace slug=differentslug\
 182                          --delete category=oldcat\
 183                          http://known.bogo/2016/post
 184
 185 __ https://indieweb.org/Micropub/Servers#Implementation_status
 186
 187
 188 ===================
 189 Syndication targets
 190 ===================
 191 You may list the syndication targets defined on the server::
 192
 193     $ shpub targets
 194     IndieNews
 195      https://news.indieweb.org/en
 196
 197 Then specify it when creating a post::
 198
 199     $ shpub article -x mp-syndicate-to=https://news.indieweb.org/en title text
 200
 201 ============
 202 File uploads
 203 ============
 204 Most post types allow file uploads. Simply use ``-f``::
 205
 206     $ shpub note -f path/to/image.jpg "image test"
 207     Note created at server
 208     http://known.bogo/2016/image-test
 209
 210 The media endpoint is used automatically if the micropub endpoint has one.
 211 To force ``shpub`` to directly upload the file and skip the media endpoint,
 212 use the ``--direct-upload`` option::
 213
 214     $ shpub note --direct-upload -f path/to/image.jpg "direct upload"
 215
 216 Use the ``upload`` command to upload files to the media endpoint without
 217 creating a post::
 218
 219     $ shpub upload /path/to/file.jpg /path/to/file2.jpg
 220     Uploaded file /path/to/file.jpg
 221     http://test.bogo/micropub-media-endpoint/1474362040.2941/file.jpg
 222     Uploaded file /path/to/file2.jpg
 223     http://test.bogo/micropub-media-endpoint/1474362040.3383/file2.jpg
 224
 225
 226 =========
 227 Debugging
 228 =========
 229 To debug ``shpub`` or your micropub endpoint, use the ``--debug`` option
 230 to see ``curl`` command equivalents to the shpub HTTP requests::
 231
 232     $ shpub -s known -d note "a simple note"
 233     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'
 234     Post created at server
 235     http://known.bogo/2016/a-simple-note
 236
 237
 238 See curl commands only
 239 ======================
 240 You may use the ``--dry-run`` option to make shpub not send any modifying
 241 HTTP requests (e.g. POST and PUT).
 242
 243 Together with ``--debug`` you can use this to get curl commands without sending
 244 anything to the server::
 245
 246     $ shpub --debug --dry-run like example.org
 247     curl -X POST -H 'User-Agent: shpub' -H 'Content-Type: application/x-www-form-urlencoded' -H 'Authorization: Bearer cafe' -d 'h=entry' -d 'like-of=http://example.org' 'http://anoweco.bogo/micropub.php'
 248     Like created at server
 249     http://example.org/fake-response
 250
 251
 252 Server information
 253 ==================
 254 To see which server, user and endpoint URLs ``shpub`` uses, pass the
 255 server name to the ``server`` command::
 256
 257     $ shpub server commentpara.de
 258     commentpara.de
 259      URL:   http://commentpara.de
 260      User:  https://commentpara.de/user/3.htm
 261      Endpoints:
 262       micropub:      https://commentpara.de/micropub.php
 263       media:
 264       token:         https://commentpara.de/token.php
 265       authorization: https://commentpara.de/auth.php
 266
 267
 268 ===========
 269 Development
 270 ===========
 271
 272 Releasing a new version
 273 =======================
 274
 275 #. Add notes to ``ChangeLog``
 276 #. Update version number in ``build.xml`` and ``src/shpub/Cli.php``
 277 #. Run ``phing``
 278 #. Commit and tag the version
 279 #. In the ``cweiske.de`` directory, run ``./scripts/update-shpub.sh``
 280
 281
 282 ===========
 283 About shpub
 284 ===========
 285 shpub's homepage is http://cweiske.de/shpub.htm
 286
 287
 288 Source code
 289 ===========
 290 shpub's source code is available from http://git.cweiske.de/shpub.git
 291 or the `mirror on github`__.
 292
 293 __ https://github.com/cweiske/shpub
 294
 295
 296 License
 297 =======
 298 shpub is licensed under the `AGPL v3 or later`__.
 299
 300 __ http://www.gnu.org/licenses/agpl.html
 301
 302
 303 Author
 304 ======
 305 shpub was written by `Christian Weiske`__.
 306
 307 __ http://cweiske.de/