diff --git a/README.md b/README.md index e6fd14b167e3354f05a889b0285d37340ce64e06..38795b10d8abd908d83adca30321c74d834c1ab9 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,10 @@ A tiny CLI to perform common operations on [HedgeDoc](https://github.com/hedgedoc/server) (the largest open-source fork of HackMD). -For more background, see the initial [discussion](https://github.com/hackmdio/codimd/issues/808) on the codimd repo. +For more background, see the initial [discussion](https://github.com/hackmdio/codimd/issues/808) 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/server` server)* +*(it may or may not be compatible with the `hedgedoc/hedgedoc` server)* ## Install @@ -34,7 +34,7 @@ hedgedoc import test.md ### Create/import a new note ```bash -$ codimd import <input_path> [note_id] # takes a local path to a text file, and an optional note id for the 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>`. @@ -42,7 +42,7 @@ You can open the new note on the server by going to `$HEDGEDOC_SERVER/<note_id>` ### Publish an existing note ```bash -$ codimd publish qhmNmwmxSmK1H2oJmkKBQQ # takes a <note_id> +$ 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>`. @@ -50,60 +50,60 @@ You can open the published note on the server by going to `$HEDGEDOC_SERVER/s/<p ### Export an existing note ```bash -$ codimd export --pdf qhmNmwmxSmK1H2oJmkKBQQ # takes a <note_id>, outputs to <note_id>.pdf by default -$ codimd export --md qhmNmwmxSmK1H2oJmkKBQQ my_note.md # or you can specify an output path explicitly -$ codimd export --html qhmNmwmxSmK1H2oJmkKBQQ -$ codimd export --slides qhmNmwmxSmK1H2oJmkKBQQ my_slides.zip +$ 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 ``` ### Authenticate and get notes history ```bash # optionally add the HEDGEDOC_COOKIES_FILE environment variable to specify -# where cookies will be stored. It defaults to ~/.config/codimd-cli/key.conf -$ export HEDGEDOC_COOKIES_FILE=~/.config/codimd-cli/key.conf +# where cookies will be stored. It defaults to ~/.config/hedgedoc-cli/key.conf +$ export HEDGEDOC_COOKIES_FILE=~/.config/hedgedoc-cli/key.conf ``` #### Authenticate with email ```bash -$ codimd login --email email@example.net p4sW0rD # takes an email and password as optional args -$ codimd login --email # or pass them via stdin prompt instead +$ 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 ```bash -$ codimd login --ldap username p4sW0rD # takes a username and a password as optional args -$ codimd login --ldap # or pass them via stdin prompt instead +$ hedgedoc login --ldap username p4sW0rD # takes a username and a password as optional args +$ hedgedoc login --ldap # or pass them via stdin prompt instead ``` #### Get auth status, history, and logout ```bash -$ codimd profile +$ hedgedoc profile You are logged in to a HedgeDoc server. HEDGEDOC_SERVER=https://hedgedoc.example.com -HEDGEDOC_COOKIES_FILE=/Users/someuser/.config/codimd/key.conf +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 -$ codimd history +$ hedgedoc history ID Title fCbvG5pdSYOLobNN1SDUhg Example-note-title ... -$ codimd logout +$ hedgedoc logout ``` -Your codimd auth session cookie is written to `$HEDGEDOC_COOKIES_FILE` (which defaults to `~/.config/codimd/key.conf`). +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: - your session expired - - the codimd server was restarted (which force-expires all sessions as a side-effect) - - the is`$HEDGEDOC_COOKIES_FILE` deleted, moved, or becomes unreadable by `codimd-cli` + - 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` ## API Endpoints @@ -124,14 +124,14 @@ These server endpoints are used by this project and can be unstable and undocume We'd love a PR for any one of these commands! - - `codimd edit <note_id> < new_content.md` - - `codimd inviteuser <email_to_invite>` - - `codimd chmod <permissions> <note_id>` - - `codimd chown <user> <note_id>` - - `codimd delete <note_id>` - - `codimd list --all` list all notes on the server by id: title - - `codimd list <user_email>` list notes for a given user by id: title - - `codimd search <query>` find a note ids matching a given query + - `hedgedoc edit <note_id> < new_content.md` + - `hedgedoc inviteuser <email_to_invite>` + - `hedgedoc chmod <permissions> <note_id>` + - `hedgedoc chown <user> <note_id>` + - `hedgedoc delete <note_id>` + - `hedgedoc list --all` list all notes on the server by id: title + - `hedgedoc list <user_email>` list notes for a given user by id: title + - `hedgedoc search <query>` find a note ids matching a given query ## Inspiration @@ -139,26 +139,26 @@ If you want to build something with this CLI, here are some ideas that the commu **Import/Export:** -- **[Tests for HedgeDoc](https://github.com/hackmdio/codimd/issues/22): write some easy tests with the codimd-cli** -- [Saving to local filesystem](https://github.com/hackmdio/codimd/issues/90): this is easy with `./codimd export` -- [Export to PDF](https://github.com/hackmdio/codimd/issues/33): `./codimd export --pdf <note_id> <output.pdf>` bam. -- [Arbitrary file upload](https://github.com/hackmdio/codimd/issues/261): we should support this with `./codimd import <file.extension>` -- [Export slides as PDF](https://github.com/hackmdio/codimd/issues/241) & https://github.com/hackmdio/codimd/issues/545: we should add this to `./codimd export --slides` once it's ready -- [Show all files in database](https://github.com/hackmdio/codimd/issues/640): `./codimd list --all` -- [Import/export file in GitHub repository](https://github.com/hackmdio/codimd/issues/218): `wget <file from github> > file.md; ./codimd import file.md` -- [API to download HTML](https://github.com/hackmdio/codimd/issues/515): works already `./codimd export --html <note_id> note.html` +- **[Tests for HedgeDoc](https://github.com/hackmdio/codimd/issues/22): write some easy tests with the hedgedoc-cli** +- [Saving to local filesystem](https://github.com/hackmdio/codimd/issues/90): this is easy with `./hedgedoc export` +- [Export to PDF](https://github.com/hackmdio/codimd/issues/33): `./hedgedoc export --pdf <note_id> <output.pdf>` bam. +- [Arbitrary file upload](https://github.com/hackmdio/codimd/issues/261): we should support this with `./hedgedoc import <file.extension>` +- [Export slides as PDF](https://github.com/hackmdio/codimd/issues/241) & https://github.com/hackmdio/codimd/issues/545: we should add this to `./hedgedoc export --slides` once it's ready +- [Show all files in database](https://github.com/hackmdio/codimd/issues/640): `./hedgedoc list --all` +- [Import/export file in GitHub repository](https://github.com/hackmdio/codimd/issues/218): `wget <file from github> > file.md; ./hedgedoc import file.md` +- [API to download HTML](https://github.com/hackmdio/codimd/issues/515): works already `./hedgedoc export --html <note_id> note.html` - [CLI for adding new note](https://github.com/hackmdio/codimd/pull/673): can be documented in the README with `hackmd` command -- ["Takeout" feature](https://github.com/hackmdio/codimd/issues/823): ability to download all user data with `./codimd export` +- ["Takeout" feature](https://github.com/hackmdio/codimd/issues/823): ability to download all user data with `./hedgedoc export` **Permission management:** -- [Support permission of invitee only](https://github.com/hackmdio/codimd/issues/35): `./codimd inviteuser --permissions r <user_email>` could work by first `chmod` and `chown`ing the note, then sending an email invite to that note -- [Find the notes by the owner](https://github.com/hackmdio/codimd/issues/653): `./codimd list <user_email>` works as a rudimentary API to do this form the command line +- [Support permission of invitee only](https://github.com/hackmdio/codimd/issues/35): `./hedgedoc inviteuser --permissions r <user_email>` could work by first `chmod` and `chown`ing the note, then sending an email invite to that note +- [Find the notes by the owner](https://github.com/hackmdio/codimd/issues/653): `./hedgedoc list <user_email>` works as a rudimentary API to do this form the command line - [Add user administration](https://github.com/hackmdio/codimd/issues/272): setup a script that creates all the users & their notes from .md files on disk, `chown` & `chmod`s them to their proper permissions, then invites all the users to join. Would be possible to run this on a timer to do regularly as well. **Sync backends:** -- [Import/Export with Github](https://github.com/hackmdio/codimd/issues/34): trigger `./codimd import|export` script via timer or webhook upon github file modification +- [Import/Export with Github](https://github.com/hackmdio/codimd/issues/34): trigger `./hedgedoc import|export` script via timer or webhook upon github file modification - [Import/Export with Evernote](https://github.com/hackmdio/codimd/issues/97): same deal as github/dropbox sync, write a script with import/export - [Support for ownCloud](https://github.com/hackmdio/codimd/issues/245): same deal as github/dropbox sync, write a script with import/export - [Support auto sync with dropbox](https://github.com/hackmdio/codimd/issues/124): write a script that does a full `import` and `export` or merge in whatever direction desired