merge the latest master.

Author: mirguest

README.md

@@ -7,61 +7,66 @@ For more background, see the initial [discussion](https://github.com/hackmdio/co
 *There is an alternative, TypeScript-based CodiMD CLI for `hackmdio/codimd` maintained by the HackMD team here: https://github.com/hackmdio/codimd-cli.*  
 *(it may or may not be compatible with the `hedgedoc/hedgedoc` server)*
 
-## Install
+## Installation
 
-Dependencies:
- - A HedgeDoc server running somewhere
- - `curl` (install via `apt install curl` or `brew install curl` on Mac)
- - `wget` (install via `apt install wget` or `brew install wget` on Mac)
- - `jq` (install via `apt install jq` or `brew install jq` on Mac)
+### Dependencies
 
-```bash
-git clone https://github.com/hedgedoc/cli
-cd cli/bin
-# optionally symlink the hedgedoc script somewhere into your $PATH
-ln -s $PWD/hedgedoc /usr/local/bin/hedgedoc
-
-# set HEDGEDOC_SERVER environment variable to your server's URL
-# it defaults to http://127.0.0.1:3000
-export HEDGEDOC_SERVER='https://hedgedoc.example.com'  
-
-# Test by creating a new note
-hedgedoc login --email
-hedgedoc import test.md
-```
+- A HedgeDoc server running somewhere
+- `curl` (install via `apt install curl` or `brew install curl` on Mac)
+- `wget` (install via `apt install wget` or `brew install wget` on Mac)
+- `jq` (install via `apt install jq` or `brew install jq` on Mac)
 
-## Documentation
+### Instructions
 
-### Create/import a new note
-```bash
-$ hedgedoc import <input_path> [note_id]     # takes a local path to a text file, and an optional note id for the new note
-qhmNmwmxSmK1H2oJmkKBQQ                     # returns <note_id> on success
-```
-You can open the new note on the server by going to `$HEDGEDOC_SERVER/<note_id>`.
+Clone the repository.
 
-### Publish an existing note
+    $ git clone https://github.com/hedgedoc/cli
 
-```bash
-$ hedgedoc publish qhmNmwmxSmK1H2oJmkKBQQ   # takes a <note_id>
-S1ok9no3f                                 # returns public note id
-```
-You can open the published note on the server by going to `$HEDGEDOC_SERVER/s/<public_note_id>`.
+Enter the folder with the script.
 
-### Export an existing note
+    $ cd cli/bin
 
-```bash
-$ hedgedoc export --pdf qhmNmwmxSmK1H2oJmkKBQQ             # takes a <note_id>, outputs to <note_id>.pdf by default
-$ hedgedoc export --md qhmNmwmxSmK1H2oJmkKBQQ my_note.md   # or you can specify an output path explicitly
-$ hedgedoc export --html qhmNmwmxSmK1H2oJmkKBQQ
-$ hedgedoc export --slides qhmNmwmxSmK1H2oJmkKBQQ my_slides.zip
-```
+Optionally symlink the hedgedoc script somewhere into your $PATH to make it globally accessible. Otherwise you will have to provide the path to the script manually. This command might need admin rights (sudo)!
+
+    $ ln -s $PWD/hedgedoc /usr/local/bin/hedgedoc
+
+Check if the new command exists. You should see the documentation 
+
+    $ hedgedoc
+
+Set `HEDGEDOC_SERVER` environment variable to your server's URL. It defaults to `http://127.0.0.1:3000` Do this once on the command line or persist it in `.profile` and/or `.bashrc`.
+
+    $ export HEDGEDOC_SERVER='https://hedgedoc.example.com'  
+
+If you added the variable to `.profile` or `.bashrc`,  re-open the terminal to read the new variable.
+
+Test your configuration by creating a new note with FREELY access and no login required. You will receive the generated `<note_id>` for the document like `3jXcabSfSNesbH6KT72ieg`.
+
+**Caution: You won't have the right to delete the new document if not authenticated!**
+
+    $ echo "# HedgeDoc!" > test.md
+    $ hedgedoc import test.md
+
+Check for the document in the browser by concatenating the
+ address of your server and the `<note_id>`.
+
+## Configuration and usage
+
+### Variants of authentication
+
+It's not necessary to authenticate against the server in order to make use of `hedgedoc-cli`. But without authentication you won't have access to the non-FREELY documents and everything that's accessible behind the login.
 
-### Authenticate and get notes history
+#### Authenticate with cookie
+
+Authentication with a cookie is so far the only way if you login with GitLab and the like. Use browser extensions like [Get cookies.txt](https://chrome.google.com/webstore/detail/get-cookiestxt/bgaddhkoddajcdgocldbbfleckgcbcid) to store the cookie in `key.conf`.
+
+Possible you have many lines in `key.conf`. You only need the line with `connect.sid` followed by a long hash!
+
+Optionally add the HEDGEDOC_COOKIES_FILE environment variable to specify where cookies will be stored. It defaults to `~/.config/hedgedoc/key.conf`
 
 ```bash
-# optionally add the HEDGEDOC_COOKIES_FILE environment variable to specify
-# where cookies will be stored. It defaults to ~/.config/hedgedoc-cli/key.conf
-$ export HEDGEDOC_COOKIES_FILE=~/.config/hedgedoc-cli/key.conf
+# You can put this in .profile and/or .bashrc, too.
+$ export HEDGEDOC_COOKIES_FILE=~/.config/hedgedoc/key.conf
 ```
 #### Authenticate with email
 
@@ -77,7 +82,11 @@ $ hedgedoc login --ldap username p4sW0rD            # takes a username and a pas
 $ hedgedoc login --ldap                             # or pass them via stdin prompt instead
 ```
 
-#### Get auth status, history, and logout
+#### Check if authentication works
+
+If your authentication method is set up correctly the following commands will work.
+
+### Get auth status, history, and logout
 
 ```bash
 $ hedgedoc profile
@@ -105,6 +114,38 @@ You may need to log in again if:
  - the hedgedoc server was restarted (which force-expires all sessions as a side-effect)
  - the  is`$HEDGEDOC_COOKIES_FILE` deleted, moved, or becomes unreadable by `hedgedoc-cli`
 
+### Create/import a new note
+
+```bash
+$ hedgedoc import <input_path> [note_id]     # takes a local path to a text file, and an optional note id for the new note
+qhmNmwmxSmK1H2oJmkKBQQ                     # returns <note_id> on success
+```
+
+You can open the new note on the server by going to `$HEDGEDOC_SERVER/<note_id>`.
+
+The optional `note_id` is only available on servers with `allowFreeURL`
+enabled.
+Check the [documentation](https://docs.hedgedoc.org/configuration/#users-and-privileges)
+for more information.
+
+### Publish an existing note
+
+```bash
+$ hedgedoc publish qhmNmwmxSmK1H2oJmkKBQQ   # takes a <note_id>
+S1ok9no3f                                 # returns public note id
+```
+You can open the published note on the server by going to `$HEDGEDOC_SERVER/s/<public_note_id>`.
+
+### Export an existing note
+
+```bash
+$ hedgedoc export --pdf qhmNmwmxSmK1H2oJmkKBQQ             # takes a <note_id>, outputs to <note_id>.pdf by default
+$ hedgedoc export --md qhmNmwmxSmK1H2oJmkKBQQ my_note.md   # or you can specify an output path explicitly
+$ hedgedoc export --html qhmNmwmxSmK1H2oJmkKBQQ
+$ hedgedoc export --slides qhmNmwmxSmK1H2oJmkKBQQ my_slides.zip
+```
+
+
 ## API Endpoints
 
 These server endpoints are used by this project and can be unstable and undocumented, but may be of use if you're developing your own projects that need API access to HedgeDoc.

bin/hedgedoc

@@ -81,7 +81,7 @@ Config:
     \$HEDGEDOC_CONFIG_DIR   (defaults to $XDG_CONFIG_HOME/$SCRIPTNAME)
     \$HEDGEDOC_COOKIES_FILE (defaults to \$HEDGEDOC_CONFIG_DIR/key.conf)
 
-Usage examples: 
+Usage examples:
 
     \$ export HEDGEDOC_SERVER='$HEDGEDOC_SERVER'
     \$ export HEDGEDOC_COOKIES_FILE=$HEDGEDOC_COOKIES_FILE
@@ -178,7 +178,7 @@ function import_note() {
         echo "Hint: You may need to run '$SCRIPTNAME login' to authenticate first." >&2
         return 2
     fi
-    echo "$note_id" 
+    echo "$note_id"
 }
 
 function export_note() {
@@ -234,7 +234,7 @@ function export_note() {
             output_path="${output_path:-$note_id.zip}"
             # hack: there is no way to get slide output as zipfile directly.
             #       we dump it to folder of html files first then zip it.
-            
+
             # check for any existing conflicting file/dir that wget downloads
             local temp_folder_name="$(
                 echo "$HEDGEDOC_SERVER" \
@@ -287,6 +287,18 @@ function user_login_helper_gitlab() {
     bash ${HELPER_SCRIPT_DIR}/login-hedgedoc-via-gitlab.sh $username $password >& /dev/null
 }
 
+
+function backup_all_notes() {
+    output_path="${1:-archive.zip}"
+
+    curl \
+        --silent \
+        --cookie "$HEDGEDOC_COOKIES_FILE" \
+        --output "$output_path" \
+        "${HEDGEDOC_SERVER}/me/export" \
+    && echo "$output_path"
+}
+
 function user_login() {
     local method="${1#--}" username="${2:-}" password="${3:-}" username_arg=""
     case "$method" in
@@ -381,7 +393,7 @@ function user_profile() {
 
 function user_history() {
     assert_is_authenticated
-    
+
     curl \
         --silent \
         --cookie "$HEDGEDOC_COOKIES_FILE" \
@@ -422,6 +434,9 @@ function main() {
         export)
             export_note "${1:-}" "${2:-}" "${3:-}"
             ;;
+        backup)
+            backup_all_notes "${1:-}"
+            ;;
         delete)
             delete_note "${1:-}"
             ;;
@@ -448,7 +463,7 @@ function main() {
 # Do the usage function of no Command line arguments are given.
 if [[ $# -eq 0 ]]; then
   set -- "help"
-fi  
+fi
 
 # Allow importing funcs without running main by using `source ./bin/hedgedoc --import`
 if [[ "${1:-}" != "--import" ]]; then