Skip to content

Document the config.toml format at a stable URL for the config template to link #224

Description

@benbaarber

#214 adds path config edit, which creates ~/.toolpath/config.toml on first use with a two-line template:

# Toolpath user configuration.
# https://toolpath.net/cli/

The link is the general CLI page because there is no reference documentation for the config file format itself. Someone landing there from the template has to dig through the share docs to learn that the file holds [[project]] rules with dir (subtree match, ~/-expandable, most specific wins) and remote (bare owner/name or a canonical Pathbase repo web URL that also carries the server).

We should write a proper config file reference and point the template comment at it instead. Candidate homes:

  • a dedicated page on toolpath.net (e.g. toolpath.net/cli/config/) — probably the best fit; the template link should be short and stable, and the site is where the rest of the user-facing CLI docs live
  • the path-cli docs on docs.rs — less suitable, since path-cli is an app rather than a library and its rustdoc is not a user-facing surface
  • a section anchor on the existing CLI page — cheapest, but anchors are less stable than a dedicated URL

The reference should cover: file location and $TOOLPATH_CONFIG_DIR override, the [[project]] rule shape and matching semantics, the remote value grammar, precedence against --repo/--url/--anon, and the forward-compatibility rule that unknown keys are ignored. It should grow alongside path config as new operations and settings land (get/set, per-project settings beyond remote).

Once the page exists, update TEMPLATE in crates/path-cli/src/cmd_config.rs to link to it.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions