Config file

Works with the CLI alone. No gander.md account.

~/.gander/config.json is the CLI's local state: API token, share map, local-watch defaults, and optional defaults for new shares. Treat api_token as a password. Do not commit the file. Do not paste the token into tickets.

The directory is mode 0700. The file is mode 0600. gander signup, gander auth, and gander share create or rewrite it.

Path and profiles

Default path: ~/.gander/config.json.

Set GANDER_CONFIG=<name> to use ~/.gander.<name>/config.json instead. The runner socket, watches, logs, and skill stay in that same profile directory.

GANDER_CONFIG=dev gander signup --email [email protected]
GANDER_CONFIG=dev gander list
GANDER_CONFIG=dev gander watch plan.md

Profile names must be a single path component: no /, \, ., or ... Named profiles never fall back to a legacy ~/.mdp file.

Example

{
  "watch": false,
  "debounce_ms": 150,
  "port": 0,
  "api_url": "https://gander.md",
  "email": "[email protected]",
  "api_token": "gmd_…",
  "doc_visibility": "private",
  "comment_access": "disabled",
  "shares": {
    "/abs/path/to/plan.md": "xK7m2pQa"
  }
}

Omit a key to keep its default. The CLI rewrites the whole struct on write, so unknown keys are dropped. Do not invent fields.

Fields

Field	Default	What it does
`watch`	`false`	Default to local live-reload (`gander plan.md --watch`) when the flag is not set.
`debounce_ms`	`150`	Coalesce file-change events before re-rendering.
`port`	`0`	HTTP port for the local watch server. `0` lets the OS pick.
`api_url`	`https://gander.md`	API origin for signup, share, list, remove, invite, manage.
`email`	(empty)	Address registered with gander.md.
`api_token`	(empty)	Bearer token. Written by `gander signup` and `gander auth`. Treat as a password.
`shares`	`{}`	Map of local absolute paths to short IDs. Updated by `gander share` and `gander watch`.
`doc_visibility`	omit (server `anyone`)	Default visibility for a new share only. `anyone`, `private`, or `hidden`.
`comment_access`	omit (server `private`)	Default commenting for a new share only. `anyone`, `private`, or `disabled`.

Defaults for new shares

doc_visibility and comment_access apply on first create (gander share / gander watch of a path not yet in shares). They do not apply on a later upload of the same file.

Flags always win for that run. The dashboard still wins on an existing share. Re-share or gander watch without flags does not reset policy from this file.

# config has "doc_visibility": "private"
gander share plan.md                      # first create: private
gander share plan.md --visibility=anyone  # this run: anyone
gander watch plan.md                      # later save: content only, policy unchanged

Anyone-commenting requires anyone-visibility. "comment_access": "anyone" with private or hidden visibility is rejected. Details: Visibility.

Flags override config

CLI flags override config for a single run. They do not write those values back into this file.

gander plan.md --watch=false
gander share plan.md --private

Sibling files

These live next to config.json and are not this file:

Path	Job
`watches.json`	Local (and hosted) watch list for the runner. Mode 0600.
`runner.sock`	Unix socket the CLI uses to talk to the daemon. Mode 0600.
`runner.log` / `runner.err`	Runner logs (`gander logs`).
`skill/`	Agent skill install. See Skill.

gander uninstall --keep-config leaves ~/.gander in place. See Install.

Do not commit it

Keep ~/.gander/config.json off git. Do not paste api_token into tickets, chat, or a PR. If it leaked, rotate from the dashboard, then gander auth on each machine.