fix(#790): preserve port from COUCH_URL when using --local

[inromualdo]

--local flag ignores port from COUCH_URL environment variable, always uses 5988

Description

Closes #790

Code review items

• Readable: Concise, well named, follows the style guide, documented if necessary.
• Documented: Configuration and user documentation on cht-docs
• Tested: Unit and/or integration tests where appropriate
• Backwards compatible: Works with existing data and configuration. Any breaking changes documented in the release notes.

License

The software is provided under AGPL-3.0. Contributions to this project are accepted under the same license.

[inromualdo]

cc: @andrablaj

[jkuester]

Thanks for the PR, @inromualdo!

One challenge that we have here is that the current logic of hardcoding the --local port to 5988 is because of how the COUCH_URL envar is used during cht-core development. When you set up your local environment for developing cht-core you need to set the COUCH_URL envar and it needs to point to the port on the host where Couch is listening. This is so that when you run the api server locally (via npm run dev-api) it can connect to your local Couch instance. So, in this case the COUCH_URL value must point to the Couch port (and not to the port that the CHT api server will be listening on).

On the other hand, when cht-conf connects to a --local CHT instance, it needs to use the port the the CHT api server is listening on (either the API_PORT envar or 5988). The --local option leverages the COUCH_URL as a "convenience", but really is trying to connect to a totally different service....

---

Honestly, I have considered the --local/COUCH_URL functionality to be targeted pretty much at cht-core development. What is your usecase here where you want to leverage --local instead of --url? Perhaps we just need to add the ability to specify a default CHT url to connect to via an envar that is NOT COUCH_URL (e.g. CHT_URL)....

[mrjones-plip]

Possibly relevant is that you can use localhost with the --url flag. I was able to run CHT Conf against a docker helper instance for example, which was running on port 10449:

cht --url=https://medic:password@localhost:10449

[inromualdo]

Thanks for the detailed review @jkuester, that makes total sense.

To give some context on why I'm using --local instead of --url: I use cht-conf through AI-assisted tools (like Claude Code), and --local lets credentials stay in the environment variable — never passed as a CLI argument. With --url, you have to inline the full URL with credentials, which means they'd flow through the AI. So --local (or an env-var-based alternative) is important for keeping secrets out of the conversation.

I hadn't considered that COUCH_URL intentionally points to CouchDB while --local needs to reach the API server. I agree that a dedicated environment variable is the right approach. Since cht-conf always talks to the CHT API (never directly to CouchDB), something like CHT_URL would be much clearer.

My thinking for the implementation:

1. Add CHT_URL support . When set, --local uses it as-is (port included), no rewriting
2. Keep COUCH_URL as fallback with the current behavior (credentials + hostname, port forced to 5988) for backward compatibility
3. Log a deprecation notice when COUCH_URL is used, nudging users toward CHT_URL

This way existing cht-core dev workflows keep working, and Docker/custom port setups get a clean solution.

Does that align with what you had in mind? Happy to rework the PR with this approach.

[jkuester]

👍 Got it! Very helpful to better understand the usecase here (for use with AI clients). My one thought with the CHT_URL is that maybe instead of overloading the --local approach, we would instead just have cht-conf read CHT_URL by default when no other connection option (like --local or --url) is provided. So, if you have the CHT_URL set, you can run cht commands without providing any connection option. What do you think of that approach?

I use cht-conf through AI-assisted tools (like Claude Code), and --local lets credentials stay in the environment variable — never passed as a CLI argument

I do wonder if it is possible to just use creds from an envar along with the --url option. In a normal bash shell you can just do:

cht --url="${CHT_URL}"

Would this work with Claude Code?