[kriszyp]

⊙ Problem

Refuse a project .env CLI target or credential, and save logins under the client's target (harper#4001) makes the harper CLI stop with an error when a project's .env sets its target, credentials or connection settings. Our docs still tell readers to put HARPER_CLI_TARGET there and say harper login writes it. On that CLI, the safe-deployments guide fails at its first step.

🤔 Are docs enough?

Not alone. npm create harper@latest still writes HARPER_CLI_TARGET in .env, so a new project's harper login and npm run deploy fail on a 5.4 CLI. These docs tell readers to remove the line, but create-harper needs its own change before 5.4 ships. No issue tracks it yet.

💡 Solution

• One section holds the rule: the refused names, the exceptions and how to migrate. Other pages keep a short summary and link to it.
• A new list shows how the CLI picks a target, because the saved target applies to the whole OS user, not one project.
• The safe-deployments guide now exports HARPER_CLI_TARGET and no longer copies .env into a staged release.
• The 5.4 notes get an upgrade note and a section.

⚖️ Alternatives

🤔 Export the target in the guide, or rely on the saved login?

Export. The saved target moves with each login, so a bare rollback command could reach another cluster. The cost is setting it again in each new shell.

🤔 Document dotenv -- harper deploy?

Yes, once, with a warning. harper#4001 lists this option, but it passes the CLI everything in the file, bypassing the check. The guide does not use it.

🤔 How does a team share a target now?

target= in a package.json script replaces the old advice to commit .env. The URL stays visible in review, and a script needs no new dependency.

🔧 Changes

• reference/cli/authentication.md: Project .env files is the new canonical section, with the refused names and when the command stops, the exception for names already in the environment, the migration routes and names an application reads at runtime. How the CLI Picks a Target is new, and the Local Operations fallback now matches it. Login's writes, the Method 2 intro, the credentials-in-URL warning and troubleshooting are corrected; the example .env and "Automatic .env Updates" are gone.
• learn/administration/safe-deployments-and-rollback.mdx: the login step exports the target, a note says to remove the scaffolded line, the staged release no longer copies .env, and the polling explanation names the variable. Look hardest here: it is the one recipe that changed.
• reference/cli/commands.md: harper login, its URL prompt default and harper logout are updated, and deploy setup and preview setup say to remove the line first.
• reference/cli/overview.md: the authentication list and login example are corrected.
• reference/backups/operations.md: an environment target is forwarded, and a refused .env stops the command before it forwards or touches a file.
• reference/environment-variables/overview.md: a note separates loadEnv from the CLI's read.
• fabric/cluster-creation-management.md: the connect step no longer says login appends to .env.
• release-notes/v5-lincoln/5.4.md: an upgrade note and a section with its upgrade impact.

