diff --git a/docs/generate_command_docs.py b/docs/generate_command_docs.py
new file mode 100644
index 00000000..1e732934
--- /dev/null
+++ b/docs/generate_command_docs.py
@@ -0,0 +1,149 @@
+"""This module generates reference docs for pebble CLI commands."""
+
+import logging
+import os
+import re
+import subprocess
+import typing
+
+
+logger = logging.getLogger(__name__)
+logging.basicConfig(level=logging.INFO)
+
+AUTOMATED_START_MARKER = "<!-- START AUTOMATED OUTPUT -->"
+AUTOMATED_STOP_MARKER = "<!-- END AUTOMATED OUTPUT -->"
+
+TEMPLATE = """\
+(reference_pebble_{command}_command)=
+# {command} command
+
+{description}
+
+## Usage
+
+<!-- START AUTOMATED OUTPUT -->
+```{{terminal}}
+   :input: command
+```
+<!-- END AUTOMATED OUTPUT -->
+"""
+
+
+def get_all_commands() -> typing.List[typing.Tuple[str, str]]:
+    process = subprocess.run(
+        ["go", "run", "../cmd/pebble", "help", "--all"],
+        text=True,
+        capture_output=True,
+        check=True,
+    )
+    return sorted(
+        line.split(maxsplit=1)
+        for line in process.stdout.splitlines()
+        if line.startswith("    ")
+    )
+
+
+def get_command_help_output(cmd: typing.List[str]) -> str:
+    return subprocess.run(cmd, text=True, capture_output=True, check=True).stdout
+
+
+def render_code_block_cmd(text: str, cmd: str) -> str:
+    return re.sub(r"(:input: ).*$", rf"\1{cmd}", text, count=1, flags=re.MULTILINE)
+
+
+def render_code_block_output(text: str, output: str) -> str:
+    start_pos = text.find(AUTOMATED_START_MARKER)
+    end_pos = text.find(AUTOMATED_STOP_MARKER) + len(AUTOMATED_STOP_MARKER)
+    return text[:start_pos] + output + text[end_pos:]
+
+
+def update_toc(cmds: typing.List[typing.Tuple[str, str]]):
+    index_page = "reference/cli-commands/cli-commands.md"
+    with open(index_page, "r") as file:
+        text = file.read()
+
+    start_index = text.find("```{toctree}")
+    end_index = text.find("```", start_index + 1) + 3
+    cmd_list = "\n".join(f"{cmd[0]} <{cmd[0]}>" for cmd in cmds)
+
+    toc_tree = f"""\
+```{{toctree}}
+:titlesonly:
+:maxdepth: 1
+
+{cmd_list}
+```"""
+
+    text = text[:start_index] + toc_tree + text[end_index:]
+    with open(index_page, "w") as file:
+        file.write(text)
+
+
+def create_file_if_not_exist(filepath: str, cmd: str) -> bool:
+    file_existed = os.path.exists(filepath)
+    if not file_existed:
+        logger.info(
+            "The doc for command %s doesn't exist, creating from the template.", cmd
+        )
+        with open(filepath, "w") as file:
+            file.write(TEMPLATE)
+    return file_existed
+
+
+def generate_help_command_and_output(cmd: str) -> typing.Tuple[str, str]:
+    help_cmd = ["pebble", "help"] if cmd == "help" else ["pebble", cmd, "--help"]
+    help_cmd_str = " ".join(help_cmd)
+    help_cmd_output = get_command_help_output(help_cmd).strip()
+
+    output = f"""\
+<!-- START AUTOMATED OUTPUT -->
+```{{terminal}}
+:input: {help_cmd_str}
+{help_cmd_output}
+```
+<!-- END AUTOMATED OUTPUT -->"""
+
+    return help_cmd, output
+
+
+def process_command(cmd: str, description: str):
+    logger.info("Processing doc for command %s.", cmd)
+
+    file_path = f"reference/cli-commands/{cmd}.md"
+    file_existed = create_file_if_not_exist(file_path, cmd)
+
+    with open(file_path, "r") as file:
+        text = file.read()
+
+    if AUTOMATED_START_MARKER not in text:
+        logger.info(
+            'The marker for automated doc generation is not found in the "%s" doc, ignore.',
+            cmd,
+        )
+        return
+
+    help_cmd, help_cmd_output = generate_help_command_and_output(cmd)
+    description = f"The `{cmd}` command is used to {description.lower()}."
+
+    if not file_existed:
+        text = text.format(command=cmd, description=description)
+
+    text = render_code_block_cmd(text, help_cmd)
+    text = render_code_block_output(text, help_cmd_output)
+
+    with open(file_path, "w") as file:
+        file.write(text)
+
+
+def main():
+    cmds = get_all_commands()
+    for cmd, description in cmds:
+        process_command(cmd, description)
+
+    logger.info("Update toc tree.")
+    update_toc(cmds)
+    logger.info("Done!")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/docs/reference/cli-commands/add-identities.md b/docs/reference/cli-commands/add-identities.md
new file mode 100644
index 00000000..c6e590ce
--- /dev/null
+++ b/docs/reference/cli-commands/add-identities.md
@@ -0,0 +1,29 @@
+(reference_pebble_add-identities_command)=
+# add-identities command
+
+The `add-identities` command is used to add new identities.
+
+## Usage
+
+<!-- START AUTOMATED OUTPUT -->
+```{terminal}
+:input: pebble add-identities --help
+Usage:
+  pebble add-identities [add-identities-OPTIONS]
+
+The add-identities command adds one or more new identities.
+
+The named identities must not yet exist.
+
+For example, to add a local admin named "bob", use YAML like this:
+
+> identities:
+>     bob:
+>         access: admin
+>         local:
+>             user-id: 42
+
+[add-identities command options]
+      --from=   Path of YAML file to read identities from (required)
+```
+<!-- END AUTOMATED OUTPUT -->
diff --git a/docs/reference/cli-commands/add.md b/docs/reference/cli-commands/add.md
new file mode 100644
index 00000000..206570b5
--- /dev/null
+++ b/docs/reference/cli-commands/add.md
@@ -0,0 +1,22 @@
+(reference_pebble_add_command)=
+# add command
+
+The `add` command is used to dynamically add a layer to the plan's layers.
+
+## Usage
+
+<!-- START AUTOMATED OUTPUT -->
+```{terminal}
+:input: pebble add --help
+Usage:
+  pebble add [add-OPTIONS] <label> <layer-path>
+
+The add command reads the plan's layer YAML from the path specified and
+appends a layer with the given label to the plan's layers. If --combine
+is specified, combine the layer with an existing layer that has the given
+label (or append if the label is not found).
+
+[add command options]
+      --combine         Combine the new layer with an existing layer that has the given label (default is to append)
+```
+<!-- END AUTOMATED OUTPUT -->
diff --git a/docs/reference/cli-commands/changes.md b/docs/reference/cli-commands/changes.md
new file mode 100644
index 00000000..0ea7858a
--- /dev/null
+++ b/docs/reference/cli-commands/changes.md
@@ -0,0 +1,19 @@
+(reference_pebble_changes_command)=
+# changes command
+
+The `changes` command is used to list system changes.
+
+## Usage
+
+<!-- START AUTOMATED OUTPUT -->
+```{terminal}
+:input: pebble changes --help
+Usage:
+  pebble changes [changes-OPTIONS] [<service>]
+
+The changes command displays a summary of system changes performed recently.
+
+[changes command options]
+      --abs-time     Display absolute times (in RFC 3339 format). Otherwise, display relative times up to 60 days, then YYYY-MM-DD.
+```
+<!-- END AUTOMATED OUTPUT -->
diff --git a/docs/reference/cli-commands/checks.md b/docs/reference/cli-commands/checks.md
new file mode 100644
index 00000000..6e4e6bb1
--- /dev/null
+++ b/docs/reference/cli-commands/checks.md
@@ -0,0 +1,21 @@
+(reference_pebble_checks_command)=
+# checks command
+
+The `checks` command is used to query the status of configured health checks.
+
+## Usage
+
+<!-- START AUTOMATED OUTPUT -->
+```{terminal}
+:input: pebble checks --help
+Usage:
+  pebble checks [checks-OPTIONS] [<check>...]
+
+The checks command lists status information about the configured health
+checks, optionally filtered by level and check names provided as positional
+arguments.
+
+[checks command options]
+      --level=[alive|ready]   Check level to filter for
+```
+<!-- END AUTOMATED OUTPUT -->
diff --git a/docs/reference/cli-commands/cli-commands.md b/docs/reference/cli-commands/cli-commands.md
index 838d785f..f2388b8c 100644
--- a/docs/reference/cli-commands/cli-commands.md
+++ b/docs/reference/cli-commands/cli-commands.md
@@ -1,14 +1,45 @@
 # CLI Commands
 
