search

hedgedoc / cli

A tiny CLI for HedgeDoc
GNU Affero General Public License v3.0
153 stars 37 forks source link
archiving backup-utility bash cli cli-app codimd codimd-cli hedgedoc markdown notes

readme

hedgedoc-cli

A tiny CLI to perform common operations on HedgeDoc (the largest open-source fork of HackMD).

For more background, see the initial discussion on the hackmd codimd repo.

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)

Installation

Dependencies

Instructions

Clone the repository.

$ git clone https://github.com/hedgedoc/cli

Enter the folder with the script.

$ cd cli/bin

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 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 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

# You can put this in .profile and/or .bashrc, too.
$ export HEDGEDOC_COOKIES_FILE=~/.config/hedgedoc/key.conf

Authenticate with email

$ hedgedoc login --email email@example.net p4sW0rD  # takes an email and password as optional args
$ hedgedoc login --email                            # or pass them via stdin prompt instead

Authenticate with LDAP

$ hedgedoc login --ldap username p4sW0rD            # takes a username and a password as optional args
$ hedgedoc login --ldap                             # or pass them via stdin prompt instead

Check if authentication works

If your authentication method is set up correctly the following commands will work.

Get auth status, history, and logout

$ hedgedoc profile
You are logged in to a HedgeDoc server.

HEDGEDOC_SERVER=https://hedgedoc.example.com
HEDGEDOC_COOKIES_FILE=/Users/someuser/.config/hedgedoc/key.conf

USER_NAME=alice
USER_ID=abc93e9b-bf57-490f-a4c6-0d7a842b7cd4
USER_PHOTO=https://cdn.libravatar.org/avatar/ba8b1ebe25440cd38748639eebdc8eaf?s=96

$ hedgedoc history
ID  Title
fCbvG5pdSYOLobNN1SDUhg  Example-note-title
...

$ hedgedoc logout

Your hedgedoc auth session cookie is written to $HEDGEDOC_COOKIES_FILE (which defaults to ~/.config/hedgedoc/key.conf).

You may need to log in again if:

Create/import a new note

$ 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 for more information.

Publish an existing note

$ 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

$ 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.

Help contribute!

We'd love a PR for any one of these commands!

Inspiration

If you want to build something with this CLI, here are some ideas that the community has requested:

Import/Export:

Permission management:

Sync backends: