feat: extend note and folder CLI capabilities

Author: EastSun5566

README.md

@@ -42,7 +42,7 @@ USAGE
 
 ## Full API access
 
-The existing `notes`, `folders`, and other commands remain unchanged. For operations without a dedicated command, use the installed API client's generated operations:
+Use the focused `notes`, `folders`, and other commands for common workflows. For operations without a dedicated command, use the installed API client's generated operations:
 
 ```bash
 hackmd-cli api operations
@@ -379,23 +379,28 @@ Update folder
 
 ```
 USAGE
-  $ hackmd-cli folders update [--color <value>] [--description <value>] [--folderId <value>] [-h] [--icon <value>]
-    [--name <value>] [--parentFolderId <value>]
+  $ hackmd-cli folders update [--clear description|icon|color] [--color <value>] [--description <value>] [--folderId
+    <value>] [-h] [--icon <value>] [--name <value>] [--parentFolderId <value>] [--root]
 
 FLAGS
   -h, --help                Show CLI help.
+  --clear=<option>...       clear fields: description, icon, color (repeatable)
+                            <options: description|icon|color>
   --color=<value>           folder color
   --description=<value>     folder description
   --folderId=<value>        HackMD folder id
   --icon=<value>            folder icon
   --name=<value>            folder name
   --parentFolderId=<value>  parent folder id
+  --root                    move to the root folder
 
 DESCRIPTION
   Update folder
 
 EXAMPLES
   $ hackmd-cli folders update --folderId=a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d --name='docs' --parentFolderId=fc7a3d48-4a07-4cbf-bf4f-e65dd896e01c --description='Docs' --icon=1F600 --color=#4F46E5
+
+  $ hackmd-cli folders update --folderId=a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d --root --clear=description
 ```
 
 ## `hackmd-cli help [COMMANDS]`
@@ -424,15 +429,16 @@ List user browse history
 
 ```
 USAGE
-  $ hackmd-cli history [-h] [--columns <value> | -x] [--sort <value>] [--filter <value>] [--output
-    csv|json|yaml |  | [--csv | --no-truncate]] [--no-header | ]
+  $ hackmd-cli history [-h] [--limit <value>] [--columns <value> | -x] [--sort <value>] [--filter <value>]
+    [--output csv|json|yaml |  | [--csv | --no-truncate]] [--no-header | ]
 
 FLAGS
   -h, --help         Show CLI help.
   -x, --extended     show extra columns
   --columns=<value>  only show provided columns (comma-separated)
   --csv              output is csv format [alias: --output=csv]
   --filter=<value>   filter property by partial string matching, ex: name=foo
+  --limit=<value>    maximum number of history items to return
   --no-header        hide table header from output
   --no-truncate      do not truncate output to fit screen
   --output=<option>  output in a more machine friendly format
@@ -448,6 +454,8 @@ EXAMPLES
   ────────────────────── ──────────────────────────────── ────────────────────── ────────
   raUuSTetT5uQbqQfLnz9lA CLI test note                    gvfz2UB5THiKABQJQnLs6Q null
   BnC6gN0_TfStV2KKmPPXeg Welcome to your team's workspace null                   CLI-test
+
+  $ hackmd-cli history --limit=10
 ```
 
 _See code: [src/commands/history.ts](https://github.com/hackmdio/hackmd-cli/blob/v2.5.1/src/commands/history.ts)_
@@ -535,9 +543,10 @@ Create a note
 
 ```
 USAGE
-  $ hackmd-cli notes create [--commentPermission <value>] [--content <value>] [-e] [-h] [--parentFolderId <value>]
-    [--readPermission <value>] [--tags <value>] [--title <value>] [--writePermission <value>] [--columns <value> | -x]
-    [--sort <value>] [--filter <value>] [--output csv|json|yaml |  | [--csv | --no-truncate]] [--no-header | ]
+  $ hackmd-cli notes create [--commentPermission <value>] [--content <value>] [--description <value>] [-e] [-h]
+    [--parentFolderId <value>] [--readPermission <value>] [--tags <value>] [--title <value>] [--writePermission <value>]
+    [--columns <value> | -x] [--sort <value>] [--filter <value>] [--output csv|json|yaml |  | [--csv | --no-truncate]]
+    [--no-header | ]
 
 FLAGS
   -e, --editor                 create note with $EDITOR
@@ -547,6 +556,7 @@ FLAGS
   --commentPermission=<value>  set comment permission: disabled, forbidden, owners, signed_in_users, everyone
   --content=<value>            new note content
   --csv                        output is csv format [alias: --output=csv]
+  --description=<value>        note description
   --filter=<value>             filter property by partial string matching, ex: name=foo
   --no-header                  hide table header from output
   --no-truncate                do not truncate output to fit screen