+Pebble uses subcommands, like some other command-line tools such as go tool or git.
+
+Subcommands are keywords that invoke a new set of options and features, and each Pebble subcommand has its own set of flags.
+
+Here's the list of all Pebble subcommands:
+
 ```{toctree}
 :titlesonly:
 :maxdepth: 1
 
+add <add>
+add-identities <add-identities>
+changes <changes>
+checks <checks>
+exec <exec>
+health <health>
 help <help>
+identities <identities>
+identity <identity>
 logs <logs>
+ls <ls>
+mkdir <mkdir>
+notice <notice>
+notices <notices>
+notify <notify>
+okay <okay>
+plan <plan>
+pull <pull>
+push <push>
+remove-identities <remove-identities>
 replan <replan>
+restart <restart>
+rm <rm>
 run <run>
 services <services>
+signal <signal>
 start <start>
 stop <stop>
+tasks <tasks>
+update-identities <update-identities>
+version <version>
+warnings <warnings>
 ```
diff --git a/docs/reference/cli-commands/exec.md b/docs/reference/cli-commands/exec.md
new file mode 100644
index 00000000..f445ebab
--- /dev/null
+++ b/docs/reference/cli-commands/exec.md
@@ -0,0 +1,37 @@
+(reference_pebble_exec_command)=
+# exec command
+
+The `exec` command is used to execute a remote command and wait for it to finish.
+
+## Usage
+
+<!-- START AUTOMATED OUTPUT -->
+```{terminal}
+:input: pebble exec --help
+Usage:
+  pebble exec [exec-OPTIONS] <command>
+
+The exec command runs a remote command and waits for it to finish. The local
+stdin is sent as the input to the remote process, while the remote stdout and
+stderr are output locally.
+
+To avoid confusion, exec options may be separated from the command and its
+arguments using "--", for example:
+
+pebble exec --timeout 10s -- echo -n foo bar
+
+[exec command options]
+      -w=              Working directory to run command in
+          --env=       Environment variable to set (in 'FOO=bar' format)
+          --uid=       User ID to run command as
+          --user=      Username to run command as (user's UID must match uid if both present)
+          --gid=       Group ID to run command as
+          --group=     Group name to run command as (group's GID must match gid if both present)
+          --timeout=   Timeout after which to terminate command
+          --context=   Inherit the context of the named service (overridden by -w, --env, --uid/user, --gid/group)
+      -t               Allocate remote pseudo-terminal and connect stdout to it (default if stdout is a TTY)
+      -T               Disable remote pseudo-terminal allocation
+      -i               Interactive mode: connect stdin to the pseudo-terminal (default if stdin and stdout are TTYs)
+      -I               Disable interactive mode and use a pipe for stdin
+```
+<!-- END AUTOMATED OUTPUT -->
diff --git a/docs/reference/cli-commands/health.md b/docs/reference/cli-commands/health.md
new file mode 100644
index 00000000..cfb14723
--- /dev/null
+++ b/docs/reference/cli-commands/health.md
@@ -0,0 +1,22 @@
+(reference_pebble_health_command)=
+# health command
+
+The `health` command is used to query health of checks.
+
+## Usage
+
+<!-- START AUTOMATED OUTPUT -->
+```{terminal}
+:input: pebble health --help
+Usage:
+  pebble health [health-OPTIONS] [<check>...]
+
+The health command queries the health of configured checks.
+
+It returns an exit code 0 if all the requested checks are healthy, or
+an exit code 1 if at least one of the requested checks are unhealthy.
+
+[health command options]
+      --level=[alive|ready]   Check level to filter for
+```
+<!-- END AUTOMATED OUTPUT -->
diff --git a/docs/reference/cli-commands/help.md b/docs/reference/cli-commands/help.md
index 8d9da2b9..9a23a018 100644
--- a/docs/reference/cli-commands/help.md
+++ b/docs/reference/cli-commands/help.md
@@ -1,5 +1,5 @@
 (reference_pebble_help_command)=
