ci: auto-sync CLI docs to docs repo on release

Author: jason-rl

.github/workflows/release.yml

@@ -50,3 +50,79 @@ jobs:
 
       - name: Publish to npm
         run: pnpm publish --no-git-checks
+
+  sync-docs:
+    needs: release
+    if: ${{ needs.release.outputs.release_created == 'true' }}
+    runs-on: ubuntu-slim
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout rl-cli
+        uses: actions/checkout@v6
+        with:
+          path: rl-cli
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v5
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          cache: "pnpm"
+          cache-dependency-path: rl-cli/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+        working-directory: rl-cli
+
+      - name: Build
+        run: pnpm run build
+        working-directory: rl-cli
+
+      - name: Generate CLI docs
+        run: node scripts/generate-command-docs.js --skip-readme --docs-path "$GITHUB_WORKSPACE/rl-cli.mdx"
+        working-directory: rl-cli
+
+      - name: Create GitHub App token
+        id: app-token
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: ${{ vars.DEPLOY_APP_CLIENT_ID }}
+          private-key: ${{ secrets.DEPLOY_APP_PRIVATE_KEY }}
+          repositories: docs
+          permission-contents: write
+          permission-pull-requests: write
+
+      - name: Get GitHub App User ID
+        id: get-user-id
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: echo "user-id=$(gh api "/users/${{ steps.app-token.outputs.app-slug }}[bot]" --jq .id)" >> "$GITHUB_OUTPUT"
+
+      - name: Checkout docs repo
+        uses: actions/checkout@v6
+        with:
+          repository: runloopai/docs
+          token: ${{ steps.app-token.outputs.token }}
+          path: docs
+
+      - name: Copy generated docs
+        run: cp "$GITHUB_WORKSPACE/rl-cli.mdx" docs/docs/tools/rl-cli.mdx
+
+      - name: Create Pull Request
+        uses: runloopai/create-pull-request@main
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          path: docs
+          commit-message: "docs: update rl-cli command reference for ${{ needs.release.outputs.tag_name }}"
+          committer: "${{ steps.app-token.outputs.app-slug }}[bot] <${{ steps.get-user-id.outputs.user-id }}+${{ steps.app-token.outputs.app-slug }}[bot]@users.noreply.github.com>"
+          author: "${{ steps.app-token.outputs.app-slug }}[bot] <${{ steps.get-user-id.outputs.user-id }}+${{ steps.app-token.outputs.app-slug }}[bot]@users.noreply.github.com>"
+          title: "docs: update rl-cli command reference for ${{ needs.release.outputs.tag_name }}"
+          body: |
+            Auto-generated from [rl-cli ${{ needs.release.outputs.tag_name }}](https://github.com/runloopai/rl-cli/releases/tag/${{ needs.release.outputs.tag_name }}).
+
+            Updates the CLI command reference documentation to match the latest release.
+          branch: rl-cli-docs/${{ needs.release.outputs.tag_name }}
+          delete-branch: true

scripts/generate-command-docs.js

@@ -510,8 +510,8 @@ The Runloop CLI is open-source. We welcome contributions!
 /**
  * Updates the external docs rl-cli.mdx file
  */
-function updateDocsMdx(program, docsPath) {
-  if (!existsSync(docsPath)) {
+function updateDocsMdx(program, docsPath, explicitPath) {
+  if (!explicitPath && !existsSync(docsPath)) {
     console.log(`⚠️  Docs file not found at ${docsPath}, skipping docs update`);
     console.log("   Set DOCS_PATH env var or use --docs-path to specify location");
     return false;
@@ -530,13 +530,15 @@ function parseArgs() {
   const args = process.argv.slice(2);
   const options = {
     docsPath: process.env.DOCS_PATH || defaultDocsPath,
+    explicitDocsPath: !!process.env.DOCS_PATH,
     skipReadme: false,
     skipDocs: false,
   };
 
   for (let i = 0; i < args.length; i++) {
     if (args[i] === "--docs-path" && args[i + 1]) {
       options.docsPath = args[i + 1];
+      options.explicitDocsPath = true;
       i++;
     } else if (args[i] === "--skip-readme") {
       options.skipReadme = true;
@@ -573,7 +575,7 @@ async function main() {
     }
 
     if (!options.skipDocs) {
-      updateDocsMdx(program, options.docsPath);
+      updateDocsMdx(program, options.docsPath, options.explicitDocsPath);
     }
   } catch (error) {
     console.error("Error generating command docs:", error);