@@ -576,6 +586,8 @@ EXAMPLES
   Or you can pipe content via Unix pipeline:
 
   cat README.md | hackmd-cli notes create
+
+  $ hackmd-cli notes create --title='My note' --description='Short summary'
 ```
 
 ## `hackmd-cli notes delete`
@@ -603,16 +615,21 @@ Update note
 
 ```
 USAGE
-  $ hackmd-cli notes update [--content <value>] [-h] [--noteId <value>] [--parentFolderId <value>] [--permalink
-    <value>] [--readPermission <value>] [--tags <value>] [--title <value>] [--writePermission <value>]
+  $ hackmd-cli notes update [--clear description] [--content <value>] [--description <value>] [-h] [--noteId
+    <value>] [--parentFolderId <value>] [--permalink <value>] [--readPermission <value>] [--root] [--tags <value>]
+    [--title <value>] [--writePermission <value>]
 
 FLAGS
   -h, --help                 Show CLI help.
+  --clear=<option>...        clear fields: description (repeatable)
+                             <options: description>
   --content=<value>          new note content
+  --description=<value>      note description
   --noteId=<value>           HackMD note id
   --parentFolderId=<value>   parent folder id
   --permalink=<value>        note permalink
   --readPermission=<value>   set note permission: owner, signed_in, guest
+  --root                     move to the root folder
   --tags=<value>             set note tags, comma-separated (e.g. tag1,tag2)
   --title=<value>            new note title
   --writePermission=<value>  set note permission: owner, signed_in, guest
@@ -632,6 +649,10 @@ EXAMPLES
   $ hackmd-cli notes update --noteId=WNkLM6gkS0Cg2cQ8rv7bYA --tags=tag1,tag2
 
   $ cat README.md | hackmd-cli notes update --noteId=WNkLM6gkS0Cg2cQ8rv7bYA
+
+  $ hackmd-cli notes update --noteId=WNkLM6gkS0Cg2cQ8rv7bYA --description='Updated summary' --root
+
+  $ hackmd-cli notes update --noteId=WNkLM6gkS0Cg2cQ8rv7bYA --clear=description
 ```
 
 ## `hackmd-cli team-folders`
@@ -755,24 +776,29 @@ Update team folder
 
 ```
 USAGE
-  $ hackmd-cli team-folders update [--color <value>] [--description <value>] [--folderId <value>] [-h] [--icon <value>]
-    [--name <value>] [--parentFolderId <value>] [--teamPath <value>]
+  $ hackmd-cli team-folders update [--clear description|icon|color] [--color <value>] [--description <value>] [--folderId
+    <value>] [-h] [--icon <value>] [--name <value>] [--parentFolderId <value>] [--root] [--teamPath <value>]
 
 FLAGS
   -h, --help                Show CLI help.
+  --clear=<option>...       clear fields: description, icon, color (repeatable)
+                            <options: description|icon|color>
   --color=<value>           folder color
   --description=<value>     folder description
   --folderId=<value>        HackMD folder id
   --icon=<value>            folder icon
   --name=<value>            folder name
   --parentFolderId=<value>  parent folder id
+  --root                    move to the root folder
   --teamPath=<value>        HackMD team path
 
 DESCRIPTION
   Update team folder
 
 EXAMPLES
   $ hackmd-cli team-folders update --teamPath=CLI-test --folderId=a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d --name='team-docs' --parentFolderId=fc7a3d48-4a07-4cbf-bf4f-e65dd896e01c --description='Docs' --icon=1F600 --color=#4F46E5
+
+  $ hackmd-cli team-folders update --teamPath=CLI-test --folderId=a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d --root --clear=description
 ```
 
 ## `hackmd-cli team-notes`
@@ -781,8 +807,8 @@ HackMD team-notes commands
 
 ```
 USAGE
-  $ hackmd-cli team-notes [-h] [--teamPath <value>] [--columns <value> | -x] [--sort <value>] [--filter <value>]
-    [--output csv|json|yaml |  | [--csv | --no-truncate]] [--no-header | ]
+  $ hackmd-cli team-notes [-h] [--noteId <value>] [--teamPath <value>] [--columns <value> | -x] [--sort <value>]
+    [--filter <value>] [--output csv|json|yaml |  | [--csv | --no-truncate]] [--no-header | ]
 
 FLAGS
   -h, --help          Show CLI help.
@@ -792,6 +818,7 @@ FLAGS
   --filter=<value>    filter property by partial string matching, ex: name=foo
   --no-header         hide table header from output
   --no-truncate       do not truncate output to fit screen