-# Pebble help command
+# help command
 
 Use the **help** command (`help` or `-h`) to get a summary or detailed
 information about available `pebble` commands.
@@ -8,18 +8,49 @@ information about available `pebble` commands.
 
 To display a summary about Pebble and the available commands, run:
 
-```bash
-pebble -h
+<!-- START AUTOMATED OUTPUT -->
+```{terminal}
+:input: pebble help
+Pebble lets you control services and perform management actions on
+the system that is running them.
+
+Usage: pebble <command> [<options>...]
+
+Commands can be classified as follows:
+
+         Run: run
+        Info: help, version
+        Plan: add, plan
+    Services: services, logs, start, restart, signal, stop, replan
+      Checks: checks, health
+       Files: push, pull, ls, mkdir, rm, exec
+     Changes: changes, tasks
+     Notices: warnings, okay, notices, notice, notify
+  Identities: identities --help
+
+Set the PEBBLE environment variable to override the configuration directory
+(which defaults to /var/lib/pebble/default). Set PEBBLE_SOCKET to override
+the unix socket used for the API (defaults to $PEBBLE/.pebble.socket).
+
+For more information about a command, run 'pebble help <command>'.
+For a short summary of all commands, run 'pebble help --all'.
 ```
+<!-- END AUTOMATED OUTPUT -->
 
 To display a short description of all available `pebble` commands, run:
 
-```bash
-pebble help --all
+```{terminal}
+:input: pebble help --all
+Pebble lets you control services and perform management actions on
+the system that is running them.
+
+Usage: pebble <command> [<options>...]
+
+...
 ```
 
 To get more details for a specific command, run:
 
