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