REFERENCE / 02

CLI reference

The package is a single command that starts a loopback-only helper and opens the editor. Flags are intentionally small: choose a port or skip the browser launch.

Package: v0.1.0
Node: >=20.19
Bins: 2
Bind host: 127.0.0.1

01 / QUICKSTART

Run it without installing.

npx downloads the package into a cache, runs it, and opens your browser. Nothing is added to your project.

terminal

$ npx open-gsd-core-config-manager

GSD Config Manager

  ➜  Local:   http://127.0.0.1:<port>
  ➜  Press Ctrl+C to stop

npx open-gsd-core-config-manager

02 / INSTALLATION

Three ways to run the same binary.

One-off

npx open-gsd-core-config-manager

Best for trying it. Cached by npx; not added to any project.

Global

npm install -g open-gsd-core-config-manager
open-gsd-core-config-manager

Also installs the alias gsd-config-editor — the same binary.

Project dev dependency

npm install --save-dev open-gsd-core-config-manager
npx open-gsd-core-config-manager

Pins the version through your project's lockfile.

03 / FLAGS

Command-line options.

Command-line flags
Flag	Argument	Behavior
`--port <number>`	Integer 0–65535	Bind an explicit loopback port. Omit it (or pass `0`) to let the OS assign a free ephemeral port. A non-numeric value or one above 65535 exits with status 1.
`--no-open`	—	Do not launch the default browser. The printed Local URL still works; useful over SSH or on headless machines.
`-h, --help`	—	Print the generated help and exit.

BINDING

The host is the loopback literal 127.0.0.1 in the source. No flag or environment variable changes it, so the server is never reachable from another machine.

PORT IN USE

If an explicitly requested port is already taken, the process reports Port <n> is already in use. and exits with status 1. Run without --port to get a free one.

04 / ENVIRONMENT

Environment variables.

Environment variables
Variable	Read by	Effect
`NO_COLOR`	Terminal output	Disables ANSI styling and switches Unicode symbols to ASCII, following the no-color.org convention. Plain mode is also used automatically when stdout is not a TTY.
`GSD_HOME`	Global defaults discovery	Overrides the home directory used to locate `~/.gsd/defaults.json`, mirroring gsd-core's own loader. Useful for isolated environments and tests.
`<PREFIX>_API_KEY`	Search providers	The environment-variable channel for optional search-provider keys (for example `BRAVE_API_KEY`). The tool detects and displays status; keys are never logged.

05 / FILES

What the tool reads and writes.

Files and locations
Path	Role	Touched by this tool?
`<project>/.planning/config.json`	The GSD config you edit	Read; written only on a confirmed, validated save or restore.
`~/.gsd/defaults.json`	Global defaults, used as a provenance layer	Read only.
`~/.gsd/<prefix>_api_key`	Optional search-provider key file	Written only when you save a key from the API-keys workspace; mode `0600`.
OS app-data directory	Snapshot history (`snapshots/<sha256(path)>`)	Written after a successful save, outside your project.

WINDOWS%LOCALAPPDATA%\open-gsd-core-config-manager\Data

MACOS~/Library/Application Support/open-gsd-core-config-manager

LINUX~/.local/share/open-gsd-core-config-manager

06 / LIFECYCLE

Startup, shutdown and exit codes.

Startup sequence

Create a launch context with a random UUID.
Build the guarded server and bind 127.0.0.1.
Read the assigned port back and seal the allowed origin.
Print the Local URL, then open the browser.
If opening the browser fails, print the URL to open manually — the server keeps running.

Shutdown and exits

On SIGINT or SIGTERM the server closes before the process exits, releasing the port. Saved changes are already on disk.

Exit codes
`0`	Clean exit after shutdown.
`1`	Invalid `--port`, port already in use, or startup failure.

07 / REMOVAL

Uninstall without losing your work.

Remove the package

npm uninstall -g open-gsd-core-config-manager
# or, for a project install
npm uninstall open-gsd-core-config-manager

What remains

Removing the package does not delete snapshots, stored API keys, or any .planning/config.json. Delete the app-data directory if you no longer need restore history. Losing key files means re-issuing keys at the provider.