-```bash
-pebble help <command>
+```{terminal}
+:input: pebble help <command>
 ```
diff --git a/docs/reference/cli-commands/identities.md b/docs/reference/cli-commands/identities.md
new file mode 100644
index 00000000..3144d319
--- /dev/null
+++ b/docs/reference/cli-commands/identities.md
@@ -0,0 +1,27 @@
+(reference_pebble_identities_command)=
+# identities command
+
+The `identities` command is used to list identities.
+
+## Usage
+
+<!-- START AUTOMATED OUTPUT -->
+```{terminal}
+:input: pebble identities --help
+Usage:
+  pebble identities [identities-OPTIONS]
+
+The identities command lists all identities.
+
+Other identity-related subcommands are as follows (use --help with any
+subcommand for details):
+
+pebble identity           Show a single identity
+pebble add-identities     Add new identities
+pebble update-identities  Update or replace identities
+pebble remove-identities  Remove identities
+
+[identities command options]
+      --format=   Output format: "text" (default), "json", or "yaml".
+```
+<!-- END AUTOMATED OUTPUT -->
diff --git a/docs/reference/cli-commands/identity.md b/docs/reference/cli-commands/identity.md
new file mode 100644
index 00000000..d5e25dd3
--- /dev/null
+++ b/docs/reference/cli-commands/identity.md
@@ -0,0 +1,16 @@
+(reference_pebble_identity_command)=
+# identity command
+
+The `identity` command is used to show a single identity.
+
+## Usage
+
+<!-- START AUTOMATED OUTPUT -->
+```{terminal}
+:input: pebble identity --help
+Usage:
+  pebble identity <name>
+
+The identity command shows details for a single identity in YAML format.
+```
+<!-- END AUTOMATED OUTPUT -->
diff --git a/docs/reference/cli-commands/logs.md b/docs/reference/cli-commands/logs.md
index 1095ba62..b7dde814 100644
--- a/docs/reference/cli-commands/logs.md
+++ b/docs/reference/cli-commands/logs.md
@@ -1,4 +1,5 @@
-# Logs command
+(reference_pebble_logs_command)=
+# logs command
 
 The Pebble daemon's service manager stores the most recent stdout and stderr from each service, using a 100KB ring buffer per service. Each log line is prefixed with an RFC-3339 timestamp and the `[service-name]` in square brackets.
 
@@ -6,8 +7,9 @@ The Pebble daemon's service manager stores the most recent stdout and stderr fro
 
 Logs are viewable via the logs API or using `pebble logs`:
 
+<!-- START AUTOMATED OUTPUT -->
 ```{terminal}
-   :input: pebble logs --help
+:input: pebble logs --help
 Usage:
   pebble logs [logs-OPTIONS] [<service>...]
 
