From ce3f8b90efcc8dbfa3428ef570d4f1e05a6cfba9 Mon Sep 17 00:00:00 2001
From: "aspire-repo-bot[bot]"
 <268009190+aspire-repo-bot[bot]@users.noreply.github.com>
Date: Fri, 29 May 2026 19:25:56 +0000
Subject: [PATCH 1/2] docs: add troubleshooting note for localhive.sh CLI copy
 failure on macOS/Linux

Documents the 'Failed to copy CLI files' error that occurs when using
localhive.sh with a publish output containing culture-specific
subdirectories (e.g., fr/, de/). The fix is to use cp -Rf with the
/.  suffix instead of a glob.

Relates to microsoft/aspire#17670

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../content/docs/get-started/troubleshooting.mdx | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/src/frontend/src/content/docs/get-started/troubleshooting.mdx b/src/frontend/src/content/docs/get-started/troubleshooting.mdx
index c0a9399ef..9d7408c38 100644
--- a/src/frontend/src/content/docs/get-started/troubleshooting.mdx
+++ b/src/frontend/src/content/docs/get-started/troubleshooting.mdx
@@ -203,6 +203,22 @@ Aspire CLI logs are stored at:
   <Code slot="windows" lang="powershell" code="$HOME\.aspire\cli\logs\" />
 </OsAwareTabs>
 
+## Building from source
+
+### "Failed to copy CLI files" error on macOS or Linux
+
+**Symptoms**: When running `localhive.sh` to install a locally built Aspire CLI, the script exits with:
+
+```
+Failed to copy CLI files from <publish_dir> to <bin_dir>
+```
+
+On macOS/BSD, this appears as `cp: .../fr is a directory (not copied)`. On Linux/GNU, it appears as `cp: -r not specified; omitting directory '...'`.
+
+**Cause**: The `dotnet publish` output for the CLI includes culture-specific resource subdirectories (for example, `fr/`, `de/`). The plain `cp` invocation without `-R` cannot copy directories.
+
+**Solution**: Update to the latest version of `localhive.sh` from the [microsoft/aspire](https://github.com/microsoft/aspire) repository. The script was updated to use `cp -Rf "$CLI_PUBLISH_DIR"/. "$CLI_BIN_DIR"/` which correctly copies both files and subdirectories.
+
 ## See also
 
 - [Create your first Aspire app](/get-started/first-app/)

From 1b1fcfc1cd4466478c33da3b69f8350a894a58e0 Mon Sep 17 00:00:00 2001
From: David Pine <7679720+IEvangelist@users.noreply.github.com>
Date: Sat, 30 May 2026 02:39:17 -0500
Subject: [PATCH 2/2] Address review feedback (1 thread)

- Clarified the localhive.sh release-branch copy fix and path placeholders (PRRT_kwDOQK_VN86FyY8J)

Verified against microsoft/aspire@11bea2eb9fbb655614bcf9814c55c88a3fdd1126 on branch release/13.4.
Edited per the doc-writer skill.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../docs/get-started/troubleshooting.mdx      | 27 ++++++++++++++++---
 1 file changed, 24 insertions(+), 3 deletions(-)

diff --git a/src/frontend/src/content/docs/get-started/troubleshooting.mdx b/src/frontend/src/content/docs/get-started/troubleshooting.mdx
index 9d7408c38..61a4be60b 100644
--- a/src/frontend/src/content/docs/get-started/troubleshooting.mdx
+++ b/src/frontend/src/content/docs/get-started/troubleshooting.mdx
@@ -207,17 +207,38 @@ Aspire CLI logs are stored at:
 
 ### "Failed to copy CLI files" error on macOS or Linux
 
-**Symptoms**: When running `localhive.sh` to install a locally built Aspire CLI, the script exits with:
+This section applies to contributors building Aspire from source with the
+`localhive.sh` script in the
+[microsoft/aspire](https://github.com/microsoft/aspire) repository. The script
+installs a locally built Aspire CLI into a local hive.
 
-```
+**Symptoms**: When running `localhive.sh`, the script exits with:
+
+```text title="Error output"
 Failed to copy CLI files from <publish_dir> to <bin_dir>
 ```
 
+Here, `<publish_dir>` is the CLI `dotnet publish` output directory, and
+`<bin_dir>` is the CLI installation directory. By default, `<bin_dir>` is
+`$HOME/.aspire/bin`; if you pass `-o` or `--output`, it is the `bin` directory
+under that output path.
+
 On macOS/BSD, this appears as `cp: .../fr is a directory (not copied)`. On Linux/GNU, it appears as `cp: -r not specified; omitting directory '...'`.
 
 **Cause**: The `dotnet publish` output for the CLI includes culture-specific resource subdirectories (for example, `fr/`, `de/`). The plain `cp` invocation without `-R` cannot copy directories.
 
-**Solution**: Update to the latest version of `localhive.sh` from the [microsoft/aspire](https://github.com/microsoft/aspire) repository. The script was updated to use `cp -Rf "$CLI_PUBLISH_DIR"/. "$CLI_BIN_DIR"/` which correctly copies both files and subdirectories.
+**Solution**: If you're working from the `release/13.4` branch, apply the
+one-line copy command fix in `localhive.sh`:
+
+```diff title="localhive.sh"
+-    if ! cp -f "$CLI_PUBLISH_DIR"/* "$CLI_BIN_DIR"/; then
++    if ! cp -Rf "$CLI_PUBLISH_DIR"/. "$CLI_BIN_DIR"/; then
+```
+
+Alternatively, update `localhive.sh` from the
+[`main` branch of microsoft/aspire](https://github.com/microsoft/aspire/blob/main/localhive.sh)
+or cherry-pick [microsoft/aspire#17670](https://github.com/microsoft/aspire/pull/17670)
+if you are pinned to a release branch.
 
 ## See also