Skip to content

Add --home CLI flag and TOML backslash error hints for Windows#87

Merged
wesm merged 5 commits intomainfrom
windows-config-path-cli
Feb 6, 2026
Merged

Add --home CLI flag and TOML backslash error hints for Windows#87
wesm merged 5 commits intomainfrom
windows-config-path-cli

Conversation

@wesm
Copy link
Owner

@wesm wesm commented Feb 5, 2026

Summary

Closes #86

Windows users writing native backslash paths in config.toml (e.g. data_dir = "C:\Users\wesmc\msgvault") get cryptic TOML parse errors because backslashes are escape characters in TOML double-quoted strings. This PR addresses the problem from two angles:

1. --home CLI flag — Sets the home directory directly from the command line, equivalent to MSGVAULT_HOME. Config, database, tokens, attachments, and analytics all live under this directory. If a config.toml exists there, it's loaded.

msgvault.exe --home "C:\Users\wesmc\msgvault" sync-full [email protected]

2. Improved TOML error messages — When config.toml contains backslash paths that fail to parse, the error now includes a hint:

hint: Windows paths in TOML must use forward slashes (C:/Games/msgvault)
or single quotes ('C:\Games\msgvault').

This catches both \G-style "invalid escape" errors and \U-style "expected hexadecimal digits" errors.

Changes

  • cmd/msgvault/cmd/root.go — Add --home persistent flag, pass it into config.Load()
  • internal/config/config.goLoad() accepts a homeDir parameter that overrides DefaultHome() before determining config path; detect backslash-related TOML errors and wrap with hint
  • internal/config/config_test.go — Tests for --home (sets HomeDir/DataDir, reads config.toml from home dir, expands tilde), tests for backslash hints (\G and \U variants)
  • CLAUDE.md — Add General Workflow, Go Development, and Git Workflow guidelines

Test plan

  • make test passes
  • make lint passes
  • Manual: msgvault.exe --home "C:\Users\wesmc\testing" init-db uses the override directory
  • Manual: config.toml with data_dir = "C:\Games\msgvault" shows the hint
  • Manual: config.toml with data_dir = "C:\Users\wesmc\data" shows the hint (\U variant)
  • Manual: config.toml in --home directory is loaded (e.g. rate_limit_qps applies)

🤖 Generated with Claude Code

Windows users writing native backslash paths in config.toml get cryptic
"invalid escape" errors from the TOML parser. This adds a helpful hint
pointing to forward slashes, single quotes, or the new --home flag.

The --home flag sets the home directory directly from the CLI, bypassing
TOML config entirely — the most common need for Windows users who just
want a custom data location.

Closes #86

Co-Authored-By: Claude Opus 4.6 <[email protected]>
wesm and others added 4 commits February 5, 2026 17:00
Previously --home was applied after config loading, so a config.toml
placed in the --home directory was silently ignored. Now --home is
passed into Load() so it behaves like MSGVAULT_HOME: config.toml is
loaded from that directory, and HomeDir/DataDir default to it.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
Paths like C:\Users\... trigger a different TOML error ("expected eight
hexadecimal digits after '\U'") than C:\Games\... ("invalid escape").
Match both patterns so the hint always appears for backslash paths.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
Since --home now loads config.toml from that directory, it doesn't
help avoid TOML parsing errors. Keep the hint focused on the fix:
use forward slashes or single quotes.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
@wesm wesm changed the title Add --home flag and TOML backslash error hint for Windows Add --home CLI flag and TOML backslash error hints for Windows Feb 6, 2026
@wesm wesm merged commit cf43372 into main Feb 6, 2026
3 checks passed
wesm added a commit to robelkin/msgvault that referenced this pull request Feb 7, 2026
## Summary

Closes wesm#86

Windows users writing native backslash paths in `config.toml` (e.g.
`data_dir = "C:\Users\wesmc\msgvault"`) get cryptic TOML parse errors
because backslashes are escape characters in TOML double-quoted strings.
This PR addresses the problem from two angles:

**1. `--home` CLI flag** — Sets the home directory directly from the
command line, equivalent to `MSGVAULT_HOME`. Config, database, tokens,
attachments, and analytics all live under this directory. If a
`config.toml` exists there, it's loaded.

```
msgvault.exe --home "C:\Users\wesmc\msgvault" sync-full [email protected]
```

**2. Improved TOML error messages** — When `config.toml` contains
backslash paths that fail to parse, the error now includes a hint:

```
hint: Windows paths in TOML must use forward slashes (C:/Games/msgvault)
or single quotes ('C:\Games\msgvault').
```

This catches both `\G`-style "invalid escape" errors and `\U`-style
"expected hexadecimal digits" errors.

## Changes

- `cmd/msgvault/cmd/root.go` — Add `--home` persistent flag, pass it
into `config.Load()`
- `internal/config/config.go` — `Load()` accepts a `homeDir` parameter
that overrides `DefaultHome()` before determining config path; detect
backslash-related TOML errors and wrap with hint
- `internal/config/config_test.go` — Tests for `--home` (sets
HomeDir/DataDir, reads config.toml from home dir, expands tilde), tests
for backslash hints (`\G` and `\U` variants)
- `CLAUDE.md` — Add General Workflow, Go Development, and Git Workflow
guidelines

## Test plan

- [x] `make test` passes
- [x] `make lint` passes
- [x] Manual: `msgvault.exe --home "C:\Users\wesmc\testing" init-db`
uses the override directory
- [x] Manual: config.toml with `data_dir = "C:\Games\msgvault"` shows
the hint
- [x] Manual: config.toml with `data_dir = "C:\Users\wesmc\data"` shows
the hint (`\U` variant)
- [x] Manual: config.toml in `--home` directory is loaded (e.g.
`rate_limit_qps` applies)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Reopen of #39 - specifying --config does not appear to work from Windows cmdline

1 participant