@@ -22,6 +24,7 @@ if none are specified) and displays them in chronological order.
       -n=              Number of logs to show (before following); defaults to 30.
                        If 'all', show all buffered logs.
 ```
+<!-- END AUTOMATED OUTPUT -->
 
 ## Examples
 
diff --git a/docs/reference/cli-commands/ls.md b/docs/reference/cli-commands/ls.md
new file mode 100644
index 00000000..c979f0c0
--- /dev/null
+++ b/docs/reference/cli-commands/ls.md
@@ -0,0 +1,22 @@
+(reference_pebble_ls_command)=
+# ls command
+
+The `ls` command is used to list path contents.
+
+## Usage
+
+<!-- START AUTOMATED OUTPUT -->
+```{terminal}
+:input: pebble ls --help
+Usage:
+  pebble ls [ls-OPTIONS] <path>
+
+The ls command lists entries in the filesystem at the specified path. A glob pattern
+may be specified for the last path element.
+
+[ls command options]
+          --abs-time  Display absolute times (in RFC 3339 format). Otherwise, display relative times up to 60 days, then YYYY-MM-DD.
+      -d              List matching entries themselves, not directory contents
+      -l              Use a long listing format
+```
+<!-- END AUTOMATED OUTPUT -->
diff --git a/docs/reference/cli-commands/mkdir.md b/docs/reference/cli-commands/mkdir.md
new file mode 100644
index 00000000..00c40f9c
--- /dev/null
+++ b/docs/reference/cli-commands/mkdir.md
@@ -0,0 +1,24 @@
+(reference_pebble_mkdir_command)=
+# mkdir command
+
+The `mkdir` command is used to create a directory.
+
+## Usage
+
+<!-- START AUTOMATED OUTPUT -->
+```{terminal}
+:input: pebble mkdir --help
+Usage:
+  pebble mkdir [mkdir-OPTIONS] <path>
+
+The mkdir command creates the specified directory.
+
+[mkdir command options]
+      -p            Create parent directories as needed, and don't fail if path already exists
+      -m=           Override mode bits (3-digit octal)
+          --uid=    Use specified user ID
+          --user=   Use specified username
+          --gid=    Use specified group ID
+          --group=  Use specified group name
+```
+<!-- END AUTOMATED OUTPUT -->
diff --git a/docs/reference/cli-commands/notice.md b/docs/reference/cli-commands/notice.md
new file mode 100644
index 00000000..191b374c
--- /dev/null
+++ b/docs/reference/cli-commands/notice.md
@@ -0,0 +1,20 @@
+(reference_pebble_notice_command)=
+# notice command
+
+The `notice` command is used to fetch a single notice.
+
+## Usage
+
+<!-- START AUTOMATED OUTPUT -->
+```{terminal}
+:input: pebble notice --help
+Usage:
+  pebble notice [notice-OPTIONS] <id-or-type> [<key>]
+
+The notice command fetches a single notice, either by ID (1-arg variant), or
+by unique type and key combination (2-arg variant).
+
+[notice command options]
+      --uid=            Look up notice from user with this UID (admin only; 2-arg variant only)
+```
+<!-- END AUTOMATED OUTPUT -->
diff --git a/docs/reference/cli-commands/notices.md b/docs/reference/cli-commands/notices.md
new file mode 100644
index 00000000..bec35011
--- /dev/null
+++ b/docs/reference/cli-commands/notices.md
@@ -0,0 +1,31 @@
+(reference_pebble_notices_command)=
+# notices command
+
+The `notices` command is used to list notices.
+
+## Usage
+
+<!-- START AUTOMATED OUTPUT -->
+```{terminal}
+:input: pebble notices --help
+Usage:
+  pebble notices [notices-OPTIONS]
+
+The notices command lists notices not yet acknowledged, ordered by the
+last-repeated time (oldest first). After it runs, the notices that were shown
+may then be acknowledged by running 'pebble okay'. When a notice repeats, it
+needs to be acknowledged again.
+
+By default, list notices with the current user ID or public notices. Admins
+can use --users=all to view notice with any user ID, or --uid=UID to view
+another user's notices.
+
+[notices command options]
+      --abs-time    Display absolute times (in RFC 3339 format). Otherwise, display relative times up to 60 days, then YYYY-MM-DD.
+      --users=      The only valid value is 'all', which lists notices with any user ID (admin only; cannot be used with --uid)
+      --uid=        Only list notices with this user ID (admin only; cannot be used with --users)
+      --type=       Only list notices of this type (multiple allowed)
+      --key=        Only list notices with this key (multiple allowed)
+      --timeout=    Wait up to this duration for matching notices to arrive
+```
+<!-- END AUTOMATED OUTPUT -->
diff --git a/docs/reference/cli-commands/notify.md b/docs/reference/cli-commands/notify.md
new file mode 100644
index 00000000..2f85a5db
--- /dev/null
+++ b/docs/reference/cli-commands/notify.md
@@ -0,0 +1,20 @@
+(reference_pebble_notify_command)=
+# notify command
+
+The `notify` command is used to record a custom notice.
+
+## Usage
+
+<!-- START AUTOMATED OUTPUT -->
+```{terminal}
+:input: pebble notify --help
+Usage:
+  pebble notify [notify-OPTIONS] <key> [<name=value>...]
+
+The notify command records a custom notice with the specified key and optional
+data fields.
+
+[notify command options]
+      --repeat-after=   Prevent notice with same type and key from reoccurring within this duration
+```
+<!-- END AUTOMATED OUTPUT -->
diff --git a/docs/reference/cli-commands/okay.md b/docs/reference/cli-commands/okay.md
new file mode 100644
index 00000000..cd0f0759
--- /dev/null
+++ b/docs/reference/cli-commands/okay.md
@@ -0,0 +1,22 @@
+(reference_pebble_okay_command)=
+# okay command
+
+The `okay` command is used to acknowledge notices and warnings.
+
+## Usage
+
+<!-- START AUTOMATED OUTPUT -->
+```{terminal}
+:input: pebble okay --help
+Usage:
+  pebble okay [okay-OPTIONS]
+
+The okay command acknowledges warnings and notices that have been previously
+listed using 'pebble warnings' or 'pebble notices', so that they are omitted
+from future runs of either command. When a notice or warning is repeated, it
+will again show up until the next 'pebble okay'.
+
+[okay command options]
+      --warnings    Only acknowledge warnings, not other notices
+```
+<!-- END AUTOMATED OUTPUT -->
diff --git a/docs/reference/cli-commands/plan.md b/docs/reference/cli-commands/plan.md
new file mode 100644
index 00000000..99f7af20
--- /dev/null
+++ b/docs/reference/cli-commands/plan.md
@@ -0,0 +1,17 @@
+(reference_pebble_plan_command)=
+# plan command
+
+The `plan` command is used to show the plan with layers combined.
+
+## Usage
+
+<!-- START AUTOMATED OUTPUT -->
+```{terminal}
+:input: pebble plan --help
+Usage:
+  pebble plan
+
+The plan command prints out the effective configuration of Pebble in YAML
+format. Layers are combined according to the override rules defined in them.
+```
+<!-- END AUTOMATED OUTPUT -->
diff --git a/docs/reference/cli-commands/pull.md b/docs/reference/cli-commands/pull.md
new file mode 100644
index 00000000..afe07ff7
--- /dev/null
+++ b/docs/reference/cli-commands/pull.md
@@ -0,0 +1,16 @@
+(reference_pebble_pull_command)=
+# pull command
+
+The `pull` command is used to retrieve a file from the remote system.
+
+## Usage
+
+<!-- START AUTOMATED OUTPUT -->
+```{terminal}
+:input: pebble pull --help
+Usage:
+  pebble pull <remote-path> <local-path>
+
+The pull command retrieves a file from the remote system.
+```
+<!-- END AUTOMATED OUTPUT -->
diff --git a/docs/reference/cli-commands/push.md b/docs/reference/cli-commands/push.md
new file mode 100644
index 00000000..56d00fc2
--- /dev/null
+++ b/docs/reference/cli-commands/push.md
@@ -0,0 +1,24 @@
+(reference_pebble_push_command)=
+# push command
+
+The `push` command is used to transfer a file to the remote system.
+
+## Usage
+
+<!-- START AUTOMATED OUTPUT -->
+```{terminal}
+:input: pebble push --help
+Usage:
+  pebble push [push-OPTIONS] <local-path> <remote-path>
+
+The push command transfers a file to the remote system.
+
+[push command options]
+      -p                   Create parent directories for the file
+      -m=                  Override mode bits (3-digit octal)
+          --uid=           Use specified user ID
+          --user=          Use specified username
+          --gid=           Use specified group ID
+          --group=         Use specified group name
+```
+<!-- END AUTOMATED OUTPUT -->
diff --git a/docs/reference/cli-commands/remove-identities.md b/docs/reference/cli-commands/remove-identities.md
new file mode 100644
index 00000000..f17b18a0
--- /dev/null
+++ b/docs/reference/cli-commands/remove-identities.md
@@ -0,0 +1,26 @@
+(reference_pebble_remove-identities_command)=
+# remove-identities command
+
+The `remove-identities` command is used to remove identities.
+
+## Usage
+
+<!-- START AUTOMATED OUTPUT -->
+```{terminal}
+:input: pebble remove-identities --help
+Usage:
+  pebble remove-identities [remove-identities-OPTIONS]
+
+The remove-identities command removes one or more identities.
+
+The named identities must exist. The named identity entries must be null in
+the YAML input. For example, to remove "alice" and "bob", use this YAML:
+
+> identities:
+>     alice: null
+>     bob: null
+
+[remove-identities command options]
+      --from=   Path of YAML file to read identities from (required)
+```
+<!-- END AUTOMATED OUTPUT -->
diff --git a/docs/reference/cli-commands/replan.md b/docs/reference/cli-commands/replan.md
index e58b861b..7f4c178f 100644
--- a/docs/reference/cli-commands/replan.md
+++ b/docs/reference/cli-commands/replan.md
@@ -1,11 +1,13 @@
-# Pebble replan command
+(reference_pebble_replan_command)=
+# replan command
 
 The replan command starts, stops, or restarts services that have changed, so that running services exactly match the desired configuration in the current plan.
 
 ## Usage
 
+<!-- START AUTOMATED OUTPUT -->
 ```{terminal}