+  --noteId=<value>    HackMD note id
   --output=<option>   output in a more machine friendly format
                       <options: csv|json|yaml>
   --sort=<value>      property to sort by (prepend '-' for descending)
@@ -806,6 +833,8 @@ EXAMPLES
   ────────────────────── ──────────────────────────────── ──────── ────────
   WNkLM6gkS0Cg2cQ8rv7bYA a team note                      null     CLI-test
   BnC6gN0_TfStV2KKmPPXeg Welcome to your team's workspace null     CLI-test
+
+  $ hackmd-cli team-notes --teamPath=CLI-test --noteId=WNkLM6gkS0Cg2cQ8rv7bYA
 ```
 
 _See code: [src/commands/team-notes/index.ts](https://github.com/hackmdio/hackmd-cli/blob/v2.5.1/src/commands/team-notes/index.ts)_
@@ -816,10 +845,10 @@ Create a team note
 
 ```
 USAGE
-  $ hackmd-cli team-notes create [--commentPermission <value>] [--content <value>] [-e] [-h] [--parentFolderId <value>]
-    [--readPermission <value>] [--tags <value>] [--teamPath <value>] [--title <value>] [--writePermission <value>]
-    [--columns <value> | -x] [--sort <value>] [--filter <value>] [--output csv|json|yaml |  | [--csv | --no-truncate]]
-    [--no-header | ]
+  $ hackmd-cli team-notes create [--commentPermission <value>] [--content <value>] [--description <value>] [-e] [-h]
+    [--parentFolderId <value>] [--readPermission <value>] [--tags <value>] [--teamPath <value>] [--title <value>]
+    [--writePermission <value>] [--columns <value> | -x] [--sort <value>] [--filter <value>] [--output csv|json|yaml |
+    | [--csv | --no-truncate]] [--no-header | ]
 
 FLAGS
   -e, --editor                 create note with $EDITOR
@@ -829,6 +858,7 @@ FLAGS
   --commentPermission=<value>  set comment permission: disabled, forbidden, owners, signed_in_users, everyone
   --content=<value>            new note content
   --csv                        output is csv format [alias: --output=csv]
+  --description=<value>        note description
   --filter=<value>             filter property by partial string matching, ex: name=foo
   --no-header                  hide table header from output
   --no-truncate                do not truncate output to fit screen
@@ -859,6 +889,8 @@ EXAMPLES
   Or you can pipe content via Unix pipeline:
 
   cat README.md | hackmd-cli team-notes create --teamPath=CLI-test
+
+  $ hackmd-cli team-notes create --teamPath=CLI-test --title='My note' --description='Short summary'
 ```
 
 ## `hackmd-cli team-notes delete`
@@ -887,17 +919,21 @@ Update team note
 
 ```
 USAGE
-  $ hackmd-cli team-notes update [--content <value>] [-h] [--noteId <value>] [--parentFolderId <value>] [--permalink
-    <value>] [--readPermission <value>] [--tags <value>] [--teamPath <value>] [--title <value>] [--writePermission
-    <value>]
+  $ hackmd-cli team-notes update [--clear description] [--content <value>] [--description <value>] [-h] [--noteId
+    <value>] [--parentFolderId <value>] [--permalink <value>] [--readPermission <value>] [--root] [--tags <value>]
+    [--teamPath <value>] [--title <value>] [--writePermission <value>]
 
 FLAGS
   -h, --help                 Show CLI help.
+  --clear=<option>...        clear fields: description (repeatable)
+                             <options: description>
   --content=<value>          new note content
+  --description=<value>      note description
   --noteId=<value>           HackMD note id
   --parentFolderId=<value>   parent folder id
   --permalink=<value>        note permalink
   --readPermission=<value>   set note permission: owner, signed_in, guest
+  --root                     move to the root folder
   --tags=<value>             set note tags, comma-separated (e.g. tag1,tag2)
   --teamPath=<value>         HackMD team path
   --title=<value>            new note title
@@ -918,6 +954,10 @@ EXAMPLES
   $ hackmd-cli team-notes update --teamPath=CLI-test --noteId=WNkLM6gkS0Cg2cQ8rv7bYA --tags=tag1,tag2
 
   $ cat README.md | hackmd-cli team-notes update --teamPath=CLI-test --noteId=WNkLM6gkS0Cg2cQ8rv7bYA
