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 The `github releases page <https://github.com/cweiske/shpub/releases>`_
  13 has self-contained ``.phar`` files that have all dependencies included.
  14
  15
  16 Dependencies
  17 ============
  18 When using the git version, you need to have the following dependencies
  19 installed on your system:
  20
  21 - PHP 5.4+
  22 - PEAR's `HTTP_Request2 <http://pear.php.net/package/HTTP_Request2>`_
  23 - PEAR's `MIME_Type <http://pear.php.net/package/MIME_Type>`_
  24 - PEAR's `NET_URL2 <http://pear.php.net/package/Net_URL2>`_
  25
  26
  27 =============
  28 Initial setup
  29 =============
  30 ::
  31
  32     $ ./bin/shpub.php connect http://mywebsite
  33
  34 Different user::
  35
  36     $ ./bin/shpub.php connect http://mywebsite http://mywebsite/user
  37
  38 If you pass a third parameter, then it will be the name of the connection.
  39 You can select a specific server/connection with ``-s`` on all commands.
  40
  41
  42 List configured servers/connections
  43 ===================================
  44 ::
  45
  46     $ ./bin/shpub.php server
  47     rr
  48     test
  49     anoweco.bogo
  50     local2
  51
  52 Also try ``server -v`` which lists server and user URLs.
  53
  54
  55 =============
  56 Post creation
  57 =============
  58 shpub has support for the following post types:
  59
  60 - `article <http://indieweb.org/article>`_
  61 - `bookmark <http://indieweb.org/bookmark>`_
  62 - `like <http://indieweb.org/like>`_
  63 - `note <http://indieweb.org/note>`_
  64 - `reply <http://indieweb.org/reply>`_
  65 - `repost <http://indieweb.org/repost>`_
  66 - `rsvp <http://indieweb.org/rsvp>`_
  67
  68 ``shpub`` sends data form-encoded by default.
  69 To send JSON requests, use the ``--json`` option.
  70
  71
  72 Create a like
  73 =============
  74 ::
  75
  76     $ ./bin/shpub.php like http://example.org/
  77     Like created at server
  78     http://anoweco.bogo/comment/23.htm
  79
  80 Create a reply
  81 ==============
  82 ::
  83
  84     $ ./bin/shpub.php reply http://example.org/ "Hey, cool!"
  85     Reply created at server
  86     http://anoweco.bogo/comment/42.htm
  87
  88
  89 Create a note
  90 =============
  91 A normal note::
  92
  93     $ ./bin/shpub.php note "oh this is cool!"
  94     Note created at server
  95     http://known.bogo/2016/oh-this-is-cool.htm
  96
  97 Note with an image::
  98
  99     $ ./bin/shpub.php note -f image.jpg "this is so cute"
 100     Note created at server
 101     http://known.bogo/2016/this-is-so-cute
 102
 103 You can use ``-f`` several times to upload multiple files.
 104
 105 URL image upload::
 106
 107     $ ./bin/shpub.php note -f http://example.org/1.jpg "img url!"
 108     Note created at server
 109     http://known.bogo/2016/img-url
 110
 111
 112 ===============
 113 Delete/Undelete
 114 ===============
 115 You may delete and restore posts on micropub servers::
 116
 117     $ ./bin/shpub.php delete http://known.bogo/2016/like
 118
 119 Restore a deleted post::
 120
 121     $ ./bin/shpub.php undelete http://known.bogo/2016/like
 122
 123
 124 =======
 125 Updates
 126 =======
 127 Existing posts can be modified if the `server supports this`__::
 128
 129     $ ./bin/shpub update --add category=foo category=bar\
 130                          --replace slug=differentslug\
 131                          --delete category=oldcat\
 132                          http://known.bogo/2016/post
 133
 134 __ https://indieweb.org/Micropub/Servers#Implementation_status
 135
 136
 137 ============
 138 File uploads
 139 ============
 140 Most post types allow file uploads. Simply use ``-f``::
 141
 142     $ ./bin/shpub.php note -f path/to/image.jpg "image test"
 143     Note created at server
 144     http://known.bogo/2016/image-test
 145
 146 The media endpoint is used automatically if the micropub endpoint has one.
 147 To force shpub to directly upload the file and skip the media endpoint,
 148 use the ``--direct-upload`` option::
 149
 150     $ ./bin/shpub.php note --direct-upload -f path/to/image.jpg "direct upload"
 151
 152 Use the ``upload`` command to upload files to the media endpoint without
 153 creating a post::
 154
 155     $ ./bin/shpub.php upload /path/to/file.jpg /path/to/file2.jpg
 156     Uploaded file /path/to/file.jpg
 157     http://test.bogo/micropub-media-endpoint/1474362040.2941/file.jpg
 158     Uploaded file /path/to/file2.jpg
 159     http://test.bogo/micropub-media-endpoint/1474362040.3383/file2.jpg
 160
 161
 162 =========
 163 Debugging
 164 =========
 165 To debug ``shpub`` or your micropub endpoint, use the ``--debug`` option
 166 to see ``curl`` command equivalents to the shpub HTTP requests::
 167
 168     $ ./bin/shpub.php -s known -d note "a simple note"
 169     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'
 170     Post created at server
 171     http://known.bogo/2016/a-simple-note
 172
 173
 174 ===========
 175 About shpub
 176 ===========
 177
 178 Source code
 179 ===========
 180 shpub's source code is available from http://git.cweiske.de/shpub.git
 181 or the `mirror on github`__.
 182
 183 __ https://github.com/cweiske/shpub
 184
 185
 186 License
 187 =======
 188 shpub is licensed under the `AGPL v3 or later`__.
 189
 190 __ http://www.gnu.org/licenses/agpl.html
 191
 192
 193 Author
 194 ======
 195 shpub was written by `Christian Weiske`__.
 196
 197 __ http://cweiske.de/