-   :input: pebble replan --help
+:input: pebble replan --help
 Usage:
   pebble replan [replan-OPTIONS]
 
@@ -16,6 +18,7 @@ current plan.
 [replan command options]
       --no-wait    Do not wait for the operation to finish but just print the change id.
 ```
+<!-- END AUTOMATED OUTPUT -->
 
 ## How it works
 
diff --git a/docs/reference/cli-commands/restart.md b/docs/reference/cli-commands/restart.md
new file mode 100644
index 00000000..bab31dd1
--- /dev/null
+++ b/docs/reference/cli-commands/restart.md
@@ -0,0 +1,19 @@
+(reference_pebble_restart_command)=
+# restart command
+
+The `restart` command is used to restart a service.
+
+## Usage
+
+<!-- START AUTOMATED OUTPUT -->
+```{terminal}
+:input: pebble restart --help
+Usage:
+  pebble restart [restart-OPTIONS] <service>...
+
+The restart command restarts the named service(s) in the correct order.
+
+[restart command options]
+      --no-wait      Do not wait for the operation to finish but just print the change id.
+```
+<!-- END AUTOMATED OUTPUT -->
diff --git a/docs/reference/cli-commands/rm.md b/docs/reference/cli-commands/rm.md
new file mode 100644
index 00000000..cc3ca8af
--- /dev/null
+++ b/docs/reference/cli-commands/rm.md
@@ -0,0 +1,19 @@
+(reference_pebble_rm_command)=
+# rm command
+
+The `rm` command is used to remove a file or directory.
+
+## Usage
+
+<!-- START AUTOMATED OUTPUT -->
+```{terminal}
+:input: pebble rm --help
+Usage:
+  pebble rm [rm-OPTIONS] <path>
+
+The rm command removes a file or directory.
+
+[rm command options]
+      -r            Remove all files and directories recursively in the specified path
+```
+<!-- END AUTOMATED OUTPUT -->
diff --git a/docs/reference/cli-commands/run.md b/docs/reference/cli-commands/run.md
index cc75f3c6..30fbd97f 100644
--- a/docs/reference/cli-commands/run.md
+++ b/docs/reference/cli-commands/run.md
@@ -1,11 +1,13 @@
-# Pebble run command
+(reference_pebble_run_command)=
+# run command
 
-The `run` command starts Pebble daemon and runs the configured environment.
+The `run` command is used to run the service manager environment.
 
 ## Usage
 
+<!-- START AUTOMATED OUTPUT -->
 ```{terminal}
