chore(docs): cli reference generation (#1751)

Signed-off-by: Tomas Pilar <thomas7pilar@gmail.com>

Author: pilartomas

apps/agentstack-cli/tasks.toml

@@ -83,7 +83,11 @@ sources = ["{{config_root}}/helm/dist/agentstack-*.tgz"]
 outputs = ["./src/agentstack_cli/data/helm-chart.tgz"]
 
 ["agentstack-cli:build"]
-depends = ["agentstack-cli:setup", "agentstack-cli:build:*", "agentstack-sdk-py:build"]
+depends = [
+  "agentstack-cli:setup",
+  "agentstack-cli:build:*",
+  "agentstack-sdk-py:build",
+]
 dir = "{{config_root}}/apps/agentstack-cli"
 sources = ["src/**/*", "hatch_build.py", "pyproject.toml", "vendor/lima/**/*"]
 outputs = ["dist/**/*"]
@@ -159,3 +163,24 @@ for job in $(jobs -p); do wait $job; done
 ["agentstack-cli:clean"]
 dir = "{{config_root}}/apps/agentstack-cli"
 run = "rm -rf ./dist"
+
+# docs
+
+["agentstack-cli:docs"]
+dir = "{{config_root}}/apps/agentstack-cli"
+depends = ["agentstack-cli:setup"]
+run = '''
+#!/bin/bash
+set -euo pipefail
+
+CLI_REFERENCE="../../docs/development/reference/cli-reference.mdx"
+TYPER_SCRIPT="src/agentstack_cli/__init__.py"
+
+HEAD_TMP=$(mktemp)
+GEN_TMP=$(mktemp)
+trap 'rm -f $HEAD_TMP $GEN_TMP' EXIT
+
+cat $CLI_REFERENCE | sed "/usage-generator/q" > $HEAD_TMP
+uv run typer $TYPER_SCRIPT utils docs --name agentstack | tail -n +2 > $GEN_TMP
+cat $HEAD_TMP $GEN_TMP > $CLI_REFERENCE
+'''