diff --git a/docs/src/pages/migrations.md b/docs/src/pages/migrations.md
index 9b7639366..0de359e06 100644
--- a/docs/src/pages/migrations.md
+++ b/docs/src/pages/migrations.md
@@ -33,6 +33,15 @@ This will be the next version of Woodpecker.
 - Removed old API routes: `registry/` -> `registries`, `/authorize/token`
 - Replaced `registry` command with `repo registry` in cli
 - Deprecated `secrets`, use `environment` with `from_secret`
+- CLI commands got restructured to provide a simplified structure:
+  - `woodpecker-cli secret [add|rm|...] --global` is now `woodpecker-cli admin secret [add|rm|...]`
+  - `woodpecker-cli user` is now `woodpecker-cli admin user`
+  - `woodpecker-cli log-level` is now `woodpecker-cli admin log-level`
+  - `woodpecker-cli secret [add|rm|...] --organization` is now `woodpecker-cli org secret [add|rm|...]`
+  - `woodpecker-cli deploy` is now `woodpecker-cli pipeline deploy`
+  - `woodpecker-cli log` is now `woodpecker-cli pipeline log`
+  - `woodpecker-cli cron` is now `woodpecker-cli repo cron`
+  - `woodpecker-cli secret [add|rm|...] --repository` is now `woodpecker-cli repo secret [add|rm|...]`
 
 ## Admin migrations