-   :input: pebble run --help
+:input: pebble run --help
 Usage:
   pebble run [run-OPTIONS]
 
@@ -24,7 +26,9 @@ pebble run --args myservice --port 8080 \; --hold
           --http=        Start HTTP API listening on this address (e.g., ":4000")
       -v, --verbose      Log all output from services to stdout
           --args=        Provide additional arguments to a service
+          --identities=  Seed identities from file (like update-identities --replace)
 ```
+<!-- END AUTOMATED OUTPUT -->
 
 ## How it works
 
@@ -83,4 +87,4 @@ pebble run
 
 To initialise the `$PEBBLE` directory with the contents of another, in a one-time copy, set the `PEBBLE_COPY_ONCE` environment variable to the source directory.
 
-This will only copy the contents if the target directory, `$PEBBLE`, is empty.
+This will only copy the contents if the target directory, `$PEBBLE`, is empty.
\ No newline at end of file
diff --git a/docs/reference/cli-commands/services.md b/docs/reference/cli-commands/services.md
index 7c0897ec..35937813 100644
--- a/docs/reference/cli-commands/services.md
+++ b/docs/reference/cli-commands/services.md
@@ -1,12 +1,13 @@
-# Pebble services command
+(reference_pebble_services_command)=
+# services command
 
 The services command lists status information about the services specified, or about all services if none are specified.
 
 ## Usage
 
+<!-- START AUTOMATED OUTPUT -->
 ```{terminal}
-   :input: pebble services --help
-Usage:
+:input: pebble services --help
 Usage:
   pebble services [services-OPTIONS] [<service>...]
 
@@ -16,6 +17,7 @@ about all services if none are specified.
 [services command options]
       --abs-time     Display absolute times (in RFC 3339 format). Otherwise, display relative times up to 60 days, then YYYY-MM-DD.
 ```
+<!-- END AUTOMATED OUTPUT -->
 
 ## Examples
 
diff --git a/docs/reference/cli-commands/signal.md b/docs/reference/cli-commands/signal.md
new file mode 100644
index 00000000..bf010480
--- /dev/null
+++ b/docs/reference/cli-commands/signal.md
@@ -0,0 +1,19 @@
+(reference_pebble_signal_command)=
+# signal command
+
+The `signal` command is used to send a signal to one or more running services.
+
+## Usage
+
+<!-- START AUTOMATED OUTPUT -->
+```{terminal}
+:input: pebble signal --help
+Usage:
+  pebble signal <SIGNAL> <service>...
+
+The signal command sends a signal to one or more running services. The signal
+name must be uppercase, for example:
+
+pebble signal HUP mysql nginx
+```
+<!-- END AUTOMATED OUTPUT -->
diff --git a/docs/reference/cli-commands/start.md b/docs/reference/cli-commands/start.md
index 022d589d..8371da57 100644
--- a/docs/reference/cli-commands/start.md
+++ b/docs/reference/cli-commands/start.md
@@ -1,20 +1,23 @@
-# Pebble start command
+(reference_pebble_start_command)=
+# start command
 
 The start command starts the service with the provided name and any other services it depends on, in the correct order.
 
 ## Usage
 
+<!-- START AUTOMATED OUTPUT -->
 ```{terminal}
-   :input: pebble start --help
+:input: pebble start --help
 Usage:
-  pebble services [services-OPTIONS] [<service>...]
+  pebble start [start-OPTIONS] <service>...
 
-The services command lists status information about the services specified, or
-about all services if none are specified.
+The start command starts the service with the provided name and
+any other services it depends on, in the correct order.
 
-[services command options]
-      --abs-time     Display absolute times (in RFC 3339 format). Otherwise, display relative times up to 60 days, then YYYY-MM-DD.
+[start command options]
+      --no-wait      Do not wait for the operation to finish but just print the change id.
 ```
+<!-- END AUTOMATED OUTPUT -->
 
 ## How it works
 
diff --git a/docs/reference/cli-commands/stop.md b/docs/reference/cli-commands/stop.md
index f665d35f..9a2865e5 100644
--- a/docs/reference/cli-commands/stop.md
+++ b/docs/reference/cli-commands/stop.md
@@ -1,11 +1,13 @@
-# Pebble stop command
+(reference_pebble_stop_command)=
+# stop command
 
 The stop command stops the service with the provided name and any other service that depends on it, in the correct order.
 
 ## Usage
 
+<!-- START AUTOMATED OUTPUT -->
 ```{terminal}
-   :input: pebble stop --help
+:input: pebble stop --help
 Usage:
   pebble stop [stop-OPTIONS] <service>...
 
