|
1 | | -# codimd-cli |
| 1 | +# hedgedoc-cli |
2 | 2 |
|
3 | | -A tiny CLI to perform common operations on [CodiMD](https://github.com/codimd/server) (the largest open-source fork of HackMD). |
| 3 | +A tiny CLI to perform common operations on [HedgeDoc](https://github.com/hedgedoc/server) (the largest open-source fork of HackMD). |
4 | 4 |
|
5 | | -For more background, see the initial [discussion](https://github.com/hackmdio/codimd/issues/808) on the main codimd repo. |
| 5 | +For more background, see the initial [discussion](https://github.com/hackmdio/codimd/issues/808) on the hackmd codimd repo. |
6 | 6 |
|
7 | 7 | *There is an alternative, TypeScript-based CodiMD CLI for `hackmdio/codimd` maintained by the HackMD team here: https://github.com/hackmdio/codimd-cli.* |
8 | | -*(it may or may not be compatible with the `codimd/server` server that this project`codimd/cli` is designed for)* |
| 8 | +*(it may or may not be compatible with the `hedgedoc/hedgedoc` server)* |
9 | 9 |
|
10 | 10 | ## Install |
11 | 11 |
|
12 | 12 | Dependencies: |
13 | | - - A CodiMD server running somewhere |
| 13 | + - A HedgeDoc server running somewhere |
14 | 14 | - `curl` (install via `apt install curl` or `brew install curl` on Mac) |
15 | 15 | - `wget` (install via `apt install wget` or `brew install wget` on Mac) |
16 | 16 | - `jq` (install via `apt install jq` or `brew install jq` on Mac) |
17 | 17 |
|
18 | 18 | ```bash |
19 | | -git clone https://github.com/codimd/cli |
| 19 | +git clone https://github.com/hedgedoc/cli |
20 | 20 | cd cli/bin |
21 | | -# optionally symlink the codimd script somewhere into your $PATH |
22 | | -ln -s $PWD/codimd /usr/local/bin/codimd |
| 21 | +# optionally symlink the hedgedoc script somewhere into your $PATH |
| 22 | +ln -s $PWD/hedgedoc /usr/local/bin/hedgedoc |
23 | 23 |
|
24 | | -# set CODIMD_SERVER environment variable to your server's URL |
| 24 | +# set HEDGEDOC_SERVER environment variable to your server's URL |
25 | 25 | # it defaults to http://127.0.0.1:3000 |
26 | | -export CODIMD_SERVER='https://codimd.example.com' |
| 26 | +export HEDGEDOC_SERVER='https://hedgedoc.example.com' |
27 | 27 |
|
28 | 28 | # Test by creating a new note |
29 | | -codimd login --email |
30 | | -codimd import test.md |
| 29 | +hedgedoc login --email |
| 30 | +hedgedoc import test.md |
31 | 31 | ``` |
32 | 32 |
|
33 | 33 | ## Documentation |
34 | 34 |
|
35 | 35 | ### Create/import a new note |
36 | 36 | ```bash |
37 | | -$ codimd import <input_path> [note_id] # takes a local path to a text file, and an optional note id for the new note |
| 37 | +$ hedgedoc import <input_path> [note_id] # takes a local path to a text file, and an optional note id for the new note |
38 | 38 | qhmNmwmxSmK1H2oJmkKBQQ # returns <note_id> on success |
39 | 39 | ``` |
40 | | -You can open the new note on the server by going to `$CODIMD_SERVER/<note_id>`. |
| 40 | +You can open the new note on the server by going to `$HEDGEDOC_SERVER/<note_id>`. |
41 | 41 |
|
42 | 42 | ### Publish an existing note |
43 | 43 |
|
44 | 44 | ```bash |
45 | | -$ codimd publish qhmNmwmxSmK1H2oJmkKBQQ # takes a <note_id> |
| 45 | +$ hedgedoc publish qhmNmwmxSmK1H2oJmkKBQQ # takes a <note_id> |
46 | 46 | S1ok9no3f # returns public note id |
47 | 47 | ``` |
48 | | -You can open the published note on the server by going to `$CODIMD_SERVER/s/<public_note_id>`. |
| 48 | +You can open the published note on the server by going to `$HEDGEDOC_SERVER/s/<public_note_id>`. |
49 | 49 |
|
50 | 50 | ### Export an existing note |
51 | 51 |
|
52 | 52 | ```bash |
53 | | -$ codimd export --pdf qhmNmwmxSmK1H2oJmkKBQQ # takes a <note_id>, outputs to <note_id>.pdf by default |
54 | | -$ codimd export --md qhmNmwmxSmK1H2oJmkKBQQ my_note.md # or you can specify an output path explicitly |
55 | | -$ codimd export --html qhmNmwmxSmK1H2oJmkKBQQ |
56 | | -$ codimd export --slides qhmNmwmxSmK1H2oJmkKBQQ my_slides.zip |
| 53 | +$ hedgedoc export --pdf qhmNmwmxSmK1H2oJmkKBQQ # takes a <note_id>, outputs to <note_id>.pdf by default |
| 54 | +$ hedgedoc export --md qhmNmwmxSmK1H2oJmkKBQQ my_note.md # or you can specify an output path explicitly |
| 55 | +$ hedgedoc export --html qhmNmwmxSmK1H2oJmkKBQQ |
| 56 | +$ hedgedoc export --slides qhmNmwmxSmK1H2oJmkKBQQ my_slides.zip |
57 | 57 | ``` |
58 | 58 |
|
59 | 59 | ### Authenticate and get notes history |
60 | 60 |
|
61 | 61 | ```bash |
62 | | -# optionally add the CODIMD_COOKIES_FILE environment variable to specify |
63 | | -# where cookies will be stored. It defaults to ~/.config/codimd-cli/key.conf |
64 | | -$ export CODIMD_COOKIES_FILE=~/.config/codimd-cli/key.conf |
| 62 | +# optionally add the HEDGEDOC_COOKIES_FILE environment variable to specify |
| 63 | +# where cookies will be stored. It defaults to ~/.config/hedgedoc-cli/key.conf |
| 64 | +$ export HEDGEDOC_COOKIES_FILE=~/.config/hedgedoc-cli/key.conf |
65 | 65 | ``` |
66 | 66 | #### Authenticate with email |
67 | 67 |
|
68 | 68 | ```bash |
69 | | -$ codimd login --email [email protected] p4sW0rD # takes an email and password as optional args |
70 | | -$ codimd login --email # or pass them via stdin prompt instead |
| 69 | +$ hedgedoc login --email [email protected] p4sW0rD # takes an email and password as optional args |
| 70 | +$ hedgedoc login --email # or pass them via stdin prompt instead |
71 | 71 | ``` |
72 | 72 |
|
73 | 73 | #### Authenticate with LDAP |
74 | 74 |
|
75 | 75 | ```bash |
76 | | -$ codimd login --ldap username p4sW0rD # takes a username and a password as optional args |
77 | | -$ codimd login --ldap # or pass them via stdin prompt instead |
| 76 | +$ hedgedoc login --ldap username p4sW0rD # takes a username and a password as optional args |
| 77 | +$ hedgedoc login --ldap # or pass them via stdin prompt instead |
78 | 78 | ``` |
79 | 79 |
|
80 | 80 | #### Get auth status, history, and logout |
81 | 81 |
|
82 | 82 | ```bash |
83 | | -$ codimd profile |
84 | | -You are logged in to a CodiMD server. |
| 83 | +$ hedgedoc profile |
| 84 | +You are logged in to a HedgeDoc server. |
85 | 85 |
|
86 | | -CODIMD_SERVER=https://codimd.example.com |
87 | | -CODIMD_COOKIES_FILE=/Users/someuser/.config/codimd/key.conf |
| 86 | +HEDGEDOC_SERVER=https://hedgedoc.example.com |
| 87 | +HEDGEDOC_COOKIES_FILE=/Users/someuser/.config/hedgedoc/key.conf |
88 | 88 |
|
89 | 89 | USER_NAME=alice |
90 | 90 | USER_ID=abc93e9b-bf57-490f-a4c6-0d7a842b7cd4 |
91 | 91 | USER_PHOTO=https://cdn.libravatar.org/avatar/ba8b1ebe25440cd38748639eebdc8eaf?s=96 |
92 | 92 |
|
93 | | -$ codimd history |
| 93 | +$ hedgedoc history |
94 | 94 | ID Title |
95 | 95 | fCbvG5pdSYOLobNN1SDUhg Example-note-title |
96 | 96 | ... |
97 | 97 |
|
98 | | -$ codimd logout |
| 98 | +$ hedgedoc logout |
99 | 99 | ``` |
100 | 100 |
|
101 | | -Your codimd auth session cookie is written to `$CODIMD_COOKIES_FILE` (which defaults to `~/.config/codimd/key.conf`). |
| 101 | +Your hedgedoc auth session cookie is written to `$HEDGEDOC_COOKIES_FILE` (which defaults to `~/.config/hedgedoc/key.conf`). |
102 | 102 |
|
103 | 103 | You may need to log in again if: |
104 | 104 | - your session expired |
105 | | - - the codimd server was restarted (which force-expires all sessions as a side-effect) |
106 | | - - the is`$CODIMD_COOKIES_FILE` deleted, moved, or becomes unreadable by `codimd-cli` |
| 105 | + - the hedgedoc server was restarted (which force-expires all sessions as a side-effect) |
| 106 | + - the is`$HEDGEDOC_COOKIES_FILE` deleted, moved, or becomes unreadable by `hedgedoc-cli` |
107 | 107 |
|
108 | 108 | ## API Endpoints |
109 | 109 |
|
110 | | -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 CodiMD. |
| 110 | +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. |
111 | 111 |
|
112 | | - - `https://<codimd_server>/login` |
113 | | - - `https://<codimd_server>/logout` |
114 | | - - `https://<codimd_server>/me` |
115 | | - - `https://<codimd_server>/history` (requires auth) |
116 | | - - `https://<codimd_server>/new` |
117 | | - - `https://<codimd_server>/new/<note_id>` |
118 | | - - `https://<codimd_server>/<note_id>/publish` |
119 | | - - `https://<codimd_server>/<note_id>/download` |
120 | | - - `https://<codimd_server>/<note_id>/pdf` |
121 | | - - `https://<codimd_server>/<note_id>/slide` |
| 112 | + - `https://<hedgedoc_server>/login` |
| 113 | + - `https://<hedgedoc_server>/logout` |
| 114 | + - `https://<hedgedoc_server>/me` |
| 115 | + - `https://<hedgedoc_server>/history` (requires auth) |
| 116 | + - `https://<hedgedoc_server>/new` |
| 117 | + - `https://<hedgedoc_server>/new/<note_id>` |
| 118 | + - `https://<hedgedoc_server>/<note_id>/publish` |
| 119 | + - `https://<hedgedoc_server>/<note_id>/download` |
| 120 | + - `https://<hedgedoc_server>/<note_id>/pdf` |
| 121 | + - `https://<hedgedoc_server>/<note_id>/slide` |
122 | 122 |
|
123 | 123 | ## Help contribute! |
124 | 124 |
|
125 | 125 | We'd love a PR for any one of these commands! |
126 | 126 |
|
127 | | - - `codimd edit <note_id> < new_content.md` |
128 | | - - `codimd inviteuser <email_to_invite>` |
129 | | - - `codimd chmod <permissions> <note_id>` |
130 | | - - `codimd chown <user> <note_id>` |
131 | | - - `codimd delete <note_id>` |
132 | | - - `codimd list --all` list all notes on the server by id: title |
133 | | - - `codimd list <user_email>` list notes for a given user by id: title |
134 | | - - `codimd search <query>` find a note ids matching a given query |
| 127 | + - `hedgedoc edit <note_id> < new_content.md` |
| 128 | + - `hedgedoc inviteuser <email_to_invite>` |
| 129 | + - `hedgedoc chmod <permissions> <note_id>` |
| 130 | + - `hedgedoc chown <user> <note_id>` |
| 131 | + - `hedgedoc delete <note_id>` |
| 132 | + - `hedgedoc list --all` list all notes on the server by id: title |
| 133 | + - `hedgedoc list <user_email>` list notes for a given user by id: title |
| 134 | + - `hedgedoc search <query>` find a note ids matching a given query |
135 | 135 |
|
136 | 136 | ## Inspiration |
137 | 137 |
|
138 | 138 | If you want to build something with this CLI, here are some ideas that the community has requested: |
139 | 139 |
|
140 | 140 | **Import/Export:** |
141 | 141 |
|
142 | | -- **[Tests for CodiMD](https://github.com/hackmdio/codimd/issues/22): write some easy tests with the codimd-cli** |
143 | | -- [Saving to local filesystem](https://github.com/hackmdio/codimd/issues/90): this is easy with `./codimd export` |
144 | | -- [Export to PDF](https://github.com/hackmdio/codimd/issues/33): `./codimd export --pdf <note_id> <output.pdf>` bam. |
145 | | -- [Arbitrary file upload](https://github.com/hackmdio/codimd/issues/261): we should support this with `./codimd import <file.extension>` |
146 | | -- [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 |
147 | | -- [Show all files in database](https://github.com/hackmdio/codimd/issues/640): `./codimd list --all` |
148 | | -- [Import/export file in GitHub repository](https://github.com/hackmdio/codimd/issues/218): `wget <file from github> > file.md; ./codimd import file.md` |
149 | | -- [API to download HTML](https://github.com/hackmdio/codimd/issues/515): works already `./codimd export --html <note_id> note.html` |
| 142 | +- **[Tests for HedgeDoc](https://github.com/hackmdio/codimd/issues/22): write some easy tests with the hedgedoc-cli** |
| 143 | +- [Saving to local filesystem](https://github.com/hackmdio/codimd/issues/90): this is easy with `./hedgedoc export` |
| 144 | +- [Export to PDF](https://github.com/hackmdio/codimd/issues/33): `./hedgedoc export --pdf <note_id> <output.pdf>` bam. |
| 145 | +- [Arbitrary file upload](https://github.com/hackmdio/codimd/issues/261): we should support this with `./hedgedoc import <file.extension>` |
| 146 | +- [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 |
| 147 | +- [Show all files in database](https://github.com/hackmdio/codimd/issues/640): `./hedgedoc list --all` |
| 148 | +- [Import/export file in GitHub repository](https://github.com/hackmdio/codimd/issues/218): `wget <file from github> > file.md; ./hedgedoc import file.md` |
| 149 | +- [API to download HTML](https://github.com/hackmdio/codimd/issues/515): works already `./hedgedoc export --html <note_id> note.html` |
150 | 150 | - [CLI for adding new note](https://github.com/hackmdio/codimd/pull/673): can be documented in the README with `hackmd` command |
151 | | -- ["Takeout" feature](https://github.com/hackmdio/codimd/issues/823): ability to download all user data with `./codimd export` |
| 151 | +- ["Takeout" feature](https://github.com/hackmdio/codimd/issues/823): ability to download all user data with `./hedgedoc export` |
152 | 152 |
|
153 | 153 | **Permission management:** |
154 | 154 |
|
155 | | -- [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 |
156 | | -- [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 |
| 155 | +- [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 |
| 156 | +- [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 |
157 | 157 | - [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. |
158 | 158 |
|
159 | 159 | **Sync backends:** |
160 | 160 |
|
161 | | -- [Import/Export with Github](https://github.com/hackmdio/codimd/issues/34): trigger `./codimd import|export` script via timer or webhook upon github file modification |
| 161 | +- [Import/Export with Github](https://github.com/hackmdio/codimd/issues/34): trigger `./hedgedoc import|export` script via timer or webhook upon github file modification |
162 | 162 | - [Import/Export with Evernote](https://github.com/hackmdio/codimd/issues/97): same deal as github/dropbox sync, write a script with import/export |
163 | 163 | - [Support for ownCloud](https://github.com/hackmdio/codimd/issues/245): same deal as github/dropbox sync, write a script with import/export |
164 | 164 | - [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 |
165 | 165 | - [Support auto sync with Google Drive](https://github.com/hackmdio/codimd/issues/275): write a script that does a full `import` and `export` or merge in whatever direction desired |
| 166 | + |
0 commit comments