From 08690bf95b2308a420000b02ed7824750ee7d944 Mon Sep 17 00:00:00 2001 From: Kris Zyp Date: Tue, 3 Nov 2026 15:49:56 -0700 Subject: [PATCH 1/5] Document the CLI refusing a project .env target or credential harper#4001 makes the harper CLI stop with an error when a .env in the current directory sets its target, credentials or connection trust, and harper login no longer writes .env. Add the canonical key list and migration to the CLI authentication page, correct the pages that told readers to put the target in .env, and add the 5.4 upgrade note. The safe-deployments guide now exports HARPER_CLI_TARGET, since the saved target is per OS user. Dispatch-Task: docs-harper-4001 Co-Authored-By: Claude Opus 5.5 --- fabric/cluster-creation-management.md | 2 +- .../safe-deployments-and-rollback.mdx | 25 ++--- reference/backups/operations.md | 6 +- reference/cli/authentication.md | 98 +++++++++++++------ reference/cli/commands.md | 12 ++- reference/cli/overview.md | 6 +- reference/environment-variables/overview.md | 6 ++ release-notes/v5-lincoln/5.4.md | 14 +++ 8 files changed, 114 insertions(+), 55 deletions(-) diff --git a/fabric/cluster-creation-management.md b/fabric/cluster-creation-management.md index 55551b6e3..46fe47618 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. If the current directory already has a `.env` file that sets no target, it also 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. From v5.4.0, the CLI stops with an error if a `.env` file in the current directory sets `HARPER_CLI_TARGET`, so remove that line. See [Project `.env` files](/reference/v5/cli/authentication#project-env-files). ```bash harper login diff --git a/learn/administration/safe-deployments-and-rollback.mdx b/learn/administration/safe-deployments-and-rollback.mdx index 0f93bdd48..ac574c343 100644 --- a/learn/administration/safe-deployments-and-rollback.mdx +++ b/learn/administration/safe-deployments-and-rollback.mdx @@ -28,26 +28,20 @@ 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 project's `.env`: +Set the cluster's Operations API URL in your shell, then log in: ```bash -# .env -HARPER_CLI_TARGET='https://my-cluster.example.com:9925' +export HARPER_CLI_TARGET='https://my-cluster.example.com:9925' +harper login "$HARPER_CLI_TARGET" ``` -`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: +Enter the cluster's admin username and password. The CLI saves a token in `~/.harperdb/credentials.json`. -```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`. +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). - - -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 `CLI_TARGET_USERNAME` and `CLI_TARGET_PASSWORD` out of it: the deploy upload includes `.env`, so its contents reach every node. +Remove any `HARPER_CLI_TARGET` line from your project's `.env`. `npm create harper@latest` writes one there, and 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). ### A Harper backend @@ -84,11 +78,10 @@ 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 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 subshell inherits `HARPER_CLI_TARGET`, so the staged directory needs no `.env`. 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 @@ -208,7 +201,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 `.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. +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. Two deploy parameters control replication failures: diff --git a/reference/backups/operations.md b/reference/backups/operations.md index 9a56daf1a..bcdb9aef1 100644 --- a/reference/backups/operations.md +++ b/reference/backups/operations.md @@ -25,7 +25,11 @@ Every operation on this page can be run from the CLI under its operation name, f Like any [CLI operation](../cli/operations-api-commands.md), backup commands also accept a remote `target=` to run against another instance instead of the local one (see [Remote Operations](../cli/overview.md#remote-operations)). With a remote target the operation is always forwarded — there is no offline path. -A target set with `HARPER_CLI_TARGET` or `CLI_TARGET` is always forwarded too, including one that `harper login` added to a `.env` file. `harper logout` does not remove a `.env` entry, so delete that line to run commands offline. +A target set with `HARPER_CLI_TARGET` or `CLI_TARGET` in the environment is always forwarded too. Unset it to run commands offline. + + + +A `.env` file in the current directory cannot set the target. If it sets either variable, or another [name the CLI refuses](../cli/authentication.md#project-env-files), and the environment does not, a backup command stops with an error naming the keys. It stops before forwarding the operation or touching a file, whether or not Harper is running. Before v5.4.0 the file's target was forwarded, including one that `harper login` added. `harper logout` does not edit the file, so delete that line. A target saved by `harper login` is also forwarded, with one exception. If the saved target is a loopback address (`localhost`, `127.x` or `::1`) and the local server is stopped: diff --git a/reference/cli/authentication.md b/reference/cli/authentication.md index 0f4734251..1d61aa8ae 100644 --- a/reference/cli/authentication.md +++ b/reference/cli/authentication.md @@ -32,6 +32,17 @@ Available since: v4.1.0; expanded in: v4.3.0 For remote operations (operations executed on a remote Harper instance via the `target` parameter), you must provide authentication credentials. +### How the CLI Picks a Target + +The CLI connects to the first of these it finds: + +1. `target=` on the command +2. The `HARPER_CLI_TARGET` environment variable, then the legacy `CLI_TARGET` +3. The target saved in `~/.harperdb/credentials.json` +4. The local domain socket + +The saved target belongs to your OS user, not to a project: it is the target of your last `harper login`, or of the last saved token the CLI refreshed. A command with no target goes there from any directory, so to keep a project's commands on one cluster, pass `target=` or export `HARPER_CLI_TARGET`. `harper logout ` clears the saved target if it is that URL, and `harper logout` with no URL removes every saved login. + ### Authentication Precedence @@ -73,7 +84,7 @@ Before v5.2.0, `username=` and `password=` operation parameters took precedence Available since: v5.1.0 -Use `harper login` to store authentication tokens for a specific target. This is the most convenient method for local development as it removes the need to pass credentials with every command. +Use `harper login` to store authentication tokens for a specific target and make it the CLI's saved target. This is the most convenient method for local development as it removes the need to pass credentials with every command. ```bash # Log in once @@ -83,8 +94,15 @@ harper login https://server.com:9925 # Subsequently execute operations without credentials harper describe_database database=dev target=https://server.com:9925 harper deploy target=https://server.com:9925 + +# target= is optional while this is the saved target +harper describe_database database=dev ``` + + +`harper login` writes only to `~/.harperdb/credentials.json`, never to a project `.env`. It saves and prints the URL you gave it, in normalized form, never a target named in the server's reply. + When you are finished, you can log out to remove the stored token: ```bash @@ -97,13 +115,13 @@ harper logout https://server.com:9925 - Simplifies frequent remote operations - No need to maintain environment variables in multiple terminal sessions -A complete environment-variable credential pair takes precedence over a saved login token. Check the [authentication precedence](#authentication-precedence) when a project `.env` file and `harper login` are both configured for the same target. +A complete environment-variable credential pair takes precedence over a saved login token. Check the [authentication precedence](#authentication-precedence) when environment variables and `harper login` are both configured for the same target. #### Method 2: Environment Variables (Recommended for CI/CD) -The CLI supports loading environment variables from your shell environment (or optionally from a `.env` file in the current directory). This is the recommended method for CI/CD pipelines and for pre-populating the `target` parameter for specific projects. +The CLI reads these variables from your shell or CI environment. A `.env` file in the current directory cannot set them: see [Project `.env` files](#project-env-files). This is the recommended method for CI/CD pipelines and for pre-populating the `target` parameter for specific projects. Starting in v5.2.0, a complete environment-variable credential pair takes precedence over a saved login token and the legacy `username=` and `password=` fallback. This makes the configured CI identity authoritative even when the operation payload also contains username or password fields. @@ -123,19 +141,12 @@ The namespace is chosen by which one is **set**, not by which one has a usable v For a pipeline, a token is the right style: it is scoped to authentication, it can be revoked without changing the account password, and it cannot be used to log in interactively. Use it _instead of_ a password or payload credentials, not alongside them — see [Token credentials for CI/CD](#token-credentials-for-cicd). -**Example `.env` file**: - -```bash -HARPER_CLI_TARGET=https://example.com:9925 -HARPER_CLI_USERNAME=HDB_ADMIN -HARPER_CLI_PASSWORD=password -``` - **Manual Environment Variables**: Set these variables in your shell to avoid exposing credentials in command history: ```bash +export HARPER_CLI_TARGET=https://example.com:9925 export HARPER_CLI_USERNAME=HDB_ADMIN export HARPER_CLI_PASSWORD=password ``` @@ -144,25 +155,7 @@ export HARPER_CLI_PASSWORD=password - Credentials not visible in command history - More secure for scripting and CI/CD systems -- Can be set once per session or project directory - -**Automatic `.env` Updates**: - -When you run `harper login ` in a directory that already has a `.env` file, the CLI appends `HARPER_CLI_TARGET` with the URL you logged in to. It does not create a `.env` file, and it leaves the file alone if the file, or your environment, already sets `HARPER_CLI_TARGET` or `CLI_TARGET`. - -```bash -harper login https://my-project.harperdb.cloud -``` - -Then you can run commands without specifying the `target` or credentials (if they are also in `.env` or exported): - -```bash -# Respects HARPER_CLI_TARGET from .env -harper deploy -harper describe_database database=dev -harper get_components -harper logout -``` +- Can be set once per session **Example Script**: @@ -187,6 +180,46 @@ harper add_user \ target=https://prod-server.com:9925 ``` +##### Project `.env` files + + + +A `.env` or `.env.vault` file in the current directory cannot configure the CLI's target, credentials or connection trust. That directory is often a cloned project, and a file it ships must not decide where your credentials go ([harper#4001: Refuse a project .env CLI target or credential](https://github.com/HarperFast/harper/pull/4001)). + +Operations API commands, including `harper deploy`, as well as `harper login` and the backup commands, read the file first. If it sets one of these names and the shell or CI environment does not, the command stops with an error naming the keys. It stops before contacting a server or touching a file, for local operations too: + +| Purpose | Names, in any letter case | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Target | `HARPER_CLI_TARGET`, `CLI_TARGET` | +| Credentials | `HARPER_CLI_USERNAME`, `HARPER_CLI_PASSWORD`, `HARPER_CLI_OPERATION_TOKEN`, `HARPER_CLI_REFRESH_TOKEN`, and the same four names with the `CLI_TARGET_` prefix | +| Workload identity | `ACTIONS_ID_TOKEN_REQUEST_URL`, `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | +| GitHub deploy inputs | `GITHUB_REPOSITORY`, `GITHUB_SHA`, `GITHUB_REF`, `GITHUB_EVENT_PATH` | +| Saved login location | `HOME`, `USERPROFILE` | +| TLS | `NODE_TLS_REJECT_UNAUTHORIZED`, `NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE`, `SSL_CERT_DIR` | +| Proxy | `NODE_USE_ENV_PROXY`, `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` | + +```text +error: HARPER_CLI_TARGET must not come from a .env or .env.vault file in /path/to/project: a project's .env no longer sets the Harper CLI's target, credentials or connection settings ... +``` + +- **`target=` does not get past the error.** The line has to leave the file, or the name has to be set in the environment. +- **Shell and CI values win.** When the environment already sets a name, the CLI ignores the file's value and runs. On Linux and macOS the spelling has to match: exporting `HTTPS_PROXY` does not clear `https_proxy` in the file. +- **Other keys still load.** A file with none of these names is applied as before, and `.env.example` and `.env.local` are not read at all. +- **Applications are unaffected.** `.env` handling in `harper run`, `harper dev` and a component's [`loadEnv`](../environment-variables/overview.md) is unchanged. `harper status`, `harper version`, `harper logout`, `harper agent` and `harper mcp` do not read the file. + +To migrate a project, remove the `HARPER_CLI_*` and `CLI_TARGET*` lines from its `.env`. `npm create harper@latest` writes `HARPER_CLI_TARGET` there, and `harper login` before v5.4.0 could append it. Then choose where the target comes from: + +| Route | Scope | +| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `harper login ` | Your OS user. Later commands use the saved target from any directory, so this suits one cluster at a time. | +| `target=` | One command. To share a target with your team, put it in a `package.json` script: `"deploy": "harper deploy project=my-app target=https://my-cluster.example.com:9925"`. | +| `export HARPER_CLI_TARGET=` | One shell session, or a CI job through its variables and secrets. | +| `dotenv -- harper deploy`, from `dotenv-cli` | One script. This hands the CLI every value in the file, including the names above, so use it only on a file you trust. | + +CI that stores `harper login --for-ci` output as secrets is unaffected, because those values reach the job as environment variables. A job that relied on a committed `.env` for its target needs `HARPER_CLI_TARGET` in its environment instead. + +If your application reads one of these names at runtime, such as a proxy setting, the CLI still stops when it finds that name in `.env`. Set the name in the process environment, or keep it in a differently named file listed under [`loadEnv`'s `files`](../environment-variables/overview.md). + ##### Token credentials for CI/CD @@ -385,7 +418,7 @@ The target URL can also contain a complete username and password, which the CLI target=https://username:password@server.example.com:9925 ``` -Percent-encode reserved characters in either value (`@` becomes `%40`, for example). Avoid this form when possible: the URL can be exposed in shell history and process listings, and `harper login` can save its target to the project `.env` file. Prefer environment variables or a saved login for routine use. +Percent-encode reserved characters in either value (`@` becomes `%40`, for example). Avoid this form when possible: the URL can be exposed in shell history and process listings. Prefer environment variables or a saved login for routine use. ## Security Best Practices @@ -506,6 +539,9 @@ If environment variables aren't working: - Variables must be exported before running commands - Variables set in one terminal don't affect other terminals +4. **Check for a refused project `.env`**: + - If the error says a name `must not come from a .env or .env.vault file`, remove that line or set the name in your environment. See [Project `.env` files](#project-env-files) + ## See Also - [CLI Overview](./overview.md) - General CLI information diff --git a/reference/cli/commands.md b/reference/cli/commands.md index c9cf4023b..05c9e4f27 100644 --- a/reference/cli/commands.md +++ b/reference/cli/commands.md @@ -488,9 +488,11 @@ The `harper install` command operates exactly like the [`harper`](#harper) comma Available since: v5.1.0 -Log in to a Harper instance to store authentication tokens locally. Once logged in, subsequent commands targeting this instance (via `target`) will automatically use the stored token. +Log in to a Harper instance to store authentication tokens locally. Once logged in, subsequent commands targeting this instance (via `target`) will automatically use the stored token. The instance also becomes the CLI's saved target, so later commands can omit `target` from any directory. See [How the CLI Picks a Target](./authentication.md#how-the-cli-picks-a-target). -The CLI also supports `.env` files. When you log in in a directory that already has a `.env` file, and neither that file nor your environment sets `HARPER_CLI_TARGET` or `CLI_TARGET`, the CLI appends `HARPER_CLI_TARGET` to it. It never creates the file. This allows you to omit the `target` parameter in subsequent commands within that directory. + + +`harper login` writes only to `~/.harperdb/credentials.json`, and no longer appends `HARPER_CLI_TARGET` to a project `.env`. It stops with an error if a `.env` file in the current directory sets the CLI's target or credentials. See [Project `.env` files](./authentication.md#project-env-files). ```bash harper login @@ -505,7 +507,7 @@ harper login You'll be asked to type in the following information: -- `` - If a URL parameter is not provided, you'll be prompted to enter the URL of the Harper instance to log in to. +- `` - If a URL parameter is not provided, you'll be prompted to enter the URL of the Harper instance to log in to. An exported `HARPER_CLI_TARGET` or `CLI_TARGET` is the default answer. - `` - Harper admin username. - `` - Harper admin password. @@ -536,6 +538,10 @@ harper logout - `` - The URL of the Harper instance to log out from. If none is provided, you'll be signed out of all instances. + + +`harper logout` does not read `.env`, so it runs in a directory whose `.env` other commands refuse. It does not edit that file. + ## Information Commands ### `harper version` diff --git a/reference/cli/overview.md b/reference/cli/overview.md index 5c8f021ea..2509c4ade 100644 --- a/reference/cli/overview.md +++ b/reference/cli/overview.md @@ -166,7 +166,7 @@ Provide credentials via: - **Dedicated authentication parameters**: Use `auth_username= auth_password=` for one-off commands - **Target URL credentials**: Embed a complete username and password in the URL (supported, but not recommended because URLs are easily exposed) -- **Environment variables and `.env` files**: Use `HARPER_CLI_TARGET` with `HARPER_CLI_USERNAME` and `HARPER_CLI_PASSWORD` (project-specific configuration) +- **Environment variables**: Export `HARPER_CLI_TARGET` with `HARPER_CLI_USERNAME` and `HARPER_CLI_PASSWORD` in your shell or CI environment. A `.env` file in the current directory cannot set them (v5.4.0); see [Project `.env` files](./authentication.md#project-env-files) - **Workload identity (OIDC)**: on GitHub Actions, the CLI trades the runner's identity token for an operation token against a [trust policy](./authentication.md#workload-identity-oidc), so the pipeline stores no Harper credential (recommended for CI/CD, v5.3.0) - **Token credentials**: `HARPER_CLI_REFRESH_TOKEN`, provisioned with [`harper login --for-ci`](./authentication.md#token-credentials-for-cicd) (for CI/CD where workload identity is not available) - **Persistent Login**: `harper login` to store tokens (recommended for local development) @@ -174,7 +174,7 @@ Provide credentials via: This list is abbreviated and is **not** in precedence order. See [Authentication Precedence](./authentication.md#authentication-precedence) for the resolution order, which changed in v5.2.0, and for the preferred and legacy environment-variable namespaces. Configure one style per context rather than combining them. -**Example: Persistent Login and `.env`**: +**Example: Persistent Login**: ```bash # Log in to a specific target @@ -184,7 +184,7 @@ harper login https://server.com:9925 harper describe_database database=dev ``` -If the current directory has a `.env` file that sets no target, `harper login` also appends `HARPER_CLI_TARGET` to it. +`harper login` saves the target in `~/.harperdb/credentials.json`, and later commands use it from any directory. See [How the CLI Picks a Target](./authentication.md#how-the-cli-picks-a-target). **Example: CLI Target Environment Variables**: diff --git a/reference/environment-variables/overview.md b/reference/environment-variables/overview.md index 9e056e71d..9b7f55a51 100644 --- a/reference/environment-variables/overview.md +++ b/reference/environment-variables/overview.md @@ -60,6 +60,12 @@ Harper's own instance-wide configuration is composed once at startup, **before** To change Harper's configuration, set it in the [configuration file](../configuration/overview.md) or export the variable in the real process/container environment **before** Harper starts — not through `loadEnv`. ::: +:::note + + +The `harper` CLI reads a `.env` file in the current directory separately from `loadEnv`, and stops with an error if it sets the CLI's target, credentials, or a TLS or proxy name such as `HTTPS_PROXY`. `loadEnv` still loads those names at runtime, but commands such as `harper deploy` fail from that directory. Set them in the process environment, or keep them in a differently named file listed under `files`. See [Project `.env` files](../cli/authentication.md#project-env-files). +::: + ## Managing `.env` Files Remotely diff --git a/release-notes/v5-lincoln/5.4.md b/release-notes/v5-lincoln/5.4.md index 84dcb9450..072125451 100644 --- a/release-notes/v5-lincoln/5.4.md +++ b/release-notes/v5-lincoln/5.4.md @@ -14,6 +14,8 @@ Full-text indexes using fulltext 0.5.0 with current field-based declarations, or An OIDC exchange now refuses a token that two enabled trust policies give a different user or different operations, where before the first policy by `id` answered (see [Conflicting Trust Policies Are Refused](#conflicting-trust-policies-are-refused)). Before upgrading, run `list_oidc_trust` and look for two enabled policies, with the same issuer and audience, whose claims can match the same runs but which name different users or `operations`, such as the policies of two `harper deploy setup=true provider=github-actions` runs that share a workflow, branch and environment. Drop, disable or narrow one of each pair, or the runs both match stop authenticating. A 5.4 node's `list_oidc_trust` names each pair in `invalid_reason`. Upgrade every node: a node still running 5.3 keeps answering with the first policy by `id`. +The `harper` CLI now stops with an error when a `.env` file in the current directory sets its target, credentials or connection settings (see [A Project `.env` No Longer Configures the CLI](#a-project-env-no-longer-configures-the-cli)). Before upgrading the CLI, remove `HARPER_CLI_*` and `CLI_TARGET*` lines from project `.env` files, including the `HARPER_CLI_TARGET` line that `npm create harper@latest` and earlier `harper login` versions wrote there. + Harper 5.4 marks failed transactions as aborted in the RocksDB transaction log by default ([`storage.rocks.transactionLogAbortMarkers`](/reference/v5/database/storage-tuning#storagerockstransactionlogabortmarkers); see [Failed Transactions Are Marked Aborted](#failed-transactions-are-marked-aborted-in-the-transaction-log)). Harper 5.3.4 and earlier cannot read those markers and would treat the failed transactions as committed. Do not downgrade a node to them, or open its database files or backups with them, after it has run 5.4 with the setting on. Harper 5.3.5 and later read the markers. Setting it to `false` later stops new markers but does not remove ones already written. - **Upgraded instances keep their `applications.lockdown` mode.** Only new installs get the new `seal-after-load` default; an instance installed earlier keeps the mode it was installed with (`freeze-after-load` since 5.0.2, `freeze` in 5.0.0 and 5.0.1) until you change it. A configuration carried over from v4 without a `lockdown` value still has no lockdown. To switch, set `applications.lockdown: seal-after-load` (in a cluster, only after every node runs v5.4.0 or later). See [Intrinsics Are Sealed Instead of Frozen by Default](#intrinsics-are-sealed-instead-of-frozen-by-default). @@ -306,6 +308,18 @@ The seal modes also seal `Function.prototype`, which the freeze modes leave exte The default changed because freezing is slow on Node.js. With frozen prototypes, V8 takes a slow path for every store into an array hole on that thread, Harper's own code included: in Harper's benchmark, msgpackr decoding inside a worker ran about four times slower than under `seal-after-load`. Sealing does not have that cost. `freeze-after-load` and `freeze` are unchanged; `none` and `ses` are also unchanged. See [Intrinsic Lockdown](/reference/v5/components/module-loading#intrinsic-lockdown) ([harper#3552](https://github.com/HarperFast/harper/pull/3552)). +### A Project `.env` No Longer Configures the CLI + +[Refuse a project .env CLI target or credential, and save logins under the client's target](https://github.com/HarperFast/harper/pull/4001) stops a cloned project from choosing where the `harper` CLI sends credentials, and stops a login server from choosing where its token is saved: + +- **A project `.env` cannot set the CLI's target, credentials or connection trust.** Operations API commands, `harper login` and the backup commands stop with an error naming the keys when a `.env` or `.env.vault` file in the current directory sets one that the environment does not. That covers `HARPER_CLI_*`, `CLI_TARGET*`, `HOME`, the TLS and proxy variables and the workload-identity and `GITHUB_*` deploy inputs; [Project `.env` files](/reference/v5/cli/authentication#project-env-files) has the full list. Exported values work as before and win over the file, and other keys still load. +- **`harper login` no longer writes `.env`.** It saves the target in `~/.harperdb/credentials.json`, which later commands use by default. It saves and prints the URL you gave it, never a target named in the server's reply. +- **`harper logout` no longer reads `.env`.** + +Application `.env` handling in `harper run`, `harper dev` and components is unchanged. + +**Upgrade impact:** a project whose `.env` sets one of these names now gets the error, and `target=` on the command does not get past it. Remove the line, then rely on the target `harper login ` saves, pass `target=`, or export the variable in your shell or CI environment. Loading the file deliberately in a script, `dotenv -- harper deploy`, also works, and trusts everything in that file. CI that stores `harper login --for-ci` output as secrets is unaffected. + ## Authentication ### Local Requests Use a Built-in User From 494e8e4de0b8e629a506b3249835a2a44fefd4e5 Mon Sep 17 00:00:00 2001 From: Kris Zyp Date: Tue, 3 Nov 2026 15:59:16 -0700 Subject: [PATCH 2/5] Align CLI .env summaries with the canonical refused-name list Short summaries named only part of the list or dropped the environment exception, and HARPER_CLI_* overstated it: HARPER_CLI_TIMEOUT_MS still loads. Note runtime keys for staged releases that keep loadEnv. Dispatch-Task: docs-harper-4001 Co-Authored-By: Claude Opus 5.5 --- fabric/cluster-creation-management.md | 2 +- learn/administration/safe-deployments-and-rollback.mdx | 2 +- reference/cli/authentication.md | 6 +++--- reference/cli/commands.md | 2 +- reference/environment-variables/overview.md | 2 +- release-notes/v5-lincoln/5.4.md | 4 ++-- 6 files changed, 9 insertions(+), 9 deletions(-) diff --git a/fabric/cluster-creation-management.md b/fabric/cluster-creation-management.md index 46fe47618..b586e478c 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 `HARPER_CLI_TARGET`, so 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. 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, so remove that line. See [Project `.env` files](/reference/v5/cli/authentication#project-env-files). ```bash harper login diff --git a/learn/administration/safe-deployments-and-rollback.mdx b/learn/administration/safe-deployments-and-rollback.mdx index ac574c343..e648dc0e8 100644 --- a/learn/administration/safe-deployments-and-rollback.mdx +++ b/learn/administration/safe-deployments-and-rollback.mdx @@ -81,7 +81,7 @@ cp deploy.config.yaml deploy/config.yaml (cd deploy && harper deploy project=my-app restart=true) ``` -The subshell inherits `HARPER_CLI_TARGET`, so the staged directory needs no `.env`. 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 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). ### Deploy from GitHub Actions diff --git a/reference/cli/authentication.md b/reference/cli/authentication.md index 1d61aa8ae..c08524c08 100644 --- a/reference/cli/authentication.md +++ b/reference/cli/authentication.md @@ -24,7 +24,7 @@ harper get_components harper set_configuration logging_level=info ``` -When no `target` parameter is specified, the CLI falls back to the target saved by a previous `harper login` if there is one, and only otherwise to the local domain socket connection, which gives authenticated access to the local Harper instance. See [Authentication Precedence](#authentication-precedence) for what that means on a shared machine. +When no `target` parameter is specified, the CLI falls back to a target set in the environment, then to the target saved by a previous `harper login` if there is one, and only otherwise to the local domain socket connection, which gives authenticated access to the local Harper instance. See [How the CLI Picks a Target](#how-the-cli-picks-a-target), and [Authentication Precedence](#authentication-precedence) for what that means on a shared machine. ## Remote Operations @@ -186,7 +186,7 @@ harper add_user \ A `.env` or `.env.vault` file in the current directory cannot configure the CLI's target, credentials or connection trust. That directory is often a cloned project, and a file it ships must not decide where your credentials go ([harper#4001: Refuse a project .env CLI target or credential](https://github.com/HarperFast/harper/pull/4001)). -Operations API commands, including `harper deploy`, as well as `harper login` and the backup commands, read the file first. If it sets one of these names and the shell or CI environment does not, the command stops with an error naming the keys. It stops before contacting a server or touching a file, for local operations too: +Every Operations API command, including `harper deploy` and `harper preview`, as well as `harper login` and the backup commands, reads the file first. If it sets one of these names and the shell or CI environment does not, the command stops with an error naming the keys. It stops before contacting a server or touching a file, for local operations too: | Purpose | Names, in any letter case | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -207,7 +207,7 @@ error: HARPER_CLI_TARGET must not come from a .env or .env.vault file in /path/t - **Other keys still load.** A file with none of these names is applied as before, and `.env.example` and `.env.local` are not read at all. - **Applications are unaffected.** `.env` handling in `harper run`, `harper dev` and a component's [`loadEnv`](../environment-variables/overview.md) is unchanged. `harper status`, `harper version`, `harper logout`, `harper agent` and `harper mcp` do not read the file. -To migrate a project, remove the `HARPER_CLI_*` and `CLI_TARGET*` lines from its `.env`. `npm create harper@latest` writes `HARPER_CLI_TARGET` there, and `harper login` before v5.4.0 could append it. Then choose where the target comes from: +To migrate a project, remove the listed names from its `.env`. Other names with these prefixes, such as `HARPER_CLI_TIMEOUT_MS`, still load. `npm create harper@latest` writes `HARPER_CLI_TARGET` there, and `harper login` before v5.4.0 could append it. Then choose where the target comes from: | Route | Scope | | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | diff --git a/reference/cli/commands.md b/reference/cli/commands.md index 05c9e4f27..c87dbf011 100644 --- a/reference/cli/commands.md +++ b/reference/cli/commands.md @@ -492,7 +492,7 @@ Log in to a Harper instance to store authentication tokens locally. Once logged -`harper login` writes only to `~/.harperdb/credentials.json`, and no longer appends `HARPER_CLI_TARGET` to a project `.env`. It stops with an error if a `.env` file in the current directory sets the CLI's target or credentials. See [Project `.env` files](./authentication.md#project-env-files). +`harper login` writes only to `~/.harperdb/credentials.json`, and no longer appends `HARPER_CLI_TARGET` to a project `.env`. It stops with an error if a `.env` file in the current directory sets a name the CLI refuses, such as its target, credentials or a proxy setting, and your environment does not. See [Project `.env` files](./authentication.md#project-env-files). ```bash harper login diff --git a/reference/environment-variables/overview.md b/reference/environment-variables/overview.md index 9b7f55a51..79c08a9ee 100644 --- a/reference/environment-variables/overview.md +++ b/reference/environment-variables/overview.md @@ -63,7 +63,7 @@ To change Harper's configuration, set it in the [configuration file](../configur :::note -The `harper` CLI reads a `.env` file in the current directory separately from `loadEnv`, and stops with an error if it sets the CLI's target, credentials, or a TLS or proxy name such as `HTTPS_PROXY`. `loadEnv` still loads those names at runtime, but commands such as `harper deploy` fail from that directory. Set them in the process environment, or keep them in a differently named file listed under `files`. See [Project `.env` files](../cli/authentication.md#project-env-files). +The `harper` CLI reads a `.env` file in the current directory separately from `loadEnv`, and stops with an error if it sets the CLI's target, credentials, or a TLS or proxy name such as `HTTPS_PROXY`, unless the environment already sets that name. `loadEnv` still loads those names at runtime, but commands such as `harper deploy` fail from that directory. Set them in the process environment, or keep them in a differently named file listed under `files`. See [Project `.env` files](../cli/authentication.md#project-env-files). ::: ## Managing `.env` Files Remotely diff --git a/release-notes/v5-lincoln/5.4.md b/release-notes/v5-lincoln/5.4.md index 072125451..2708ca71e 100644 --- a/release-notes/v5-lincoln/5.4.md +++ b/release-notes/v5-lincoln/5.4.md @@ -14,7 +14,7 @@ Full-text indexes using fulltext 0.5.0 with current field-based declarations, or An OIDC exchange now refuses a token that two enabled trust policies give a different user or different operations, where before the first policy by `id` answered (see [Conflicting Trust Policies Are Refused](#conflicting-trust-policies-are-refused)). Before upgrading, run `list_oidc_trust` and look for two enabled policies, with the same issuer and audience, whose claims can match the same runs but which name different users or `operations`, such as the policies of two `harper deploy setup=true provider=github-actions` runs that share a workflow, branch and environment. Drop, disable or narrow one of each pair, or the runs both match stop authenticating. A 5.4 node's `list_oidc_trust` names each pair in `invalid_reason`. Upgrade every node: a node still running 5.3 keeps answering with the first policy by `id`. -The `harper` CLI now stops with an error when a `.env` file in the current directory sets its target, credentials or connection settings (see [A Project `.env` No Longer Configures the CLI](#a-project-env-no-longer-configures-the-cli)). Before upgrading the CLI, remove `HARPER_CLI_*` and `CLI_TARGET*` lines from project `.env` files, including the `HARPER_CLI_TARGET` line that `npm create harper@latest` and earlier `harper login` versions wrote there. +The `harper` CLI now stops with an error when a `.env` file in the current directory sets its target, credentials or connection settings (see [A Project `.env` No Longer Configures the CLI](#a-project-env-no-longer-configures-the-cli)). Before upgrading the CLI, remove the CLI's target and credential lines from project `.env` files, including the `HARPER_CLI_TARGET` line that `npm create harper@latest` and earlier `harper login` versions wrote there. Harper 5.4 marks failed transactions as aborted in the RocksDB transaction log by default ([`storage.rocks.transactionLogAbortMarkers`](/reference/v5/database/storage-tuning#storagerockstransactionlogabortmarkers); see [Failed Transactions Are Marked Aborted](#failed-transactions-are-marked-aborted-in-the-transaction-log)). Harper 5.3.4 and earlier cannot read those markers and would treat the failed transactions as committed. Do not downgrade a node to them, or open its database files or backups with them, after it has run 5.4 with the setting on. Harper 5.3.5 and later read the markers. Setting it to `false` later stops new markers but does not remove ones already written. @@ -312,7 +312,7 @@ The default changed because freezing is slow on Node.js. With frozen prototypes, [Refuse a project .env CLI target or credential, and save logins under the client's target](https://github.com/HarperFast/harper/pull/4001) stops a cloned project from choosing where the `harper` CLI sends credentials, and stops a login server from choosing where its token is saved: -- **A project `.env` cannot set the CLI's target, credentials or connection trust.** Operations API commands, `harper login` and the backup commands stop with an error naming the keys when a `.env` or `.env.vault` file in the current directory sets one that the environment does not. That covers `HARPER_CLI_*`, `CLI_TARGET*`, `HOME`, the TLS and proxy variables and the workload-identity and `GITHUB_*` deploy inputs; [Project `.env` files](/reference/v5/cli/authentication#project-env-files) has the full list. Exported values work as before and win over the file, and other keys still load. +- **A project `.env` cannot set the CLI's target, credentials or connection trust.** Operations API commands, `harper login` and the backup commands stop with an error naming the keys when a `.env` or `.env.vault` file in the current directory sets one that the environment does not. That covers the `HARPER_CLI_` and `CLI_TARGET` target and credential names, `HOME`, TLS and proxy variables, and workload-identity and `GITHUB_` deploy inputs; [Project `.env` files](/reference/v5/cli/authentication#project-env-files) has the full list. Exported values work as before and win over the file, and other keys still load. - **`harper login` no longer writes `.env`.** It saves the target in `~/.harperdb/credentials.json`, which later commands use by default. It saves and prints the URL you gave it, never a target named in the server's reply. - **`harper logout` no longer reads `.env`.** From 1abbda591c9646215119d8dfb875f0134ffa5101 Mon Sep 17 00:00:00 2001 From: Kris Zyp Date: Tue, 3 Nov 2026 16:03:31 -0700 Subject: [PATCH 3/5] State the environment exception and runtime names in the 5.4 note Dispatch-Task: docs-harper-4001 Co-Authored-By: Claude Opus 5.5 --- release-notes/v5-lincoln/5.4.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/release-notes/v5-lincoln/5.4.md b/release-notes/v5-lincoln/5.4.md index 2708ca71e..db366dd86 100644 --- a/release-notes/v5-lincoln/5.4.md +++ b/release-notes/v5-lincoln/5.4.md @@ -14,7 +14,7 @@ Full-text indexes using fulltext 0.5.0 with current field-based declarations, or An OIDC exchange now refuses a token that two enabled trust policies give a different user or different operations, where before the first policy by `id` answered (see [Conflicting Trust Policies Are Refused](#conflicting-trust-policies-are-refused)). Before upgrading, run `list_oidc_trust` and look for two enabled policies, with the same issuer and audience, whose claims can match the same runs but which name different users or `operations`, such as the policies of two `harper deploy setup=true provider=github-actions` runs that share a workflow, branch and environment. Drop, disable or narrow one of each pair, or the runs both match stop authenticating. A 5.4 node's `list_oidc_trust` names each pair in `invalid_reason`. Upgrade every node: a node still running 5.3 keeps answering with the first policy by `id`. -The `harper` CLI now stops with an error when a `.env` file in the current directory sets its target, credentials or connection settings (see [A Project `.env` No Longer Configures the CLI](#a-project-env-no-longer-configures-the-cli)). Before upgrading the CLI, remove the CLI's target and credential lines from project `.env` files, including the `HARPER_CLI_TARGET` line that `npm create harper@latest` and earlier `harper login` versions wrote there. +The `harper` CLI now stops with an error when a `.env` file in the current directory sets its target, credentials or connection settings and the environment does not (see [A Project `.env` No Longer Configures the CLI](#a-project-env-no-longer-configures-the-cli)). Before upgrading the CLI, move those names out of project `.env` files, including the `HARPER_CLI_TARGET` line that `npm create harper@latest` and earlier `harper login` versions wrote there. Harper 5.4 marks failed transactions as aborted in the RocksDB transaction log by default ([`storage.rocks.transactionLogAbortMarkers`](/reference/v5/database/storage-tuning#storagerockstransactionlogabortmarkers); see [Failed Transactions Are Marked Aborted](#failed-transactions-are-marked-aborted-in-the-transaction-log)). Harper 5.3.4 and earlier cannot read those markers and would treat the failed transactions as committed. Do not downgrade a node to them, or open its database files or backups with them, after it has run 5.4 with the setting on. Harper 5.3.5 and later read the markers. Setting it to `false` later stops new markers but does not remove ones already written. @@ -318,7 +318,7 @@ The default changed because freezing is slow on Node.js. With frozen prototypes, Application `.env` handling in `harper run`, `harper dev` and components is unchanged. -**Upgrade impact:** a project whose `.env` sets one of these names now gets the error, and `target=` on the command does not get past it. Remove the line, then rely on the target `harper login ` saves, pass `target=`, or export the variable in your shell or CI environment. Loading the file deliberately in a script, `dotenv -- harper deploy`, also works, and trusts everything in that file. CI that stores `harper login --for-ci` output as secrets is unaffected. +**Upgrade impact:** a project whose `.env` sets one of these names now gets the error, and `target=` on the command does not get past it. Remove a target or credential line, then rely on the target `harper login ` saves, pass `target=`, or export the variable in your shell or CI environment. Move a name your application reads at runtime, such as a proxy setting, to the process environment or a differently named file that `loadEnv` lists. Loading the file deliberately in a script, `dotenv -- harper deploy`, also works, and trusts everything in that file. CI that stores `harper login --for-ci` output as secrets is unaffected. ## Authentication From 24f410aef961a9cf428c514a33843db4303c96fb Mon Sep 17 00:00:00 2001 From: Kris Zyp Date: Tue, 3 Nov 2026 16:07:57 -0700 Subject: [PATCH 4/5] Note the .env refusal on the setup commands run from a project checkout Dispatch-Task: docs-harper-4001 Co-Authored-By: Claude Opus 5.5 --- reference/cli/commands.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/reference/cli/commands.md b/reference/cli/commands.md index c87dbf011..8508be389 100644 --- a/reference/cli/commands.md +++ b/reference/cli/commands.md @@ -274,7 +274,7 @@ See [`deploy_component` credentials](../operations-api/operations.md#deploy-cred -`harper deploy setup=true provider=github-actions` sets a cluster up so a GitHub Actions workflow can deploy with its [OIDC identity token](./authentication.md#workload-identity-oidc) instead of a stored credential. Run it once, signed in to the cluster as a `super_user` (`harper login`), from the project's checkout: +`harper deploy setup=true provider=github-actions` sets a cluster up so a GitHub Actions workflow can deploy with its [OIDC identity token](./authentication.md#workload-identity-oidc) instead of a stored credential. Run it once, signed in to the cluster as a `super_user` (`harper login`), from the project's checkout. Remove any `HARPER_CLI_TARGET` line from that checkout's `.env` first; see [Project `.env` files](./authentication.md#project-env-files): ```bash harper deploy setup=true provider=github-actions project=my-app @@ -312,7 +312,7 @@ A preview of the application `my-app` for PR `42` is the [isolated application]( #### `harper preview setup` -Enables previews of one application on the cluster, and sets up the GitHub side. Run it once, signed in to the cluster as a `super_user` (`harper login`), from a checkout of the application's repository: +Enables previews of one application on the cluster, and sets up the GitHub side. Run it once, signed in to the cluster as a `super_user` (`harper login`), from a checkout of the application's repository. Remove any `HARPER_CLI_TARGET` line from that checkout's `.env` first; see [Project `.env` files](./authentication.md#project-env-files): ```bash harper preview setup app=my-app target=https://my-cluster.example.com:9925 From a792e3f0e9f9c624424774127ea5d99cfab5ee63 Mon Sep 17 00:00:00 2001 From: Kris Zyp Date: Tue, 3 Nov 2026 16:16:18 -0700 Subject: [PATCH 5/5] Give the .env refusal its own sentence on the summary pages Dispatch-Task: docs-harper-4001 Co-Authored-By: Claude Opus 5.5 --- fabric/cluster-creation-management.md | 2 +- learn/administration/safe-deployments-and-rollback.mdx | 2 +- reference/environment-variables/overview.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/fabric/cluster-creation-management.md b/fabric/cluster-creation-management.md index b586e478c..ed0199434 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, so 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. 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). ```bash harper login diff --git a/learn/administration/safe-deployments-and-rollback.mdx b/learn/administration/safe-deployments-and-rollback.mdx index e648dc0e8..a8b026dfe 100644 --- a/learn/administration/safe-deployments-and-rollback.mdx +++ b/learn/administration/safe-deployments-and-rollback.mdx @@ -41,7 +41,7 @@ Commands such as `harper deploy`, `harper list_deployments`, and `harper get_job -Remove any `HARPER_CLI_TARGET` line from your project's `.env`. `npm create harper@latest` writes one there, and 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). +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). ### A Harper backend diff --git a/reference/environment-variables/overview.md b/reference/environment-variables/overview.md index 79c08a9ee..08a39ab62 100644 --- a/reference/environment-variables/overview.md +++ b/reference/environment-variables/overview.md @@ -63,7 +63,7 @@ To change Harper's configuration, set it in the [configuration file](../configur :::note -The `harper` CLI reads a `.env` file in the current directory separately from `loadEnv`, and stops with an error if it sets the CLI's target, credentials, or a TLS or proxy name such as `HTTPS_PROXY`, unless the environment already sets that name. `loadEnv` still loads those names at runtime, but commands such as `harper deploy` fail from that directory. Set them in the process environment, or keep them in a differently named file listed under `files`. See [Project `.env` files](../cli/authentication.md#project-env-files). +The `harper` CLI reads a `.env` file in the current directory separately from `loadEnv`. It stops with an error if the file sets the CLI's target, credentials, or a TLS or proxy name such as `HTTPS_PROXY`, unless the environment already sets that name. `loadEnv` still loads those names at runtime, but commands such as `harper deploy` fail from that directory. Set them in the process environment, or keep them in a differently named file listed under `files`. See [Project `.env` files](../cli/authentication.md#project-env-files). ::: ## Managing `.env` Files Remotely