diff --git a/README.md b/README.md
index 04aa67e..588604a 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,7 @@
 [![License](https://img.shields.io/npm/l/@hackmd/hackmd-cli.svg)](https://github.com/hackmdio/hackmd-cli/blob/master/package.json)
 
 * [Usage](#usage)
+* [Full API access](#full-api-access)
 * [Commands](#commands)
 * [Configuration](#configuration)
 * [License](#license)
@@ -31,7 +32,7 @@ $ npm install -g @hackmd/hackmd-cli
 $ hackmd-cli COMMAND
 running command...
 $ hackmd-cli (--version|-v)
-@hackmd/hackmd-cli/2.5.1 darwin-arm64 node-v26.0.0
+@hackmd/hackmd-cli/2.5.1 darwin-arm64 node-v24.16.0
 $ hackmd-cli --help [COMMAND]
 USAGE
   $ hackmd-cli COMMAND
@@ -39,6 +40,23 @@ USAGE
 ```
 <!-- usagestop -->
 
+## Full API access
+
+Use the focused `notes`, `folders`, and other commands for common workflows. For other API operations, use `api`:
+
+```bash
+hackmd-cli api operations
+hackmd-cli api describe GetTeamNote
+hackmd-cli api call GetTeamNote --path teampath=docs --path noteId=abc
+hackmd-cli api call ListVersions --path noteId=abc --query limit=10
+hackmd-cli api call CreateNote --body @note.json
+hackmd-cli api call UploadNoteImage --path noteId=abc --file image=@photo.png
+```
+
+Use repeated `--path key=value`, `--query key=value`, and `--header 'Name: value'` flags. `--body` accepts JSON text, `@file`, or `-` for stdin. For multipart image uploads, use `--file image=@path`; the file extension sets its MIME type, or use `--mime` to override it. `--include` prints HTTP status and headers before the response body. Empty 204/304 responses print no body; NDJSON is printed unchanged. Errors exit nonzero.
+
+`api operations` and `api describe` need no connection or token. They use the API client bundled with this CLI, so older HackMD EE servers may not support every operation. `api call` uses the same access token and endpoint configuration as other commands. Writes are not retried automatically.
+
 ## Configuration
 
 ### Set access token
@@ -100,6 +118,9 @@ All available configurations are listed in the table below.
 ## Commands
 
 <!-- commands -->
+* [`hackmd-cli api call OPERATIONID`](#hackmd-cli-api-call-operationid)
+* [`hackmd-cli api describe OPERATIONID`](#hackmd-cli-api-describe-operationid)
+* [`hackmd-cli api operations`](#hackmd-cli-api-operations)
 * [`hackmd-cli autocomplete [SHELL]`](#hackmd-cli-autocomplete-shell)
 * [`hackmd-cli export`](#hackmd-cli-export)
 * [`hackmd-cli folders`](#hackmd-cli-folders)
@@ -128,6 +149,66 @@ All available configurations are listed in the table below.
 * [`hackmd-cli version`](#hackmd-cli-version)
 * [`hackmd-cli whoami`](#hackmd-cli-whoami)
 
+## `hackmd-cli api call OPERATIONID`
+
+Call a HackMD API operation
+
+```
+USAGE
+  $ hackmd-cli api call OPERATIONID [--body <value>] [--file <value>] [--header <value>] [-h] [--include]
+    [--mime <value>] [--path <value>] [--query <value>]
+
+FLAGS
+  -h, --help           Show CLI help.
+  --body=<value>       JSON value, @file, or - for stdin
+  --file=<value>...    Multipart binary field, e.g. image=@photo.png
+  --header=<value>...  Request header Name: value
+  --include            Include HTTP status and response headers
+  --mime=<value>       MIME type override for --file
+  --path=<value>...    Path parameter key=value
+  --query=<value>...   Query parameter key=value
+
+DESCRIPTION
+  Call a HackMD API operation
+
+EXAMPLES
+  $ hackmd-cli api call GetTeamNote --path teampath=docs --path noteId=abc
+
+  $ hackmd-cli api call CreateNote --body @note.json
+
+  $ hackmd-cli api call UploadNoteImage --path noteId=abc --file image=@photo.png
+```
+
+## `hackmd-cli api describe OPERATIONID`
+
+Show details for an API operation
+
+```
+USAGE
+  $ hackmd-cli api describe OPERATIONID [-h]
+
+FLAGS
+  -h, --help  Show CLI help.
+
+DESCRIPTION
+  Show details for an API operation
+```
+
+## `hackmd-cli api operations`
+
+List available API operations
+
+```
+USAGE
+  $ hackmd-cli api operations [-h]
+
+FLAGS
+  -h, --help  Show CLI help.
+
+DESCRIPTION
+  List available API operations
+```
+
 ## `hackmd-cli autocomplete [SHELL]`
 
 display autocomplete installation instructions
@@ -298,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]`
@@ -343,8 +429,8 @@ 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.
@@ -352,6 +438,7 @@ FLAGS
   --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
@@ -367,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)_
@@ -454,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
@@ -466,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
@@ -495,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`
@@ -522,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
@@ -550,7 +648,11 @@ EXAMPLES
 
   $ hackmd-cli notes update --noteId=WNkLM6gkS0Cg2cQ8rv7bYA --tags=tag1,tag2
 
-  cat README.md | hackmd-cli notes update --noteId=WNkLM6gkS0Cg2cQ8rv7bYA
+  $ 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`
@@ -674,17 +776,20 @@ 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
@@ -692,6 +797,8 @@ DESCRIPTION
 
 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`
@@ -700,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.
@@ -711,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)
@@ -725,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)_
@@ -735,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
@@ -748,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
@@ -778,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`
@@ -806,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
@@ -836,7 +953,11 @@ 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
+  $ 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`
diff --git a/hackmd-cli.skill b/hackmd-cli.skill
index 55ff35e..ac5da4f 100644
Binary files a/hackmd-cli.skill and b/hackmd-cli.skill differ
diff --git a/hackmd-cli/SKILL.md b/hackmd-cli/SKILL.md
index 32b75df..035a59b 100644
--- a/hackmd-cli/SKILL.md
+++ b/hackmd-cli/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: hackmd-cli
-description: HackMD command-line interface for managing personal/team notes and folders. Use this skill when users want to create, read, update, delete, reorder, or export HackMD notes and folders via CLI, manage team content, list teams, view browsing history, or automate HackMD workflows.
+description: HackMD command-line interface for managing notes, folders, and other v1 API operations. Use for HackMD content, team workflows, exports, or API automation.
 ---
 
 # HackMD CLI
@@ -35,6 +35,20 @@ export HMD_API_ENDPOINT_URL=https://your.hackmd-ee.endpoint
 
 ## Commands
 
+### Other API operations
+
+Prefer the focused `notes`, `folders`, and other commands when available. For other operations, find the operation ID and parameters, then call it:
+
+```bash
+hackmd-cli api operations
+hackmd-cli api describe GetTeamNote
+hackmd-cli api call GetTeamNote --path teampath=docs --path noteId=abc
+hackmd-cli api call CreateNote --body @note.json
+hackmd-cli api call UploadNoteImage --path noteId=abc --file image=@photo.png
+```
+
+Repeat `--path key=value`, `--query key=value`, or `--header 'Name: value'` as needed. `--body` accepts JSON text, `@file`, or `-` for stdin. `--file image=@path` is for multipart upload; use `--mime` if the extension is unknown. `--include` shows HTTP status and headers. The list comes from the API client bundled with the CLI; older EE servers may not support every operation. Generic writes are not retried automatically. Do not run writes or deletes without the user's authorization.
+
 ### Authentication
 
 ```bash
@@ -53,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
@@ -68,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>
@@ -82,8 +99,11 @@ 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'
@@ -91,9 +111,12 @@ hackmd-cli team-notes create --teamPath=<team-path> --parentFolderId=<folder-id>
 # 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>
@@ -119,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>
@@ -148,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>
@@ -162,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
@@ -180,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
diff --git a/package.json b/package.json
index 5444642..8bad563 100644
--- a/package.json
+++ b/package.json
@@ -54,6 +54,11 @@
     "commands": "./lib/commands",
     "bin": "hackmd-cli",
     "topicSeparator": " ",
+    "topics": {
+      "api": {
+        "description": "Explore and call HackMD API operations"
+      }
+    },
     "additionalHelpFlags": [
       "-h"
     ],
diff --git a/src/api/operations.ts b/src/api/operations.ts
new file mode 100644
index 0000000..d5f93ae
--- /dev/null
+++ b/src/api/operations.ts
@@ -0,0 +1,68 @@
+import type {OperationId} from '@hackmd/api/raw'
+
+import {operationRegistry} from '@hackmd/api/raw'
+
+export type Operation = {
+  call: unknown;
+  method: string;
+  parameters: ReadonlyArray<{in: string; name: string; required: boolean; type: string}>;
+  path: string;
+  requestBody?: {
+    binaryFields: ReadonlyArray<{name: string; required: boolean}>;
+    contentTypes: readonly string[];
+    required: boolean;
+  };
+  responses: Record<string, readonly string[]>;
+}
+
+export function getOperation(id: string): Operation {
+  if (!Object.hasOwn(operationRegistry, id)) {
+    throw new Error(`Unknown operation "${id}". Run "hackmd-cli api operations" to see available operations.`)
+  }
+
+  return operationRegistry[id as OperationId]
+}
+
+export function parsePairs(values: string[], separator: string, kind: string): Record<string, string> {
+  const result: Record<string, string> = Object.create(null)
+  for (const value of values) {
+    const index = value.indexOf(separator)
+    if (index <= 0) throw new Error(`Invalid --${kind} value "${value}"; expected key${separator}value`)
+    const key = value.slice(0, index).trim()
+    if (!key || Object.hasOwn(result, key)) throw new Error(`Duplicate or empty --${kind} key "${key}"`)
+    result[key] = value.slice(index + separator.length).trim()
+  }
+
+  return result
+}
+
+export function validateParameters(operation: Operation, location: 'path' | 'query', input: Record<string, string>): Record<string, boolean | number | string> {
+  const parameters = operation.parameters.filter(parameter => parameter.in === location)
+  const allowed = new Map(parameters.map(parameter => [parameter.name, parameter]))
+  for (const parameter of parameters) {
+    if (parameter.required && !Object.hasOwn(input, parameter.name)) {
+      throw new Error(`Missing required --${location} ${parameter.name}=...`)
+    }
+  }
+
+  const result: Record<string, boolean | number | string> = {}
+  for (const [key, value] of Object.entries(input)) {
+    const parameter = allowed.get(key)
+    if (!parameter) throw new Error(`Unknown --${location} parameter "${key}" for ${operation.method} ${operation.path}`)
+    if (parameter.type === 'number' || parameter.type === 'integer') {
+      const number = Number(value)
+      if (value === '' || !Number.isFinite(number) || (parameter.type === 'integer' && !Number.isInteger(number))) {
+        throw new Error(`--${location} ${key} must be a ${parameter.type}`)
+      }
+
+      result[key] = number
+    } else if (parameter.type === 'boolean') {
+      if (value !== 'true' && value !== 'false') throw new Error(`--${location} ${key} must be true or false`)
+      result[key] = value === 'true'
+    } else {
+      result[key] = value
+    }
+  }
+
+  return result
+}
diff --git a/src/commands/api/call.ts b/src/commands/api/call.ts
new file mode 100644
index 0000000..6e82c81
--- /dev/null
+++ b/src/commands/api/call.ts
@@ -0,0 +1,154 @@
+import type {Client} from '@hackmd/api/raw'
+
+import {createClient} from '@hackmd/api/raw'
+import {Args, Flags, ux} from '@oclif/core'
+import {readFileSync} from 'node:fs'
+import {basename, extname} from 'node:path'
+
+import type {Operation} from '../../api/operations'
+
+import {getOperation, parsePairs, validateParameters} from '../../api/operations'
+import HackMDCommand from '../../command'
+import config from '../../config'
+import {setAccessTokenConfig} from '../../utils'
+
+type RawResponse = {data: unknown; headers: Record<string, unknown>; status: number}
+type RawCall = (options: {
+  body?: unknown;
+  client: Client;
+  headers?: Record<string, string>;
+  path?: Record<string, boolean | number | string>;
+  query?: Record<string, boolean | number | string>;
+  responseType?: 'text';
+  throwOnError: true;
+}) => Promise<RawResponse>
+
+const mimeTypes: Record<string, string> = {
+  '.avif': 'image/avif',
+  '.gif': 'image/gif',
+  '.jpeg': 'image/jpeg',
+  '.jpg': 'image/jpeg',
+  '.png': 'image/png',
+  '.svg': 'image/svg+xml',
+  '.webp': 'image/webp',
+}
+
+function readBody(value: string): unknown {
+  const content = value === '-'
+    ? readFileSync(process.stdin.fd, 'utf8')
+    : (value.startsWith('@') ? readFileSync(value.slice(1), 'utf8') : value)
+  try {
+    return JSON.parse(content)
+  } catch {
+    throw new Error('--body must contain valid JSON')
+  }
+}
+
+function prepareFiles(operation: Operation, files: string[], mime: string | undefined): Record<string, File> {
+  if (!operation.requestBody?.contentTypes.includes('multipart/form-data')) throw new Error('--file is only supported for multipart operations')
+  const result: Record<string, File> = {}
+  for (const input of files) {
+    const [field, filepath] = input.split('=@', 2)
+    if (!field || !filepath || !operation.requestBody.binaryFields.some(entry => entry.name === field)) {
+      throw new Error(`Invalid --file "${input}"; expected a documented field such as image=@path`)
+    }
+
+    if (result[field]) throw new Error(`Duplicate --file field "${field}"`)
+    const contentType = mime ?? mimeTypes[extname(filepath).toLowerCase()]
+    if (!contentType) throw new Error(`Cannot infer MIME type for ${filepath}; pass --mime`)
+    result[field] = new File([readFileSync(filepath)], basename(filepath), {type: contentType})
+  }
+
+  for (const field of operation.requestBody.binaryFields) {
+    if (field.required && !result[field.name]) throw new Error(`Missing required --file ${field.name}=@path`)
+  }
+
+  return result
+}
+
+function prepareBody(operation: Operation, body: string | undefined, file: string[] | undefined, mime: string | undefined): unknown {
+  const files = file ?? []
+  if (body !== undefined && files.length > 0) throw new Error('Use either --body or --file, not both')
+  if (mime && files.length === 0) throw new Error('--mime requires --file')
+  if ((body !== undefined || files.length > 0) && !operation.requestBody) throw new Error(`${operation.method} ${operation.path} has no request body`)
+  if (operation.requestBody?.required && body === undefined && files.length === 0) throw new Error('This operation requires --body or --file')
+  if (files.length > 0) return prepareFiles(operation, files, mime)
+
+  if (body !== undefined) {
+    if (!operation.requestBody?.contentTypes.includes('application/json')) throw new Error('--body JSON is not supported by this operation')
+    return readBody(body)
+  }
+}
+
+function formatBody(data: unknown): string {
+  if (typeof data === 'string') return data
+  return JSON.stringify(data, null, 2)
+}
+
+export default class CallCommand extends HackMDCommand {
+  static args = {operationId: Args.string({required: true})}
+  static description = 'Call a HackMD API operation'
+  static examples = [
+    'hackmd-cli api call GetTeamNote --path teampath=docs --path noteId=abc',
+    'hackmd-cli api call CreateNote --body @note.json',
+    'hackmd-cli api call UploadNoteImage --path noteId=abc --file image=@photo.png',
+  ]
+  static flags = {
+    body: Flags.string({description: 'JSON value, @file, or - for stdin'}),
+    file: Flags.string({description: 'Multipart binary field, e.g. image=@photo.png', multiple: true}),
+    header: Flags.string({description: 'Request header Name: value', multiple: true}),
+    help: Flags.help({char: 'h'}),
+    include: Flags.boolean({description: 'Include HTTP status and response headers'}),
+    mime: Flags.string({description: 'MIME type override for --file'}),
+    path: Flags.string({description: 'Path parameter key=value', multiple: true}),
+    query: Flags.string({description: 'Query parameter key=value', multiple: true}),
+  }
+
+  async run() {
+    const {args, flags} = await this.parse(CallCommand)
+    const operation = getOperation(args.operationId)
+    const path = validateParameters(operation, 'path', parsePairs(flags.path ?? [], '=', 'path'))
+    const query = validateParameters(operation, 'query', parsePairs(flags.query ?? [], '=', 'query'))
+    const headers = parsePairs(flags.header ?? [], ':', 'header')
+    const body = prepareBody(operation, flags.body, flags.file, flags.mime)
+    const token = config.accessToken || await ux.prompt('Enter your access token', {type: 'hide'})
+    if (!token) throw new Error('An access token is required')
+    const client = createClient({
+      auth: token,
+      baseURL: config.hackmdAPIEndpointURL,
+      validateStatus: status => (status >= 200 && status < 300) || status === 304,
+    })
+    const ndjson = Object.values(operation.responses).some(contentTypes => contentTypes.includes('application/x-ndjson'))
+    try {
+      const response = await (operation.call as unknown as RawCall)({
+        body,
+        client,
+        headers,
+        path,
+        query,
+        ...(ndjson ? {responseType: 'text' as const} : {}),
+        throwOnError: true,
+      })
+      if (!config.accessToken) setAccessTokenConfig(token)
+      if (flags.include) {
+        this.log(`HTTP ${response.status}`)
+        for (const [name, value] of Object.entries(response.headers)) this.log(`${name}: ${value}`)
+        this.log('')
+      }
+
+      const hasBody = operation.responses[String(response.status)]?.length !== 0
+      if (hasBody && response.data !== undefined && response.data !== null) {
+        if (ndjson) process.stdout.write(formatBody(response.data))
+        else this.log(formatBody(response.data))
+      }
+    } catch (error) {
+      const failure = error as {message?: string; response?: RawResponse}
+      if (failure.response) {
+        const {data, status} = failure.response
+        this.error(`HTTP ${status}${data === undefined ? '' : `: ${formatBody(data)}`}`)
+      }
+
+      this.error(failure.message ?? String(error))
+    }
+  }
+}
diff --git a/src/commands/api/describe.ts b/src/commands/api/describe.ts
new file mode 100644
index 0000000..61b1026
--- /dev/null
+++ b/src/commands/api/describe.ts
@@ -0,0 +1,15 @@
+import {Args, Flags} from '@oclif/core'
+
+import {getOperation} from '../../api/operations'
+import HackMDCommand from '../../command'
+
+export default class DescribeCommand extends HackMDCommand {
+  static args = {operationId: Args.string({required: true})}
+  static description = 'Show details for an API operation'
+  static flags = {help: Flags.help({char: 'h'})}
+
+  async run() {
+    const {args} = await this.parse(DescribeCommand)
+    this.log(JSON.stringify({operationId: args.operationId, ...getOperation(args.operationId)}, null, 2))
+  }
+}
diff --git a/src/commands/api/operations.ts b/src/commands/api/operations.ts
new file mode 100644
index 0000000..affd1a7
--- /dev/null
+++ b/src/commands/api/operations.ts
@@ -0,0 +1,17 @@
+import {operationRegistry} from '@hackmd/api/raw'
+import {Flags} from '@oclif/core'
+
+import HackMDCommand from '../../command'
+
+export default class OperationsCommand extends HackMDCommand {
+  static description = 'List available API operations'
+  static flags = {help: Flags.help({char: 'h'})}
+
+  async run() {
+    await this.parse(OperationsCommand)
+    this.log('Available API operations:')
+    for (const [id, operation] of Object.entries(operationRegistry)) {
+      this.log(`${id}\t${operation.method} ${operation.path}`)
+    }
+  }
+}
diff --git a/src/commands/folders/update.ts b/src/commands/folders/update.ts
index 1e3875c..e215ec6 100644
--- a/src/commands/folders/update.ts
+++ b/src/commands/folders/update.ts
@@ -4,20 +4,25 @@ import {Flags} from '@oclif/core'
 
 import HackMDCommand from '../../command'
 import {
+  clearFields,
   folderColor,
   folderDescription,
   folderIcon,
   folderId,
   folderName,
   parentFolderId,
+  root,
 } from '../../flags'
+import {buildFolderUpdatePayload} from '../../folder-update'
 
 export default class Update extends HackMDCommand {
   static description = 'Update folder'
   static 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',
   ]
   static flags = {
+    clear: clearFields(['description', 'icon', 'color']),
     color: folderColor,
     description: folderDescription,
     folderId,
@@ -25,22 +30,24 @@ export default class Update extends HackMDCommand {
     icon: folderIcon,
     name: folderName,
     parentFolderId,
+    root,
   }
 
   async run() {
     const {flags} = await this.parse(Update)
-    const {color, description, folderId, icon, name, parentFolderId} = flags
+    const {clear, color, description, folderId, icon, name, parentFolderId, root} = flags
 
     if (!folderId) {
       this.error('Flag folderId could not be empty')
     }
 
-    const payload: UpdateUserFolderBody = {
-      color,
-      description,
-      icon,
-      name,
-      parentFolderId,
+    let payload: UpdateUserFolderBody
+    try {
+      payload = buildFolderUpdatePayload({
+        clear, color, description, icon, name, parentFolderId, root,
+      })
+    } catch (error) {
+      this.error(error as Error)
     }
 
     try {
diff --git a/src/commands/history.ts b/src/commands/history.ts
index 2c38a78..a46378c 100644
--- a/src/commands/history.ts
+++ b/src/commands/history.ts
@@ -9,19 +9,25 @@ export default class History extends HackMDCommand {
 ID                     Title                            User Path               Team Path
 ────────────────────── ──────────────────────────────── ────────────────────── ────────
 raUuSTetT5uQbqQfLnz9lA CLI test note                    gvfz2UB5THiKABQJQnLs6Q null
-BnC6gN0_TfStV2KKmPPXeg Welcome to your team's workspace null                   CLI-test `,
+BnC6gN0_TfStV2KKmPPXeg Welcome to your team's workspace null                   CLI-test`,
+    '$ hackmd-cli history --limit=10',
   ]
   static flags = {
     help: Flags.help({char: 'h'}),
+    limit: Flags.integer({description: 'maximum number of history items to return'}),
     ...ux.table.flags(),
   }
 
   async run() {
     const {flags} = await this.parse(History)
 
+    if (flags.limit !== undefined && flags.limit < 1) {
+      this.error('Flag limit must be a positive integer')
+    }
+
     try {
       const APIClient = await this.getAPIClient()
-      const history = await APIClient.getHistory()
+      const history = await APIClient.getHistory(flags.limit === undefined ? undefined : {limit: flags.limit})
 
       ux.table(history, {
         id: {
diff --git a/src/commands/notes/create.ts b/src/commands/notes/create.ts
index 132e427..929a155 100644
--- a/src/commands/notes/create.ts
+++ b/src/commands/notes/create.ts
@@ -12,6 +12,7 @@ import {
   commentPermission,
   editor,
   noteContent,
+  noteDescription,
   notePermission,
   noteTags,
   noteTitle,
@@ -40,10 +41,12 @@ raUuSTetT5uQbqQfLnz9lA A new note                       gvfz2UB5THiKABQJQnLs6Q n
 
     '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'",
   ]
   static flags = {
     commentPermission,
     content: noteContent,
+    description: noteDescription,
     editor,
     help: Flags.help({char: 'h'}),
     parentFolderId,
@@ -61,6 +64,7 @@ raUuSTetT5uQbqQfLnz9lA A new note                       gvfz2UB5THiKABQJQnLs6Q n
     const options: CreateNoteOptions & {tags?: string[]} = {
       commentPermission: flags.commentPermission as CommentPermissionType,
       content: pipeString || flags.content,
+      description: flags.description,
       parentFolderId: flags.parentFolderId,
       readPermission: flags.readPermission as NotePermissionRole,
       title: flags.title,
@@ -93,7 +97,7 @@ raUuSTetT5uQbqQfLnz9lA A new note                       gvfz2UB5THiKABQJQnLs6Q n
             header: 'ID',
           },
           tags: {
-            get: row => (row.tags ?? []).join(', '),
+            get: row => ('tags' in row ? row.tags ?? [] : []).join(', '),
           },
           teamPath: {
             header: 'Team path',
diff --git a/src/commands/notes/update.ts b/src/commands/notes/update.ts
index b0aae8b..9a8db9f 100644
--- a/src/commands/notes/update.ts
+++ b/src/commands/notes/update.ts
@@ -4,7 +4,7 @@ import {Flags} from '@oclif/core'
 
 import HackMDCommand from '../../command'
 import {
-  noteContent, noteId, notePermission, noteTags, noteTitle, parentFolderId, permalink,
+  clearFields, noteContent, noteDescription, noteId, notePermission, noteTags, noteTitle, parentFolderId, permalink, root,
 } from '../../flags'
 import {buildNoteUpdatePayload} from '../../note-update'
 import {safeStdinRead} from '../../utils'
@@ -18,14 +18,19 @@ export default class Update extends HackMDCommand {
     '$ hackmd-cli notes update --noteId=WNkLM6gkS0Cg2cQ8rv7bYA --readPermission=owner --writePermission=owner',
     '$ 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',
   ]
   static flags = {
+    clear: clearFields(['description']),
     content: noteContent,
+    description: noteDescription,
     help: Flags.help({char: 'h'}),
     noteId,
     parentFolderId,
     permalink,
     readPermission: notePermission(),
+    root,
     tags: noteTags,
     title: noteTitle,
     writePermission: notePermission(),
@@ -33,7 +38,7 @@ export default class Update extends HackMDCommand {
 
   async run() {
     const {flags} = await this.parse(Update)
-    const {content, noteId, parentFolderId, permalink, readPermission, tags, title, writePermission} = flags
+    const {clear, content, description, noteId, parentFolderId, permalink, readPermission, root, tags, title, writePermission} = flags
 
     if (!noteId) {
       this.error('Flag noteId could not be empty')
@@ -44,7 +49,7 @@ export default class Update extends HackMDCommand {
     try {
       payload = buildNoteUpdatePayload(
         {
-          content, parentFolderId, permalink, readPermission, tags, title, writePermission,
+          clear, content, description, parentFolderId, permalink, readPermission, root, tags, title, writePermission,
         },
         stdinContent,
       )
diff --git a/src/commands/team-folders/update.ts b/src/commands/team-folders/update.ts
index f380709..f03ea38 100644
--- a/src/commands/team-folders/update.ts
+++ b/src/commands/team-folders/update.ts
@@ -4,14 +4,17 @@ import {Flags} from '@oclif/core'
 
 import HackMDCommand from '../../command'
 import {
+  clearFields,
   folderColor,
   folderDescription,
   folderIcon,
   folderId,
   folderName,
   parentFolderId,
+  root,
   teamPath,
 } from '../../flags'
+import {buildFolderUpdatePayload} from '../../folder-update'
 
 export default class Update extends HackMDCommand {
   static description = 'Update team folder'
@@ -23,8 +26,10 @@ export default class Update extends HackMDCommand {
       '--parentFolderId=fc7a3d48-4a07-4cbf-bf4f-e65dd896e01c ',
       "--description='Docs' --icon=1F600 --color=#4F46E5",
     ].join(''),
+    '$ hackmd-cli team-folders update --teamPath=CLI-test --folderId=a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d --root --clear=description',
   ]
   static flags = {
+    clear: clearFields(['description', 'icon', 'color']),
     color: folderColor,
     description: folderDescription,
     folderId,
@@ -32,12 +37,13 @@ export default class Update extends HackMDCommand {
     icon: folderIcon,
     name: folderName,
     parentFolderId,
+    root,
     teamPath,
   }
 
   async run() {
     const {flags} = await this.parse(Update)
-    const {color, description, folderId, icon, name, parentFolderId, teamPath} = flags
+    const {clear, color, description, folderId, icon, name, parentFolderId, root, teamPath} = flags
 
     if (!teamPath) {
       this.error('Flag teamPath could not be empty')
@@ -47,12 +53,13 @@ export default class Update extends HackMDCommand {
       this.error('Flag folderId could not be empty')
     }
 
-    const payload: UpdateTeamFolderBody = {
-      color,
-      description,
-      icon,
-      name,
-      parentFolderId,
+    let payload: UpdateTeamFolderBody
+    try {
+      payload = buildFolderUpdatePayload({
+        clear, color, description, icon, name, parentFolderId, root,
+      })
+    } catch (error) {
+      this.error(error as Error)
     }
 
     try {
diff --git a/src/commands/team-notes/create.ts b/src/commands/team-notes/create.ts
index db4a0af..43ad092 100644
--- a/src/commands/team-notes/create.ts
+++ b/src/commands/team-notes/create.ts
@@ -5,7 +5,7 @@ import fs from 'node:fs'
 
 import HackMDCommand from '../../command'
 import {
-  commentPermission, editor, noteContent, notePermission, noteTags, noteTitle, parentFolderId, teamPath,
+  commentPermission, editor, noteContent, noteDescription, notePermission, noteTags, noteTitle, parentFolderId, teamPath,
 } from '../../flags'
 import {openEditor} from '../../open-editor'
 import {safeStdinRead, temporaryMD} from '../../utils'
@@ -30,10 +30,12 @@ raUuSTetT5uQbqQfLnz9lA A new note                       gvfz2UB5THiKABQJQnLs6Q n
 
     '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'",
   ]
   static flags = {
     commentPermission,
     content: noteContent,
+    description: noteDescription,
     editor,
     help: Flags.help({char: 'h'}),
     parentFolderId,
@@ -49,10 +51,11 @@ raUuSTetT5uQbqQfLnz9lA A new note                       gvfz2UB5THiKABQJQnLs6Q n
     const {flags} = await this.parse(Create)
     const pipeString = safeStdinRead()
 
-    const {commentPermission, content, parentFolderId, readPermission, tags, teamPath, title, writePermission} = flags
+    const {commentPermission, content, description, parentFolderId, readPermission, tags, teamPath, title, writePermission} = flags
     const options: CreateNoteOptions & {tags?: string[]} = {
       commentPermission: commentPermission as CommentPermissionType,
       content: pipeString || content,
+      description,
       parentFolderId,
       readPermission: readPermission as NotePermissionRole,
       title,
@@ -87,7 +90,7 @@ raUuSTetT5uQbqQfLnz9lA A new note                       gvfz2UB5THiKABQJQnLs6Q n
           header: 'ID',
         },
         tags: {
-          get: row => (row.tags ?? []).join(', '),
+          get: row => ('tags' in row ? row.tags ?? [] : []).join(', '),
         },
         teamPath: {
           header: 'Team path',
diff --git a/src/commands/team-notes/index.ts b/src/commands/team-notes/index.ts
index fb8e7c9..ca550f2 100644
--- a/src/commands/team-notes/index.ts
+++ b/src/commands/team-notes/index.ts
@@ -1,7 +1,7 @@
 import {Flags, ux} from '@oclif/core'
 
 import HackMDCommand from '../../command'
-import {teamPath} from '../../flags'
+import {noteId, teamPath} from '../../flags'
 
 export default class IndexCommand extends HackMDCommand {
   static description = 'HackMD team-notes commands'
@@ -11,9 +11,11 @@ ID                     Title                            User path Team path
 ────────────────────── ──────────────────────────────── ──────── ────────
 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',
   ]
   static flags = {
     help: Flags.help({char: 'h'}),
+    noteId,
     teamPath,
     ...ux.table.flags(),
   }
@@ -27,7 +29,9 @@ BnC6gN0_TfStV2KKmPPXeg Welcome to your team's workspace null     CLI-test`,
 
     try {
       const APIClient = await this.getAPIClient()
-      const notes = await APIClient.getTeamNotes(flags.teamPath)
+      const notes = flags.noteId
+        ? [await APIClient.getTeamNote(flags.teamPath, flags.noteId)]
+        : await APIClient.getTeamNotes(flags.teamPath)
 
       ux.table(notes, {
         id: {
diff --git a/src/commands/team-notes/update.ts b/src/commands/team-notes/update.ts
index 5f22e92..c858675 100644
--- a/src/commands/team-notes/update.ts
+++ b/src/commands/team-notes/update.ts
@@ -4,7 +4,7 @@ import {Flags} from '@oclif/core'
 
 import HackMDCommand from '../../command'
 import {
-  noteContent, noteId, notePermission, noteTags, noteTitle, parentFolderId, permalink, teamPath,
+  clearFields, noteContent, noteDescription, noteId, notePermission, noteTags, noteTitle, parentFolderId, permalink, root, teamPath,
 } from '../../flags'
 import {buildNoteUpdatePayload} from '../../note-update'
 import {safeStdinRead} from '../../utils'
@@ -18,14 +18,19 @@ export default class Update extends HackMDCommand {
     '$ hackmd-cli team-notes update --teamPath=CLI-test --noteId=WNkLM6gkS0Cg2cQ8rv7bYA --readPermission=owner --writePermission=owner',
     '$ 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',
   ]
   static flags = {
+    clear: clearFields(['description']),
     content: noteContent,
+    description: noteDescription,
     help: Flags.help({char: 'h'}),
     noteId,
     parentFolderId,
     permalink,
     readPermission: notePermission(),
+    root,
     tags: noteTags,
     teamPath,
     title: noteTitle,
@@ -34,7 +39,7 @@ export default class Update extends HackMDCommand {
 
   async run() {
     const {flags} = await this.parse(Update)
-    const {content, noteId, parentFolderId, permalink, readPermission, tags, teamPath, title, writePermission} = flags
+    const {clear, content, description, noteId, parentFolderId, permalink, readPermission, root, tags, teamPath, title, writePermission} = flags
 
     if (!teamPath) {
       this.error('Flag teamPath could not be empty')
@@ -49,7 +54,7 @@ export default class Update extends HackMDCommand {
     try {
       payload = buildNoteUpdatePayload(
         {
-          content, parentFolderId, permalink, readPermission, tags, title, writePermission,
+          clear, content, description, parentFolderId, permalink, readPermission, root, tags, title, writePermission,
         },
         stdinContent,
       )
diff --git a/src/flags.ts b/src/flags.ts
index 2e569a0..818e5bf 100644
--- a/src/flags.ts
+++ b/src/flags.ts
@@ -19,6 +19,10 @@ export const noteTitle = Flags.string({
   description: 'new note title',
 })
 
+export const noteDescription = Flags.string({
+  description: 'note description',
+})
+
 export const folderName = Flags.string({
   description: 'folder name',
 })
@@ -27,6 +31,12 @@ export const folderDescription = Flags.string({
   description: 'folder description',
 })
 
+export const clearFields = (options: string[]) => Flags.string({
+  description: `clear fields: ${options.join(', ')} (repeatable)`,
+  multiple: true,
+  options,
+})
+
 export const folderIcon = Flags.string({
   description: 'folder icon',
 })
@@ -39,6 +49,10 @@ export const parentFolderId = Flags.string({
   description: 'parent folder id',
 })
 
+export const root = Flags.boolean({
+  description: 'move to the root folder',
+})
+
 export const folderOrder = Flags.string({
   description: 'folder order JSON, e.g. {"root":["folder-id"]}',
 })
diff --git a/src/folder-update.ts b/src/folder-update.ts
new file mode 100644
index 0000000..9fd6278
--- /dev/null
+++ b/src/folder-update.ts
@@ -0,0 +1,37 @@
+import type {UpdateUserFolderBody} from '@hackmd/api'
+
+export type FolderUpdateFlags = {
+  clear?: string[]
+  color?: string
+  description?: string
+  icon?: string
+  name?: string
+  parentFolderId?: string
+  root?: boolean
+}
+
+export function buildFolderUpdatePayload(flags: FolderUpdateFlags): UpdateUserFolderBody {
+  if (flags.root && flags.parentFolderId !== undefined) {
+    throw new Error('Use either --root or --parentFolderId, not both')
+  }
+
+  const payload: UpdateUserFolderBody = {}
+  if (flags.name !== undefined) payload.name = flags.name
+  if (flags.description !== undefined) payload.description = flags.description
+  if (flags.icon !== undefined) payload.icon = flags.icon
+  if (flags.color !== undefined) payload.color = flags.color
+  if (flags.parentFolderId !== undefined) payload.parentFolderId = flags.parentFolderId
+
+  for (const field of flags.clear ?? []) {
+    if (field !== 'description' && field !== 'icon' && field !== 'color') {
+      throw new Error(`Cannot clear folder field: ${field}`)
+    }
+
+    if (flags[field] !== undefined) throw new Error(`Use either --${field} or --clear=${field}, not both`)
+    payload[field] = null
+  }
+
+  if (flags.root) payload.parentFolderId = null
+
+  return payload
+}
diff --git a/src/note-update.ts b/src/note-update.ts
index ceaef4a..c746206 100644
--- a/src/note-update.ts
+++ b/src/note-update.ts
@@ -1,28 +1,44 @@
 import type {NotePermissionRole, UpdateNoteOptions} from '@hackmd/api'
 
 export type NoteUpdateFlags = {
+  clear?: string[]
   content?: string
+  description?: string
   parentFolderId?: string
   permalink?: string
   readPermission?: string
+  root?: boolean
   tags?: string
   title?: string
   writePermission?: string
 }
 
 export function buildNoteUpdatePayload(
-  {content, parentFolderId, permalink, readPermission, tags, title, writePermission}: NoteUpdateFlags,
+  {clear = [], content, description, parentFolderId, permalink, readPermission, root, tags, title, writePermission}: NoteUpdateFlags,
   stdinContent?: string,
 ): UpdateNoteOptions {
   if (stdinContent && content !== undefined) {
     throw new Error('Content cannot be provided from both stdin and --content')
   }
 
+  if (root && parentFolderId !== undefined) {
+    throw new Error('Use either --root or --parentFolderId, not both')
+  }
+
   const payload: UpdateNoteOptions = {}
   const resolvedContent = stdinContent || content
 
   if (resolvedContent !== undefined) payload.content = resolvedContent
+  if (description !== undefined) payload.description = description
+
+  for (const field of clear) {
+    if (field !== 'description') throw new Error(`Cannot clear note field: ${field}`)
+    if (description !== undefined) throw new Error('Use either --description or --clear=description, not both')
+    payload.description = null
+  }
+
   if (parentFolderId !== undefined) payload.parentFolderId = parentFolderId
+  if (root) payload.parentFolderId = null
   if (readPermission !== undefined) payload.readPermission = readPermission as NotePermissionRole
   if (writePermission !== undefined) payload.writePermission = writePermission as NotePermissionRole
   if (permalink !== undefined) payload.permalink = permalink
diff --git a/test/folder-update.test.ts b/test/folder-update.test.ts
new file mode 100644
index 0000000..fccdedd
--- /dev/null
+++ b/test/folder-update.test.ts
@@ -0,0 +1,51 @@
+import {expect} from 'chai'
+
+import FoldersUpdate from '../src/commands/folders/update'
+import TeamFoldersUpdate from '../src/commands/team-folders/update'
+import {buildFolderUpdatePayload} from '../src/folder-update'
+
+describe('Folder update payload', () => {
+  it('exposes root and clear flags for personal and team folders', () => {
+    for (const command of [FoldersUpdate, TeamFoldersUpdate]) {
+      for (const flag of ['root', 'clear']) {
+        expect(command.flags).to.have.property(flag)
+      }
+    }
+  })
+
+  it('omits unchanged fields', () => {
+    expect(buildFolderUpdatePayload({name: 'Docs'})).to.deep.equal({name: 'Docs'})
+  })
+
+  it('preserves an empty string when setting a field', () => {
+    expect(buildFolderUpdatePayload({description: ''})).to.deep.equal({description: ''})
+  })
+
+  it('uses null only for explicitly cleared fields', () => {
+    expect(buildFolderUpdatePayload({
+      clear: ['color', 'description', 'icon'],
+      root: true,
+    })).to.deep.equal({
+      color: null,
+      description: null,
+      icon: null,
+      parentFolderId: null,
+    })
+  })
+
+  it('rejects root with a parent folder ID', () => {
+    expect(() => buildFolderUpdatePayload({parentFolderId: 'folder-id', root: true}))
+    .to.throw('Use either --root or --parentFolderId, not both')
+  })
+
+  it('rejects fields that cannot be cleared', () => {
+    expect(() => buildFolderUpdatePayload({clear: ['name']})).to.throw('Cannot clear folder field: name')
+  })
+
+  for (const field of ['color', 'description', 'icon'] as const) {
+    it(`rejects --${field} with --clear=${field}`, () => {
+      expect(() => buildFolderUpdatePayload({clear: [field], [field]: 'value'}))
+      .to.throw(`Use either --${field} or --clear=${field}, not both`)
+    })
+  }
+})
diff --git a/test/integration/api.test.ts b/test/integration/api.test.ts
new file mode 100644
index 0000000..ff93a17
--- /dev/null
+++ b/test/integration/api.test.ts
@@ -0,0 +1,289 @@
+import {expect} from 'chai'
+import {spawn} from 'node:child_process'
+import {mkdtempSync, rmSync, writeFileSync} from 'node:fs'
+import {createServer, IncomingMessage, ServerResponse} from 'node:http'
+import {createRequire} from 'node:module'
+import {tmpdir} from 'node:os'
+import path from 'node:path'
+
+type Result = {code: null | number; stderr: string; stdout: string}
+
+function run(args: string[], endpoint: string, configDir: string, input?: string): Promise<Result> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [path.join(process.cwd(), 'bin/run'), ...args], {
+      env: {
+        ...process.env, HMD_API_ACCESS_TOKEN: 'test-token', HMD_API_ENDPOINT_URL: endpoint, HMD_CLI_CONFIG_DIR: configDir, NODE_ENV: 'production',
+      },
+    })
+    let stdout = ''
+    let stderr = ''
+    child.stdout.on('data', chunk => {
+      stdout += chunk
+    })
+    child.stderr.on('data', chunk => {
+      stderr += chunk
+    })
+    child.on('error', reject)
+    child.on('close', code => resolve({code, stderr, stdout}))
+    if (input === undefined) child.stdin.end()
+    else child.stdin.end(input)
+  })
+}
+
+describe('CLI commands with local API client', () => {
+  const configDir = mkdtempSync(path.join(tmpdir(), 'hackmd-cli-api-'))
+  const requests: Array<{authorization: string | undefined; body: string; contentType: string | undefined; url: string | undefined}> = []
+  let endpoint = ''
+  let status = 200
+  let responseBody = '{}'
+  let contentType = 'application/json'
+  const server = createServer(async (request: IncomingMessage, response: ServerResponse) => {
+    const chunks: Buffer[] = []
+    for await (const chunk of request) chunks.push(Buffer.from(chunk))
+    requests.push({
+      authorization: request.headers.authorization,
+      body: Buffer.concat(chunks).toString(),
+      contentType: request.headers['content-type'],
+      url: request.url,
+    })
+    response.writeHead(status, {'Content-Type': contentType, ETag: '"v1"'})
+    response.end(status === 204 || status === 304 ? undefined : responseBody)
+  })
+
+  before(async () => {
+    await new Promise<void>(resolve => {
+      server.listen(0, '127.0.0.1', resolve)
+    })
+    const address = server.address()
+    if (!address || typeof address === 'string') throw new Error('Expected a local TCP address')
+    endpoint = `http://127.0.0.1:${address.port}/v1`
+  })
+
+  after(async () => {
+    await new Promise<void>((resolve, reject) => {
+      server.close(error => error ? reject(error) : resolve())
+    })
+    rmSync(configDir, {force: true, recursive: true})
+  })
+
+  beforeEach(() => {
+    requests.length = 0
+    status = 200
+    responseBody = '{}'
+    contentType = 'application/json'
+  })
+
+  it('loads the CJS raw entry and lists/describes operations offline', async () => {
+    const raw = createRequire(path.join(process.cwd(), 'package.json'))('@hackmd/api/raw')
+    expect(raw.operationRegistry.GetTeamNote.call).to.be.a('function')
+    const help = await run(['api', '--help'], 'http://127.0.0.1:1/v1', configDir)
+    expect(help.code).to.equal(0)
+    expect(help.stdout).to.include('Explore and call HackMD API operations')
+    const list = await run(['api', 'operations'], 'http://127.0.0.1:1/v1', configDir)
+    expect(list.code).to.equal(0)
+    expect(list.stdout).to.include('Available API operations:')
+    expect(list.stdout).to.include('GetTeamNote')
+    const describe = await run(['api', 'describe', 'GetTeamNote'], 'http://127.0.0.1:1/v1', configDir)
+    expect(describe.code).to.equal(0)
+    const operation = JSON.parse(describe.stdout)
+    expect(operation.path).to.equal('/teams/{teampath}/notes/{noteId}')
+    expect(operation.parameters.map((parameter: {name: string}) => parameter.name)).to.include.members(['teampath', 'noteId'])
+    expect(requests).to.have.length(0)
+  })
+
+  it('uses token, custom endpoint, path, query and response headers', async () => {
+    responseBody = JSON.stringify({id: 'abc'})
+    const result = await run(['api', 'call', 'GetTeamNote', '--path', 'teampath=docs', '--path', 'noteId=abc', '--include'], endpoint, configDir)
+    expect(result.code, result.stderr).to.equal(0)
+    expect(result.stdout).to.include('HTTP 200')
+    expect(result.stdout).to.include('"id": "abc"')
+    expect(requests).to.have.length(1)
+    expect(requests[0].url).to.equal('/v1/teams/docs/notes/abc')
+    expect(requests[0].authorization).to.equal('Bearer test-token')
+    const query = await run(['api', 'call', 'ListVersions', '--path', 'noteId=abc', '--query', 'limit=2'], endpoint, configDir)
+    expect(query.code, query.stderr).to.equal(0)
+    expect(requests[1].url).to.equal('/v1/notes/abc/versions?limit=2')
+  })
+
+  it('handles documented no-body statuses without printing the generated empty object', async () => {
+    status = 304
+    const notModified = await run(['api', 'call', 'GetNote', '--path', 'noteId=abc', '--header', 'If-None-Match: "v1"', '--include'], endpoint, configDir)
+    expect(notModified.code, notModified.stderr).to.equal(0)
+    expect(notModified.stdout).to.include('HTTP 304')
+    expect(notModified.stdout).not.to.include('{}')
+    status = 204
+    const restored = await run(['api', 'call', 'RestoreNote', '--path', 'noteId=abc'], endpoint, configDir)
+    expect(restored.code, restored.stderr).to.equal(0)
+    expect(restored.stdout).to.equal('')
+    status = 202
+    const updated = await run(['api', 'call', 'UpdateNote', '--path', 'noteId=abc', '--body', '{"content":"updated"}'], endpoint, configDir)
+    expect(updated.code, updated.stderr).to.equal(0)
+    expect(updated.stdout).to.equal('')
+  })
+
+  it('sends JSON once and prints a 207 response', async () => {
+    status = 207
+    responseBody = JSON.stringify({error: 'partial', note: {id: 'abc'}})
+    const result = await run(['api', 'call', 'CreateNote', '--body', '{"content":"hello"}'], endpoint, configDir)
+    expect(result.code, result.stderr).to.equal(0)
+    expect(result.stdout).to.include('"partial"')
+    expect(requests).to.have.length(1)
+    expect(JSON.parse(requests[0].body)).to.deep.equal({content: 'hello'})
+    const filePath = path.join(configDir, 'note.json')
+    writeFileSync(filePath, '{"content":"from file"}')
+    const fromFile = await run(['api', 'call', 'CreateNote', '--body', `@${filePath}`], endpoint, configDir)
+    expect(fromFile.code, fromFile.stderr).to.equal(0)
+    expect(JSON.parse(requests[1].body)).to.deep.equal({content: 'from file'})
+    const fromStdin = await run(['api', 'call', 'CreateNote', '--body', '-'], endpoint, configDir, '{"content":"from stdin"}')
+    expect(fromStdin.code, fromStdin.stderr).to.equal(0)
+    expect(JSON.parse(requests[2].body)).to.deep.equal({content: 'from stdin'})
+  })
+
+  it('uploads multipart with inferred MIME and supports NDJSON text', async () => {
+    const imagePath = path.join(configDir, 'image.png')
+    writeFileSync(imagePath, Buffer.from([0x89, 0x50, 0x4E, 0x47]))
+    const upload = await run(['api', 'call', 'UploadNoteImage', '--path', 'noteId=abc', '--file', `image=@${imagePath}`], endpoint, configDir)
+    expect(upload.code, upload.stderr).to.equal(0)
+    expect(requests[0].contentType).to.include('multipart/form-data')
+    expect(requests[0].body).to.include('image/png')
+    expect(requests[0].body).to.include('filename="image.png"')
+    const uploadWithMime = await run(['api', 'call', 'UploadNoteImage', '--path', 'noteId=abc', '--file', `image=@${imagePath}`, '--mime', 'image/jpeg'], endpoint, configDir)
+    expect(uploadWithMime.code, uploadWithMime.stderr).to.equal(0)
+    expect(requests[1].body).to.include('image/jpeg')
+    contentType = 'application/x-ndjson'
+    responseBody = '{"id":1}\n{"id":2}\n'
+    const exportResult = await run(['api', 'call', 'ExportWebhookDeliveries', '--path', 'hookId=abc'], endpoint, configDir)
+    expect(exportResult.code, exportResult.stderr).to.equal(0)
+    expect(exportResult.stdout).to.equal(responseBody)
+  })
+
+  it('rejects unknown parameters before making a request and reports HTTP errors', async () => {
+    const invalid = await run(['api', 'call', 'GetNote', '--path', 'wrong=abc'], endpoint, configDir)
+    expect(invalid.code).not.to.equal(0)
+    expect(invalid.stderr).to.include('Missing required --path noteId')
+    expect(requests).to.have.length(0)
+    status = 404
+    responseBody = JSON.stringify({error: 'Note not found'})
+    const notFound = await run(['api', 'call', 'GetNote', '--path', 'noteId=abc'], endpoint, configDir)
+    expect(notFound.code).not.to.equal(0)
+    expect(notFound.stderr).to.include('HTTP 404')
+    expect(notFound.stderr).to.include('Note not found')
+  })
+
+  it('passes descriptions when creating personal and team notes', async () => {
+    responseBody = JSON.stringify({id: 'abc', tags: [], title: 'Test'})
+    const personal = await run(['notes', 'create', '--title=Test', '--description=Personal'], endpoint, configDir)
+    expect(personal.code, personal.stderr).to.equal(0)
+    const personalRequest = requests.find(request => request.url === '/v1/notes')
+    expect(JSON.parse(personalRequest!.body)).to.include({description: 'Personal'})
+
+    requests.length = 0
+    const team = await run(['team-notes', 'create', '--teamPath=docs', '--title=Test', '--description=Team'], endpoint, configDir)
+    expect(team.code, team.stderr).to.equal(0)
+    const teamRequest = requests.find(request => request.url === '/v1/teams/docs/notes')
+    expect(JSON.parse(teamRequest!.body)).to.include({description: 'Team'})
+  })
+
+  it('passes description and null root placement when updating personal and team notes', async () => {
+    status = 202
+    const personal = await run(['notes', 'update', '--noteId=abc', '--description=', '--root'], endpoint, configDir)
+    expect(personal.code, personal.stderr).to.equal(0)
+    const personalRequest = requests.find(request => request.url === '/v1/notes/abc')
+    expect(JSON.parse(personalRequest!.body)).to.deep.equal({description: '', parentFolderId: null})
+
+    requests.length = 0
+    const team = await run(['team-notes', 'update', '--teamPath=docs', '--noteId=abc', '--description=Team', '--root'], endpoint, configDir)
+    expect(team.code, team.stderr).to.equal(0)
+    const teamRequest = requests.find(request => request.url === '/v1/teams/docs/notes/abc')
+    expect(JSON.parse(teamRequest!.body)).to.deep.equal({description: 'Team', parentFolderId: null})
+  })
+
+  it('clears nullable personal and team folder fields without changing omitted fields', async () => {
+    status = 202
+    const personal = await run(['folders', 'update', '--folderId=abc', '--clear=description', '--root'], endpoint, configDir)
+    expect(personal.code, personal.stderr).to.equal(0)
+    const personalRequest = requests.find(request => request.url === '/v1/folders/abc')
+    expect(JSON.parse(personalRequest!.body)).to.deep.equal({description: null, parentFolderId: null})
+
+    requests.length = 0
+    const team = await run(['team-folders', 'update', '--teamPath=docs', '--folderId=abc', '--clear=color', '--clear=icon'], endpoint, configDir)
+    expect(team.code, team.stderr).to.equal(0)
+    const teamRequest = requests.find(request => request.url === '/v1/teams/docs/folders/abc')
+    expect(JSON.parse(teamRequest!.body)).to.deep.equal({color: null, icon: null})
+  })
+
+  it('clears personal and team note descriptions with null', async () => {
+    status = 202
+    const personal = await run(['notes', 'update', '--noteId=abc', '--clear=description'], endpoint, configDir)
+    expect(personal.code, personal.stderr).to.equal(0)
+
+    const team = await run(['team-notes', 'update', '--teamPath=docs', '--noteId=abc', '--clear=description'], endpoint, configDir)
+    expect(team.code, team.stderr).to.equal(0)
+    const personalRequest = requests.find(request => request.url === '/v1/notes/abc')
+    const teamRequest = requests.find(request => request.url === '/v1/teams/docs/notes/abc')
+    expect(JSON.parse(personalRequest!.body)).to.deep.equal({description: null})
+    expect(JSON.parse(teamRequest!.body)).to.deep.equal({description: null})
+  })
+
+  it('reads one team note and passes a history limit', async () => {
+    responseBody = JSON.stringify({id: 'abc', tags: [], title: 'Team note'})
+    const note = await run(['team-notes', '--teamPath=docs', '--noteId=abc'], endpoint, configDir)
+    expect(note.code, note.stderr).to.equal(0)
+    expect(note.stdout).to.include('Team note')
+    expect(requests.some(request => request.url === '/v1/teams/docs/notes/abc')).to.be.true
+
+    requests.length = 0
+    responseBody = '[]'
+    const history = await run(['history', '--limit=5'], endpoint, configDir)
+    expect(history.code, history.stderr).to.equal(0)
+    expect(requests.some(request => request.url === '/v1/history?limit=5')).to.be.true
+  })
+
+  for (const [args, url, body] of [
+    [['notes', 'update', '--noteId=abc', '--title=Changed'], '/v1/notes/abc', {title: 'Changed'}],
+    [['team-notes', 'update', '--teamPath=docs', '--noteId=abc', '--title=Changed'], '/v1/teams/docs/notes/abc', {title: 'Changed'}],
+    [['folders', 'update', '--folderId=abc', '--name=Changed'], '/v1/folders/abc', {name: 'Changed'}],
+    [['team-folders', 'update', '--teamPath=docs', '--folderId=abc', '--name=Changed'], '/v1/teams/docs/folders/abc', {name: 'Changed'}],
+  ] as const) {
+    it(`keeps omitted ${args[0]} update fields unchanged`, async () => {
+      status = 202
+      const result = await run([...args], endpoint, configDir)
+      expect(result.code, result.stderr).to.equal(0)
+      const request = requests.find(request => request.url === url)
+      expect(JSON.parse(request!.body)).to.deep.equal(body)
+    })
+  }
+
+  it('keeps the default team list and history requests unchanged', async () => {
+    responseBody = '[]'
+    const team = await run(['team-notes', '--teamPath=docs'], endpoint, configDir)
+    expect(team.code, team.stderr).to.equal(0)
+    expect(requests.some(request => request.url === '/v1/teams/docs/notes')).to.be.true
+
+    const history = await run(['history'], endpoint, configDir)
+    expect(history.code, history.stderr).to.equal(0)
+    expect(requests.some(request => request.url === '/v1/history')).to.be.true
+  })
+
+  it('rejects conflicting and invalid flags before sending any request', async () => {
+    const rootConflict = await run(['notes', 'update', '--noteId=abc', '--parentFolderId=folder', '--root'], endpoint, configDir)
+    expect(rootConflict.code).not.to.equal(0)
+    expect(rootConflict.stderr).to.include('Use either --root or --parentFolderId')
+
+    const clearConflict = await run(['folders', 'update', '--folderId=abc', '--description=Text', '--clear=description'], endpoint, configDir)
+    expect(clearConflict.code).not.to.equal(0)
+    expect(clearConflict.stderr).to.include('Use either --description or --clear=description')
+
+    const noteConflict = await run(['notes', 'update', '--noteId=abc', '--description=', '--clear=description'], endpoint, configDir)
+    expect(noteConflict.code).not.to.equal(0)
+    expect(noteConflict.stderr).to.include('Use either --description or --clear=description')
+
+    const invalidClear = await run(['notes', 'update', '--noteId=abc', '--clear=icon'], endpoint, configDir)
+    expect(invalidClear.code).not.to.equal(0)
+
+    const invalidLimit = await run(['history', '--limit=0'], endpoint, configDir)
+    expect(invalidLimit.code).not.to.equal(0)
+    expect(invalidLimit.stderr).to.include('Flag limit must be a positive integer')
+    expect(requests).to.have.length(0)
+  })
+})
diff --git a/test/note-update.test.ts b/test/note-update.test.ts
index 039bab1..f1c6f26 100644
--- a/test/note-update.test.ts
+++ b/test/note-update.test.ts
@@ -1,6 +1,8 @@
 import {expect} from 'chai'
 
+import NotesCreate from '../src/commands/notes/create'
 import NotesUpdate from '../src/commands/notes/update'
+import TeamNotesCreate from '../src/commands/team-notes/create'
 import TeamNotesUpdate from '../src/commands/team-notes/update'
 import {buildNoteUpdatePayload} from '../src/note-update'
 
@@ -10,6 +12,12 @@ describe('Note update payload', () => {
     expect(TeamNotesUpdate.flags).to.have.property('title')
   })
 
+  it('exposes --description for personal and team create and update', () => {
+    for (const command of [NotesCreate, TeamNotesCreate, NotesUpdate, TeamNotesUpdate]) {
+      expect(command.flags).to.have.property('description')
+    }
+  })
+
   it('uses piped stdin content without changing it', () => {
     const content = '# Piped content\n\nBody with trailing newline.\n'
 
@@ -56,4 +64,35 @@ describe('Note update payload', () => {
   it('allows an explicit empty --title value', () => {
     expect(buildNoteUpdatePayload({title: ''})).to.deep.equal({title: ''})
   })
+
+  it('preserves an empty description and moves a note to root with null', () => {
+    expect(buildNoteUpdatePayload({description: '', root: true})).to.deep.equal({
+      description: '',
+      parentFolderId: null,
+    })
+  })
+
+  it('rejects both root and a parent folder ID', () => {
+    expect(() => buildNoteUpdatePayload({parentFolderId: 'folder-id', root: true}))
+    .to.throw('Use either --root or --parentFolderId, not both')
+  })
+
+  it('exposes --clear for personal and team note updates', () => {
+    for (const command of [NotesUpdate, TeamNotesUpdate]) expect(command.flags).to.have.property('clear')
+  })
+
+  it('clears a description with null', () => {
+    expect(buildNoteUpdatePayload({clear: ['description']})).to.deep.equal({description: null})
+  })
+
+  it('rejects clearing and setting the same description, including an empty string', () => {
+    for (const description of ['Text', '']) {
+      expect(() => buildNoteUpdatePayload({clear: ['description'], description}))
+      .to.throw('Use either --description or --clear=description, not both')
+    }
+  })
+
+  it('rejects fields that cannot be cleared', () => {
+    expect(() => buildNoteUpdatePayload({clear: ['title']})).to.throw('Cannot clear note field: title')
+  })
 })
diff --git a/test/smoke/cli.test.ts b/test/smoke/cli.test.ts
index e18ccf5..29b4128 100644
--- a/test/smoke/cli.test.ts
+++ b/test/smoke/cli.test.ts
@@ -58,6 +58,7 @@ describe('Smoke Tests: Built CLI Binary', () => {
   async function runCLI(args: string[] = [], options: {env?: NodeJS.ProcessEnv} = {}): Promise<{code: null | number; stderr: string; stdout: string;}> {
     const env = {
       ...process.env,
+      NODE_ENV: 'production',
       ...options.env,
     }
 
@@ -157,6 +158,15 @@ describe('Smoke Tests: Built CLI Binary', () => {
   })
 
   describe('Command structure verification', () => {
+    for (const topic of ['notes', 'team-notes', 'folders', 'team-folders']) {
+      it(`shows the new update flags in ${topic} help`, async () => {
+        const result = await runCLI([topic, 'update', '--help'])
+        expect(result.code, result.stderr).to.equal(0)
+        for (const flag of ['--description', '--clear', '--root']) expect(result.stdout).to.include(flag)
+        if (topic.includes('folders')) expect(result.stdout).to.include('description|icon|color')
+      })
+    }
+
     it('should recognize notes command', async () => {
       const result = await runCLI(['notes', '--help'])
       // Command should execute (even if it requires auth) and produce output
diff --git a/tsconfig.json b/tsconfig.json
index ab53f7f..3121cf6 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -2,11 +2,12 @@
   "compilerOptions": {
     "declaration": true,
     "importHelpers": true,
-    "module": "commonjs",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
     "outDir": "lib",
     "rootDir": "src",
     "strict": true,
-    "target": "es2017",
+    "target": "ES2022",
     "esModuleInterop": true,
     "skipLibCheck": true
   },