+
+  $ hackmd-cli team-notes update --teamPath=CLI-test --noteId=WNkLM6gkS0Cg2cQ8rv7bYA --description='Updated summary' --root
+
+  $ hackmd-cli team-notes update --teamPath=CLI-test --noteId=WNkLM6gkS0Cg2cQ8rv7bYA --clear=description
 ```
 
 ## `hackmd-cli teams`

hackmd-cli.skill

@@ -67,7 +67,7 @@ hackmd-cli notes
 hackmd-cli notes --noteId=<id>
 
 # Create note
-hackmd-cli notes create --content='# Title' --title='My Note'
+hackmd-cli notes create --content='# Title' --title='My Note' --description='Summary'
 hackmd-cli notes create --readPermission=owner --writePermission=owner
 
 # Create note inside a folder
@@ -82,9 +82,12 @@ hackmd-cli notes create -e
 # Update note
 hackmd-cli notes update --noteId=<id> --content='# New Content'
 hackmd-cli notes update --noteId=<id> --title='New title'
+hackmd-cli notes update --noteId=<id> --description='New summary'
+hackmd-cli notes update --noteId=<id> --clear=description
 
 # Move note into a folder
 hackmd-cli notes update --noteId=<id> --parentFolderId=<folder-id>
+hackmd-cli notes update --noteId=<id> --root
 
 # Delete note
 hackmd-cli notes delete --noteId=<id>
@@ -96,18 +99,24 @@ hackmd-cli notes delete --noteId=<id>
 # List team notes
 hackmd-cli team-notes --teamPath=<team-path>
 
+# Get a specific team note
+hackmd-cli team-notes --teamPath=<team-path> --noteId=<id>
+
 # Create team note
-hackmd-cli team-notes create --teamPath=<team-path> --content='# Team Doc'
+hackmd-cli team-notes create --teamPath=<team-path> --content='# Team Doc' --description='Summary'
 
 # Create team note inside a folder
 hackmd-cli team-notes create --teamPath=<team-path> --parentFolderId=<folder-id> --content='# Team Doc'
 
 # Update team note
 hackmd-cli team-notes update --teamPath=<team-path> --noteId=<id> --content='# Updated'
 hackmd-cli team-notes update --teamPath=<team-path> --noteId=<id> --title='New title'
+hackmd-cli team-notes update --teamPath=<team-path> --noteId=<id> --description='New summary'
+hackmd-cli team-notes update --teamPath=<team-path> --noteId=<id> --clear=description
 
 # Move team note into a folder
 hackmd-cli team-notes update --teamPath=<team-path> --noteId=<id> --parentFolderId=<folder-id>
+hackmd-cli team-notes update --teamPath=<team-path> --noteId=<id> --root
 
 # Delete team note
 hackmd-cli team-notes delete --teamPath=<team-path> --noteId=<id>
@@ -133,6 +142,8 @@ hackmd-cli folders create --name='Docs' --description='Project docs' --icon=1F60
 
 # Update folder
 hackmd-cli folders update --folderId=<id> --name='Updated Docs'
+hackmd-cli folders update --folderId=<id> --root
+hackmd-cli folders update --folderId=<id> --clear=description --clear=icon --clear=color
 
 # Delete folder
 hackmd-cli folders delete --folderId=<id>
@@ -162,6 +173,8 @@ hackmd-cli team-folders create --teamPath=<team-path> --name='Team Docs' --descr
 
 # Update team folder
 hackmd-cli team-folders update --teamPath=<team-path> --folderId=<id> --name='Updated Team Docs'
+hackmd-cli team-folders update --teamPath=<team-path> --folderId=<id> --root
+hackmd-cli team-folders update --teamPath=<team-path> --folderId=<id> --clear=description
 
 # Delete team folder
 hackmd-cli team-folders delete --teamPath=<team-path> --folderId=<id>
@@ -176,6 +189,7 @@ hackmd-cli team-folders order --teamPath=<team-path> --order='{"root":["folder-i
 ```bash
 hackmd-cli teams              # List accessible teams
 hackmd-cli history            # List browsing history
+hackmd-cli history --limit=10 # Limit the number of items
 ```
 
 ### Export
@@ -194,10 +208,15 @@ Available permission values:
 | `--writePermission`   | `owner`, `signed_in`, `guest`                                    |
 | `--commentPermission` | `disabled`, `forbidden`, `owners`, `signed_in_users`, `everyone` |
 
-## Folder Flags
+## Note and Folder Update Flags
+
+Omitted fields stay unchanged. `--description=''` sets an empty string; `--clear=description` removes the description. Do not set and clear the same field in one command.
 
 ```bash
 --parentFolderId=<folder-id>          # Put note/folder inside another folder
+--root                                # Move a note/folder to root (update only)
+--clear=description                   # Clear note/folder description (update only)
+--clear=icon --clear=color             # Clear folder fields (repeatable, update only)
 --icon=1F600                          # Emoji unified codepoint string
 --color='#4F46E5'                     # Hex color string
 --order='{"root":["id1","id2"]}'  # Folder ordering JSON