reference/components/applications.md and the getting-started guide also show harper login, with no note: neither scaffolds with create-harper, and the error names the fix. The v4 snapshot is unchanged. These pages stay here, like other open 5.4 docs PRs, until Assemble the v5 reference and open release notes from harper and harper-pro (#788) lands.

✅ Verification

• Ran each documented behavior on a throwaway Harper built from the harper#4001 head (249786d1), with scratch HOME and ROOTPATH. The guide's export, login, deploy and staged deploy all worked.
• format:check, lint, typecheck, test:examples and build pass. The three new anchors are in the built HTML.

What the CLI did

In the project	Command	Result
.env sets the target	an operation, harper login <url>, list_backups (server running and stopped), harper deploy	exit 1, error names the key
.env sets the target	the same with target=<url>	exit 1
.env sets NODE_EXTRA_CA_CERTS	local get_components	exit 1
.env sets https_proxy	with HTTPS_PROXY exported	exit 1 (Linux)
.env sets the target	with it exported, or under dotenv --	runs
.env sets the target	harper logout, version, status	runs
.env.local sets HTTPS_PROXY; .env.example sets the target	an operation	runs
Clean .env	harper login <url>, then a bare operation	.env unchanged, last_target saved and used
Clean .env	harper logout <url>	last_target cleared
Clean .env	npm run deploy with target= in the script	deployed

Not run: Windows, and .env.vault end to end (the loader reads it through dotenv).

Depends-on: harper#4001

Refs HarperFast/harper#1927, HarperFast/harper#1928

Signed: Claude Opus 5.5 (dev-agent, dispatch task docs-harper-4001)

🤖 Generated with Claude Code

Related PRs: #788 overlaps, 2 others independent

Late Grok findings

6 surviving (highest minor) — Grok reviewed 08690bf

• minor — release-notes/v5-lincoln/5.4.md:321 — the upgrade paragraph says "Remove the line" for any refused name. For an application value such as HTTPS_PROXY, that drops the value the component's loadEnv was supplying, and the paragraph gives no other place to put it.
• minor — learn/administration/safe-deployments-and-rollback.mdx:84 — the staged release no longer copies .env, so values a kept loadEnv entry reads stop reaching the nodes. (previously adjudicated)
• minor — reference/environment-variables/overview.md:66 — short summaries of the refusal rule on other pages leave out the "unless the environment sets it" exception and the full set of refused names. (previously adjudicated)
• minor — reference/cli/authentication.md:27 — the "Local Operations" fallback (saved login, then socket) contradicts the new ordered list at reference/cli/authentication.md:37-42, which puts the environment target in between. (previously adjudicated)
• minor — release-notes/v5-lincoln/5.4.md:315 — "That covers HARPER_CLI_*" names more than the closed list the CLI actually refuses. Same wording in the migration text at reference/cli/authentication.md:210 and release-notes/v5-lincoln/5.4.md:17. (previously adjudicated)
• nit — reference/cli/authentication.md:189 — the list of commands that read .env doesn't name harper preview (reference/cli/commands.md:305). (previously adjudicated)

Not standing: 3 merged. Grok ran 8m (8m from launch to report); the fold adjudication (cursor-grok@08690bf95b23-bbf9ec41, claude) took 1m.

Origin — the dispatch brief this PR was written from

Document that the harper CLI refuses a project .env target or credential

Document a breaking CLI change from HarperFast/harper PR HarperFast/harper#4001 (fixes harper#1927 and harper#1928), targeted at v5.4.

What changed for users:

• The harper CLI no longer lets a .env file in the current directory set its target, credentials or connection trust. If that file sets any of HARPER_CLI_TARGET, CLI_TARGET, HARPER_CLI_USERNAME/_PASSWORD/_OPERATION_TOKEN/_REFRESH_TOKEN (and the CLI_TARGET_* equivalents), ACTIONS_ID_TOKEN_REQUEST_URL/_TOKEN, GITHUB_REPOSITORY/GITHUB_SHA/GITHUB_REF/GITHUB_EVENT_PATH, HOME/USERPROFILE, NODE_TLS_REJECT_UNAUTHORIZED, NODE_EXTRA_CA_CERTS, SSL_CERT_FILE/SSL_CERT_DIR, NODE_USE_ENV_PROXY, HTTP_PROXY/HTTPS_PROXY/NO_PROXY (any letter case) and the shell/CI environment does not already set it, CLI operations, harper login and the backup commands stop with an error naming the keys. Values exported in the shell or CI environment work as before and win over the file. Other .env keys still load. Application runtime .env handling (harper run/dev, components) is unchanged.
• harper login no longer appends HARPER_CLI_TARGET to the project .env; it saves the target it connected to in ~/.harperdb/credentials.json, which later commands use by default. It always saves and prints the URL the user gave, never a target named by the server's reply.
• harper logout no longer reads .env.

Migration to document: remove HARPER_CLI_* / CLI_TARGET* lines from the project .env; then either rely on harper login <url> (saved target), pass target=<url>, export the variables in the shell or CI secrets, or load the file deliberately in an npm script (dotenv -- harper deploy). CI using harper login --for-ci output as secrets is unaffected.

Find every page in the docs that tells users to put HARPER_CLI_TARGET (or credentials) in a project .env, or that says harper login writes it there, and update it; add a short note to the CLI reference / CLI authentication page and the v5.4 release notes if the repo keeps them. Link the harper PR. No customer names.

Acceptance

One draft documentation PR covering the CLI .env change and its migration, linking HarperFast/harper#4001.

_{Dispatch: task docs-harper-4001 · queued by task:harper-cli-target-credential-trust-bundle · ran by claude/opus/high · worker kzyp-xps-1}

_{Ready-For-Promotion: a792e3f urgency=normal late=folded}

_{Review-Coverage: authored=claude; ran=gemini,cursor-composer,codex,cursor-grok; late=cursor-grok:adjudicated; adjudicated=domain; declined=muse; rounds=5; full=2 @ a792e3f}

_{Review-Attention: skim ~2m (decisions: team-target-sharing-route, document-dotenv-cli-bypass, guide-uses-shell-export) @ a792e3f}

[gemini-code-assist]

Code Review

This pull request updates the Harper CLI documentation for version 5.4.0, detailing the new behavior where the CLI refuses to load targets, credentials, or connection settings from a project's local .env file and instead throws an error. The feedback focuses on improving readability by ensuring that these file refusal conditions and critical limitations are presented in separate, distinct sentences rather than being combined with other concepts.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-796

This preview will update automatically when you push new commits.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-796

This preview will update automatically when you push new commits.