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