@@ -15,6 +17,7 @@ any other service that depends on it, in the correct order.
 [stop command options]
       --no-wait      Do not wait for the operation to finish but just print the change id.
 ```
+<!-- END AUTOMATED OUTPUT -->
 
 ## How it works
 
diff --git a/docs/reference/cli-commands/tasks.md b/docs/reference/cli-commands/tasks.md
new file mode 100644
index 00000000..6f51c73b
--- /dev/null
+++ b/docs/reference/cli-commands/tasks.md
@@ -0,0 +1,26 @@
+(reference_pebble_tasks_command)=
+# tasks command
+
+The `tasks` command is used to list a change's tasks.
+
+## Usage
+
+<!-- START AUTOMATED OUTPUT -->
+```{terminal}
+:input: pebble tasks --help
+Usage:
+  pebble tasks [tasks-OPTIONS] [<change-id>]
+
+The tasks command displays a summary of tasks associated with an individual
+change that happened recently.
+
+[tasks command options]
+      --abs-time       Display absolute times (in RFC 3339 format). Otherwise, display relative times up to 60 days, then YYYY-MM-DD.
+      --last=          Select last change of given type (install, refresh, remove, try, auto-refresh, etc.). A question mark at the end of the type means
+                       to do nothing (instead of returning an error) if no change of the given type is found. Note the question mark could need protecting
+                       from the shell.
+
+[tasks command arguments]
+  <change-id>:         Change ID
+```
+<!-- END AUTOMATED OUTPUT -->
diff --git a/docs/reference/cli-commands/update-identities.md b/docs/reference/cli-commands/update-identities.md
new file mode 100644
index 00000000..bef8ab89
--- /dev/null
+++ b/docs/reference/cli-commands/update-identities.md
@@ -0,0 +1,35 @@
+(reference_pebble_update-identities_command)=
+# update-identities command
+
+The `update-identities` command is used to update or replace identities.
+
+## Usage
+
+<!-- START AUTOMATED OUTPUT -->
+```{terminal}
+:input: pebble update-identities --help
+Usage:
+  pebble update-identities [update-identities-OPTIONS]
+
+The update-identities command updates or replaces one or more identities.
+
+By default, the named identities must already exist and are updated.
+
+If --replace is specified, update-identities operates differently: if a named
+identity exists, it will be updated. If it does not exist, it will be added.
+If a named identity is null in the YAML input, that identity will be removed.
+For example, to add or update "alice" and ensure "bob" is removed, use
+--replace with YAML like this:
+
+> identities:
+>     alice:
+>         access: admin
+>         local:
+>             user-id: 1000
+>     bob: null
+
+[update-identities command options]
+      --from=      Path of YAML file to read identities from (required)
+      --replace    Replace (add or update) identities; remove null identities
+```
+<!-- END AUTOMATED OUTPUT -->
diff --git a/docs/reference/cli-commands/version.md b/docs/reference/cli-commands/version.md
new file mode 100644
index 00000000..3baac3ec
--- /dev/null
+++ b/docs/reference/cli-commands/version.md
@@ -0,0 +1,19 @@
+(reference_pebble_version_command)=
+# version command
+
+The `version` command is used to show version details.
+
+## Usage
+
+<!-- START AUTOMATED OUTPUT -->
+```{terminal}
+:input: pebble version --help
+Usage:
+  pebble version [version-OPTIONS]
+
+The version command displays the versions of the running client and server.
+
+[version command options]
+      --client    Only display the client version
+```
+<!-- END AUTOMATED OUTPUT -->
diff --git a/docs/reference/cli-commands/warnings.md b/docs/reference/cli-commands/warnings.md
new file mode 100644
index 00000000..5a605d0b
--- /dev/null
+++ b/docs/reference/cli-commands/warnings.md
@@ -0,0 +1,28 @@
+(reference_pebble_warnings_command)=
+# warnings command
+
+The `warnings` command is used to list warnings.
+
+## Usage
+
+<!-- START AUTOMATED OUTPUT -->
+```{terminal}
+:input: pebble warnings --help
+Usage:
+  pebble warnings [warnings-OPTIONS]
+
+The warnings command lists the warnings that have been reported to the system.
+
+Once warnings have been listed with 'pebble warnings', 'pebble okay' may be used to
+silence them. A warning that's been silenced in this way will not be listed
+again unless it happens again, _and_ a cooldown time has passed.
+
+Warnings expire automatically, and once expired they are forgotten.
+
+[warnings command options]
+      --abs-time                      Display absolute times (in RFC 3339 format). Otherwise, display relative times up to 60 days, then YYYY-MM-DD.
+      --unicode=[auto|never|always]   Use a little bit of Unicode to improve legibility. (default: auto)
+      --all                           Show all warnings
+      --verbose                       Show more information
+```
+<!-- END AUTOMATED OUTPUT -->
diff --git a/docs/tox.ini b/docs/tox.ini
index dd0ca209..d1dca9f6 100644
--- a/docs/tox.ini
+++ b/docs/tox.ini
@@ -32,3 +32,7 @@ commands_pre =
 commands =
     sphinx-autobuild . _build/html
 
+[testenv:commands]
+description = Generate reference docs for CLI commands
+commands =
+    python3 generate_command_docs.py