From d98b2fc4ff3a776714b5e3606ed559ebf9933966 Mon Sep 17 00:00:00 2001 From: Kris Zyp Date: Wed, 4 Nov 2026 21:34:03 -0700 Subject: [PATCH 1/4] Restore the project .env CLI flow on the Fabric and Learn pages harper#4039 reverts the CLI refusal of a project .env target or credential, so undo what documentation#796 changed on the two pages that stayed in this repo: the safe-deployments guide again pins the target in .env and copies it into the staged deploy directory, and the Fabric page again says harper login appends HARPER_CLI_TARGET to an existing .env. Two corrections beyond the revert: the append also skips when the environment sets a target, and the credential warning names the primary HARPER_CLI_USERNAME/HARPER_CLI_PASSWORD variables. Dispatch-Task: docs-harper-revert-4001 Co-Authored-By: Claude Opus 5.5 --- fabric/cluster-creation-management.md | 2 +- .../safe-deployments-and-rollback.mdx | 25 ++++++++++++------- 2 files changed, 17 insertions(+), 10 deletions(-) diff --git a/fabric/cluster-creation-management.md b/fabric/cluster-creation-management.md index ed0199434..51f3e054f 100644 --- a/fabric/cluster-creation-management.md +++ b/fabric/cluster-creation-management.md @@ -81,7 +81,7 @@ Clusters are provisioned in real time, as soon as selections are complete ## Connecting the Harper CLI to a Cluster -The cluster's **Config → Overview** page exposes its **Application URL** — the hostname the Harper CLI and SDKs target. Pass it to `harper login` to authenticate; the CLI stores the token so subsequent commands don't need credentials repeated. It also saves the URL as the CLI's default target. From v5.4.0, the CLI stops with an error if a `.env` file in the current directory sets a name it refuses, such as `HARPER_CLI_TARGET`, and your environment does not. Remove that line. See [Project `.env` files](/reference/v5/cli/authentication#project-env-files). +The cluster's **Config → Overview** page exposes its **Application URL** — the hostname the Harper CLI and SDKs target. Pass it to `harper login` to authenticate; the CLI stores the token so subsequent commands don't need credentials repeated. It also saves the URL as the CLI's default target. If the current directory already has a `.env` file, and neither that file nor your environment sets a target, login appends `HARPER_CLI_TARGET` to it. ```bash harper login diff --git a/learn/administration/safe-deployments-and-rollback.mdx b/learn/administration/safe-deployments-and-rollback.mdx index a8b026dfe..e502a2506 100644 --- a/learn/administration/safe-deployments-and-rollback.mdx +++ b/learn/administration/safe-deployments-and-rollback.mdx @@ -28,20 +28,26 @@ This guide deploys a Harper application to a cluster, waits until every node run ### Log in -Set the cluster's Operations API URL in your shell, then log in: +Set the cluster's Operations API URL in your project's `.env`: ```bash -export HARPER_CLI_TARGET='https://my-cluster.example.com:9925' -harper login "$HARPER_CLI_TARGET" +# .env +HARPER_CLI_TARGET='https://my-cluster.example.com:9925' ``` -Enter the cluster's admin username and password. The CLI saves a token in `~/.harperdb/credentials.json`. +`npm create harper@latest` asks for your cluster URL and writes it here, adding `https://` if you omit the scheme and port `9925` if you omit the port. If you skipped the prompt, replace the placeholder. From the project directory, log in: -Commands such as `harper deploy`, `harper list_deployments`, and `harper get_job` then need no `target=`. The export keeps this shell's commands from falling back to the last cluster you logged in to from any project, so set it again in each new shell. CI sets the same variable from a repository variable. See [how the CLI picks a target](/reference/v5/cli/authentication#how-the-cli-picks-a-target). +```bash +harper login +``` - +Press Enter to accept the `.env` value at the **Cluster Target URL** prompt, then enter the cluster's admin username and password. The CLI saves a token in `~/.harperdb/credentials.json`, not in `.env`. + + + +The CLI loads `.env` from the directory you run it in. Commands such as `harper deploy`, `harper list_deployments`, and `harper get_job` then need no `target=`. Pinning the target here keeps this project's commands from falling back to the last cluster you logged in to. An existing environment variable wins over `.env`, so CI can still set `HARPER_CLI_TARGET` from a repository variable. See [authentication](/reference/v5/cli/authentication) for the full precedence rules. -Remove any `HARPER_CLI_TARGET` line from your project's `.env`. `npm create harper@latest` writes one there. From v5.4.0, the CLI stops with an error while the file sets it and your environment does not. To share the target with your team, pass `target=` in a `package.json` script. See [Project `.env` files](/reference/v5/cli/authentication#project-env-files). +The target URL is not a secret. To share it with your team, remove `.env` from the template's `.gitignore` and commit the file, or force-add it. Templates ignore `.env` and `.env.*`, except `.env.example`. Keep credentials such as `HARPER_CLI_USERNAME` and `HARPER_CLI_PASSWORD` out of it: the deploy upload includes `.env`, so its contents reach every node. ### A Harper backend @@ -78,10 +84,11 @@ npm run build rm -rf deploy && mkdir deploy cp -R dist schemas resources deploy/ cp deploy.config.yaml deploy/config.yaml +cp .env deploy/.env (cd deploy && harper deploy project=my-app restart=true) ``` -The subshell inherits `HARPER_CLI_TARGET`, so the CLI needs no `.env` in the staged directory. If your release configuration keeps `loadEnv`, copy only the application's keys to `deploy/`, under a file name its `files` lists. The staged directory has no `package.json`, so the nodes skip the install step. If your resources import npm packages, add a `package.json` to `deploy/` that lists only those runtime dependencies. Harper Studio [deploys itself this way](https://github.com/HarperFast/studio/blob/stage/.github/actions/studio-deploy/action.yaml). +The CLI reads `.env` from the directory it runs in, so the staged directory needs this copy to find the target. It holds only the target URL, so shipping it is harmless. The staged directory has no `package.json`, so the nodes skip the install step. If your resources import npm packages, add a `package.json` to `deploy/` that lists only those runtime dependencies. Harper Studio [deploys itself this way](https://github.com/HarperFast/studio/blob/stage/.github/actions/studio-deploy/action.yaml). ### Deploy from GitHub Actions @@ -201,7 +208,7 @@ harper deploy project=my-app restart=rolling target=https://node-1.example.com:9 ) ``` -Jobs are not replicated, so the script deploys to and polls one node rather than the load-balanced cluster URL in `HARPER_CLI_TARGET`, where a poll can reach a node that never saw the job. See [the job lives on one node](../developers/deploying-from-ci.mdx#path-a-deploy-a-tagged-release-from-your-repository). Without certification, including before v5.4.0, a `COMPLETE` job can still leave a node it could not reach on the old release. Check the serving version on every node afterwards. +Jobs are not replicated, so the script deploys to and polls one node rather than the load-balanced cluster URL in `.env`, where a poll can reach a node that never saw the job. See [the job lives on one node](../developers/deploying-from-ci.mdx#path-a-deploy-a-tagged-release-from-your-repository). Without certification, including before v5.4.0, a `COMPLETE` job can still leave a node it could not reach on the old release. Check the serving version on every node afterwards. Two deploy parameters control replication failures: From d76a466c4e5aeb577992453c52ebfe8d2f24998a Mon Sep 17 00:00:00 2001 From: Kris Zyp Date: Wed, 4 Nov 2026 21:39:47 -0700 Subject: [PATCH 2/4] State when shipping the staged .env is harmless Dispatch-Task: docs-harper-revert-4001 Co-Authored-By: Claude Opus 5.5 --- learn/administration/safe-deployments-and-rollback.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/administration/safe-deployments-and-rollback.mdx b/learn/administration/safe-deployments-and-rollback.mdx index e502a2506..ac897a366 100644 --- a/learn/administration/safe-deployments-and-rollback.mdx +++ b/learn/administration/safe-deployments-and-rollback.mdx @@ -88,7 +88,7 @@ cp .env deploy/.env (cd deploy && harper deploy project=my-app restart=true) ``` -The CLI reads `.env` from the directory it runs in, so the staged directory needs this copy to find the target. It holds only the target URL, so shipping it is harmless. The staged directory has no `package.json`, so the nodes skip the install step. If your resources import npm packages, add a `package.json` to `deploy/` that lists only those runtime dependencies. Harper Studio [deploys itself this way](https://github.com/HarperFast/studio/blob/stage/.github/actions/studio-deploy/action.yaml). +The CLI reads `.env` from the directory it runs in, so the staged directory needs this copy to find the target. The copy ships to every node, which is harmless while the file holds only the target URL. The staged directory has no `package.json`, so the nodes skip the install step. If your resources import npm packages, add a `package.json` to `deploy/` that lists only those runtime dependencies. Harper Studio [deploys itself this way](https://github.com/HarperFast/studio/blob/stage/.github/actions/studio-deploy/action.yaml). ### Deploy from GitHub Actions From ce53bc61484de4832d65a478f54b1b64631226b8 Mon Sep 17 00:00:00 2001 From: Kris Zyp Date: Wed, 4 Nov 2026 21:43:24 -0700 Subject: [PATCH 3/4] Name both target variables in the Fabric login append condition Dispatch-Task: docs-harper-revert-4001 Co-Authored-By: Claude Opus 5.5 --- fabric/cluster-creation-management.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fabric/cluster-creation-management.md b/fabric/cluster-creation-management.md index 51f3e054f..3aaeafe1c 100644 --- a/fabric/cluster-creation-management.md +++ b/fabric/cluster-creation-management.md @@ -81,7 +81,7 @@ Clusters are provisioned in real time, as soon as selections are complete ## Connecting the Harper CLI to a Cluster -The cluster's **Config → Overview** page exposes its **Application URL** — the hostname the Harper CLI and SDKs target. Pass it to `harper login` to authenticate; the CLI stores the token so subsequent commands don't need credentials repeated. It also saves the URL as the CLI's default target. If the current directory already has a `.env` file, and neither that file nor your environment sets a target, login appends `HARPER_CLI_TARGET` to it. +The cluster's **Config → Overview** page exposes its **Application URL** — the hostname the Harper CLI and SDKs target. Pass it to `harper login` to authenticate; the CLI stores the token so subsequent commands don't need credentials repeated. It also saves the URL as the CLI's default target. If the current directory already has a `.env` file, and neither that file nor your environment sets `HARPER_CLI_TARGET` or `CLI_TARGET`, login appends `HARPER_CLI_TARGET` to it. ```bash harper login From fc3b8b605f4627879f80f23965c3e56938f85313 Mon Sep 17 00:00:00 2001 From: Kris Zyp Date: Wed, 4 Nov 2026 21:49:48 -0700 Subject: [PATCH 4/4] Give the .env credential warning its own sentence Dispatch-Task: docs-harper-revert-4001 Co-Authored-By: Claude Opus 5.5 --- learn/administration/safe-deployments-and-rollback.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/administration/safe-deployments-and-rollback.mdx b/learn/administration/safe-deployments-and-rollback.mdx index ac897a366..369f95817 100644 --- a/learn/administration/safe-deployments-and-rollback.mdx +++ b/learn/administration/safe-deployments-and-rollback.mdx @@ -47,7 +47,7 @@ Press Enter to accept the `.env` value at the **Cluster Target URL** prompt, the The CLI loads `.env` from the directory you run it in. Commands such as `harper deploy`, `harper list_deployments`, and `harper get_job` then need no `target=`. Pinning the target here keeps this project's commands from falling back to the last cluster you logged in to. An existing environment variable wins over `.env`, so CI can still set `HARPER_CLI_TARGET` from a repository variable. See [authentication](/reference/v5/cli/authentication) for the full precedence rules. -The target URL is not a secret. To share it with your team, remove `.env` from the template's `.gitignore` and commit the file, or force-add it. Templates ignore `.env` and `.env.*`, except `.env.example`. Keep credentials such as `HARPER_CLI_USERNAME` and `HARPER_CLI_PASSWORD` out of it: the deploy upload includes `.env`, so its contents reach every node. +The target URL is not a secret. To share it with your team, remove `.env` from the template's `.gitignore` and commit the file, or force-add it. Templates ignore `.env` and `.env.*`, except `.env.example`. Keep credentials such as `HARPER_CLI_USERNAME` and `HARPER_CLI_PASSWORD` out of it. The deploy upload includes `.env`, so its contents reach every node. ### A Harper backend