docs: document that config files are no longer loaded from the working directory

[pbeckham]

Follow-up to kosli-dev/server#6778, documenting the CLI change made in kosli-dev/cli#1152.

Corrects the two pages that told readers a kosli.yml in their working directory would be picked up automatically. Both now describe the $HOME/.kosli.yml default and carry a warning naming the migration.

Why

Until v2.39.2 the CLI loaded kosli.<yaml|yml|toml|json|env> from the directory it ran in, with no --config-file. A repository could therefore set host for any command run against it with a real API token, sending Authorization: Bearer <token> to an attacker-chosen host. That is fixed in v2.40.0, but the docs still described the old behaviour, so a reader following them writes a config file the CLI now ignores and gets no explanation for why their settings stopped applying.

What changed

faq/faq.md and getting_started/install.md. Each replaces the implicit-default claim with the $HOME/.kosli.yml default and how to name any other file, then adds a Warning covering what changed, why, and the migration: pass --config-file kosli.yml or set KOSLI_CONFIG_FILE. No navigation or structural change.

The generated client_reference/ pages already carry the new --config-file help text, from the v2.40.1 reference regeneration on main.

Verification

Doc Review and PR Quality Checks gate this PR, and both changed files are Markdown so the doc-quality review runs on them. The version claims hold against the CLI releases: v2.39.2 (2026-09-01) is the last release with the old behaviour, v2.40.0 (2026-09-11) the first without it.

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
kosli	🟢 Ready	View Preview	Sep 15, 2026, 8:49 AM

[claude]

Claude finished @pbeckham's task in 2m 29s —— View job

---

Doc review — PR #416

• Read changed files at branch head
• Check the new snippet against repo conventions
• Cross-check claims against generated client_reference/ pages
• Sweep for other pages describing the working-directory config behaviour
• Post findings

Both findings from the previous review are fixed at ad9cbc2, and the extension list now matches the "JSON, YAML, or TOML" prose on both pages. I verified the new claims against the current reference pages rather than the diff:

Claim	Checked against
--config-file defaults to $HOME/.kosli.yml	kosli_config.md:44 — (default "$HOME/.kosli.yml"), "never implicitly from the current directory"
KOSLI_CONFIG_FILE as an alternative	kosli_config.md:17
--quiet suppresses the new warning	kosli.md:28 — "Suppress non-critical warning messages"
v2.39.2 last / v2.40.0 first	changelog/index.mdx — v2.40.0 (Sep 11), v2.39.2 (Sep 1)

Extracting the warning to snippets/ is the right call: it is used by 2 pages, which clears the bar in CLAUDE.md, importing a snippet into a .md page is the existing pattern (cli-beta-notice.mdx), and snippets/ is excluded from the navigation audit (audit_navigation.py:36), so core rule 2 does not apply to the new file.

Nothing here blocks the merge. Three things worth a look, in order:

1. Verify extension inference survived v2.40.0 — the example sits two lines above the new text

Both edited pages tell readers they can drop the extension, on lines the PR leaves untouched:

• faq/faq.md:52-56 — "you can skip the file extension … kosli list environments --config-file kosli-conf"
• getting_started/install.md:196-201 — same example with =

kosli-conf is a relative, extension-less value, so resolving it means picking a directory (the working directory) and trying extensions. That is explicit naming rather than implicit discovery, so it plausibly still works — but it is the one adjacent claim this PR did not check, and it is the claim most likely to have been narrowed by the same upstream change. The flag help now reads "The Kosli config file path", with no mention of extension inference, which does not settle it either way. Worth a single run of kosli list environments --config-file kosli-conf against v2.40.x before merge; if inference is gone, both pages carry an example that now fails.

2. The changelog entry announcing the break has no migration path

changelog/index.mdx:41 is where most readers meet this change, and it tells them what broke without telling them what to do:

It now only reads config from the standard locations. Before upgrading, check for kosli.yml files at the root of any repository where the CLI runs.

Two gaps against the snippet this PR just wrote. It names only kosli.yml, so a reader with kosli.toml or kosli.json scans for the wrong filename — the same class of miss as the yml omission already fixed here. And it offers no --config-file / KOSLI_CONFIG_FILE migration, which is the entire point of the new warning. A clause pointing at /faq/faq#what-is-the---config-file-flag would close the sweep. Fix this →

3. The API-token page omits the default config file

administration/authentication/api_authentication_methods.md:28 lists the ways to give a kosli command a token, and the config-file bullet is "A config file passed via --config-file". Pre-existing and not wrong, but this PR promotes $HOME/.kosli.yml to the config file, and that is exactly the path a reader who ran kosli config is using — with no --config-file anywhere. Adding it to that list keeps the three token pages telling one story. Low priority; fine as a follow-up.

_{vale-spellcheck covers spelling, so this review does not.}
· 6778-no-implicit-cwd-config

[pbeckham]

Triage of the four findings. 1, 2 and 4 are fixed in ad9cbc2; 3 is not a problem, with evidence below.

1. Missing yml, stray env — fixed, replied inline. The list was not just missing yml: the old implicit search used viper.SupportedExts, twelve extensions rather than four. Now kosli.<yaml|yml|json|toml>, matching the formats the surrounding pages document, with env dropped.

2. kosli.yml already means a flow template — fixed. Confirmed against getting_started/attestations.md:121 and tutorials/try_kosli_locally.mdx:53-70. The advice now names the reader's own file rather than a literal, which is also what the CLI does: its warning interpolates the filename it actually found (cmd/kosli/root.go:484-486).

3. Does --config-file still accept a bare basename? — no change needed, the examples are still correct. cmd/kosli/root.go:668-680 splits the value, strips the extension, and calls SetConfigName plus AddConfigPath("."), so --config-file kosli-conf still resolves ./kosli-conf.{yaml,yml,json,toml,...} exactly as before. What v2.40.0 removed is only the implicit search when no file is named. Extensionless resolution for an explicitly named file survives, so faq/faq.md:51-54 and getting_started/install.md:196-200 are accurate as they stand.

4. Duplicated verbatim across two pages — fixed. Extracted to snippets/cli-working-dir-config-notice.mdx, following the cli-beta-notice import convention. Findings 1 and 2 were then each applied once instead of twice.

On the warning you could not verify from this repo: it is real. cmd/kosli/root.go:484 and :486 emit it, in two variants depending on whether the command declares its own --config-file. Your hunch about --quiet was right: internal/logger/logger.go:56-58 returns early from Warn when QuietEnabled. Both facts are now in the snippet, along with the kosli config route to moving the settings permanently.