Skip to content

Clarify and document Cosine CLI settings precedence and storage locations #1

@seungpyoson

Description

@seungpyoson

Summary
The CLI exposes several config-related flags and cos init, but the effective settings precedence and all storage locations are not clearly discoverable from the repository README alone.

Observed behavior / evidence

  • cos --help documents these configuration surfaces:
    • repo config: cosine.toml / .cosine.toml
    • user config: ~/.cosine.toml
    • profile config via --profile, selecting cosine.<name>.toml or ~/.cosine.<name>.toml
    • MCP config path override via --mcp-config, defaulting to ~/.cosine/mcp.json
  • cos init --help says it initializes repo defaults (cosine.toml + repo context).
  • The public README currently focuses on install/authentication and does not explain settings precedence or where all config files live.

Why this matters
Users trying to apply persistent settings can see multiple flags and file names but still not know:

  1. exact precedence order across CLI flags, repo config, user config, and profile config
  2. whether cosine.toml and .cosine.toml are equivalent and how conflicts are resolved
  3. where auth/session state lives versus normal settings
  4. which settings belong in TOML versus ~/.cosine/mcp.json

Requested improvement
Please add explicit documentation covering:

  • all supported config files and directories
  • precedence order
  • profile resolution rules
  • which values are persisted where
  • example minimal configs for repo-local and user-global settings

This may already exist in docs, but if so it should also be easy to find from the repo README and/or CLI help output.

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