Merge pull request #126 from nshepperd/xdg-config-path

Xdg config path

Author: Microck

CHANGELOG.md

@@ -7,6 +7,12 @@ Before `1.0.0`, breaking changes may still ship in minor releases.
 
 ## [Unreleased]
 
+### Changed
+
+- The configuration file now lives at a fixed XDG location instead of a working-directory-relative `./.kagi.toml`. It is resolved in this order: `$KAGI_CONFIG` (an explicit full file path), then `$XDG_CONFIG_HOME/kagi-cli/config.toml`, then `~/.config/kagi-cli/config.toml`. The file is still created with `0600` permissions, and the `KAGI_API_KEY`/`KAGI_API_TOKEN`/`KAGI_SESSION_TOKEN` environment variables continue to take precedence over it.
+
+  **Breaking:** credentials previously saved in a working-directory-relative `./.kagi.toml` are no longer read. Run `kagi auth set` (or `kagi auth`) once to re-save them at the new location, or point `KAGI_CONFIG` at your existing file.
+
 ## [0.10.0]
 
 ### Added

CONTRIBUTING.md

@@ -78,7 +78,7 @@ Pull requests will not be rejected solely because AI was used. They may be rejec
 
 ## Auth and Test Safety
 
-- Do not commit `.env`, `.kagi.toml`, session tokens, or API tokens
+- Do not commit `.env`, credential files, session tokens, or API tokens
 - Prefer unit tests and parser fixtures over live authenticated tests
 - If a change requires live verification, document the exact manual steps in the pull request
 

README.md

@@ -18,7 +18,7 @@
 
 `kagi` is a terminal CLI for Kagi that gives you command-line access to search, quick answers, ask-page, assistant, translate, summarization, public feeds through `news` and `smallweb`, paid API commands like `fastgpt` and `enrich`, and account-level settings like lenses, custom assistants, custom bangs, and redirect rules. it is built for people who want one command surface for interactive use, shell workflows, and structured JSON output.
 
-the main setup path is `kagi auth`. on a real terminal it opens a guided setup flow where you choose `Session Link`, `API Key`, or `Legacy API Token`, get the official instructions inline, paste the credential, save it to `./.kagi.toml`, and validate it immediately. if you also use Kagi's paid API, the same wizard can add that too.
+the main setup path is `kagi auth`. on a real terminal it opens a guided setup flow where you choose `Session Link`, `API Key`, or `Legacy API Token`, get the official instructions inline, paste the credential, save it to `~/.config/kagi-cli/config.toml`, and validate it immediately. if you also use Kagi's paid API, the same wizard can add that too.
 
 [documentation](https://kagi.micr.dev) | [npm](https://www.npmjs.com/package/kagi-cli) | [mcp](https://github.com/Microck/kagi-mcp)
 
@@ -81,7 +81,7 @@ the wizard is the default setup path. it guides you through:
 - `Session Link` from `https://kagi.com/settings/user_details`
 - `API Key` from `https://kagi.com/api/keys`
 - `Legacy API Token` from `https://kagi.com/settings/api`
-- saving into `./.kagi.toml`
+- saving into `~/.config/kagi-cli/config.toml`
 - immediate validation
 
 non-interactive alternative:
@@ -153,8 +153,8 @@ notes:
 
 - `kagi auth` is interactive on TTYs and becomes the default onboarding path
 - `kagi auth set --session-token` accepts either the raw token or the full session-link URL
-- `kagi --profile work ...` reads `[profiles.work.auth]` from `.kagi.toml`
-- environment variables override `.kagi.toml`
+- `kagi --profile work ...` reads `[profiles.work.auth]` from the config file (`~/.config/kagi-cli/config.toml`)
+- environment variables override `~/.config/kagi-cli/config.toml`
 - base `kagi search` defaults to the session-token path when both credentials are present
 - set `[auth] preferred_auth = "api"` if you want base search to prefer the API path instead
 - API-first base search falls back to the session-token path when the API key is rejected, including quota and rate-limit failures

docs/SKILL.md

@@ -49,7 +49,7 @@ kagi auth
 Opens a guided TTY wizard that walks through:
 - Choosing Session Link, API Key, or Legacy API Token
 - Pasting credentials
-- Saving to `./.kagi.toml`
+- Saving to `~/.config/kagi-cli/config.toml`
 - Immediate validation
 
 ### Non-Interactive Setup
@@ -77,7 +77,7 @@ export KAGI_API_TOKEN='...'
 | `KAGI_API_TOKEN` | summarize, fastgpt, enrich web, enrich news |
 | none | news, smallweb, auth status, --help |
 
-Environment variables override `./.kagi.toml`. When a session token and API key are both present, base `kagi search` defaults to the session token; set `[auth] preferred_auth = "api"` in config to prefer the API key.
+Environment variables override `~/.config/kagi-cli/config.toml`. When a session token and API key are both present, base `kagi search` defaults to the session token; set `[auth] preferred_auth = "api"` in config to prefer the API key.
 
 ## Commands
 

docs/commands/auth.mdx

@@ -5,7 +5,7 @@ description: "Reference for the kagi auth wizard and non-interactive credential
 
 # `kagi auth`
 
-`kagi auth` is the main onboarding path for this CLI. On a real terminal, it launches an interactive setup wizard that lets you choose `Session Link`, `API Key`, or `Legacy API Token`, shows the official Kagi settings page for that credential, accepts a paste, saves into `./.kagi.toml`, and validates the selected credential immediately.
+`kagi auth` is the main onboarding path for this CLI. On a real terminal, it launches an interactive setup wizard that lets you choose `Session Link`, `API Key`, or `Legacy API Token`, shows the official Kagi settings page for that credential, accepts a paste, saves into `~/.config/kagi-cli/config.toml`, and validates the selected credential immediately.
 
 ![Auth command demo](/images/demos/auth.gif)
 
@@ -34,7 +34,7 @@ The wizard flow is:
 4. accepts the pasted value
 5. asks before overwriting an existing config value of the same type
 6. validates the selected credential
-7. saves to `./.kagi.toml`
+7. saves to `~/.config/kagi-cli/config.toml`
 8. warns if an environment variable will still override what you saved
 
 ### Session Link Path
@@ -109,7 +109,7 @@ preferred auth for base search: session
 api key: not configured
 legacy api token: not configured
 session token: configured via config
-config path: .kagi.toml
+config path: ~/.config/kagi-cli/config.toml
 precedence: env > selected profile config > default config; base search defaults to session unless preferred_auth = "api"; lens search requires session token
 ```
 
@@ -155,7 +155,7 @@ Options:
 
 Behavior:
 
-- creates `./.kagi.toml` when needed
+- creates `~/.config/kagi-cli/config.toml` when needed
 - preserves the other credential if you only set one
 - normalizes full Session Link URLs into the raw token value
 - writes the config file with restrictive permissions on Unix
@@ -166,9 +166,9 @@ The CLI resolves credentials in this order:
 
 1. `KAGI_API_KEY` / `KAGI_API_TOKEN` / `KAGI_SESSION_TOKEN`
 2. selected profile config, such as `[profiles.work.auth]`
-3. default `./.kagi.toml` `[auth]`
+3. default `~/.config/kagi-cli/config.toml` `[auth]`
 
-Environment variables override the config file. Use `--profile <NAME>` to select a named profile from `.kagi.toml`:
+The config file is resolved from `$KAGI_CONFIG` (an explicit full path), then `$XDG_CONFIG_HOME/kagi-cli/config.toml`, then `~/.config/kagi-cli/config.toml`. Environment variables override the config file. Use `--profile <NAME>` to select a named profile from the config file (`~/.config/kagi-cli/config.toml`):
 
 ```toml
 [profiles.work.auth]
@@ -220,7 +220,7 @@ kagi search --format pretty "what changed in rust 1.86?"
 ## Security Notes
 
 - `auth status` and `auth check` never print the secret values
-- `./.kagi.toml` is local plaintext config, so keep it out of version control
+- `~/.config/kagi-cli/config.toml` is local plaintext config, so keep it out of version control
 - on Unix, the CLI writes restrictive file permissions when saving the config
 - environment variables still override config and may be preferable in CI/CD
 

docs/guides/advanced-usage.mdx

@@ -691,8 +691,9 @@ chmod 600 "$TEMP_FILE"
 #!/bin/bash
 # Prevent accidental token commits
 
-# Add to .gitignore
-echo ".kagi.toml" >> .gitignore
+# The config file now lives at ~/.config/kagi-cli/config.toml, outside your
+# repositories, so it no longer needs to be added to .gitignore.
+# Still guard against other accidental secret commits:
 echo ".env" >> .gitignore
 echo "*token*" >> .gitignore
 

docs/guides/authentication.mdx

@@ -15,7 +15,7 @@ On a real terminal, the default setup path is:
 kagi auth
 ```
 
-The wizard lets you choose `Session Link`, `API Key`, or `Legacy API Token`, points you to the correct Kagi settings page, accepts a paste, saves into `./.kagi.toml`, and validates the selected credential immediately.
+The wizard lets you choose `Session Link`, `API Key`, or `Legacy API Token`, points you to the correct Kagi settings page, accepts a paste, saves into `~/.config/kagi-cli/config.toml`, and validates the selected credential immediately.
 
 Use `kagi auth set ...` only when you want a non-interactive or scripted flow.
 
@@ -219,10 +219,14 @@ env:
 
 ### Method 2: Configuration File
 
-The `.kagi.toml` file provides persistent configuration:
+The config file provides persistent configuration:
 
 **Location:**
-- `./.kagi.toml` in the current working directory
+- `~/.config/kagi-cli/config.toml`
+
+The config file is resolved from `$KAGI_CONFIG` (an explicit full path), then `$XDG_CONFIG_HOME/kagi-cli/config.toml`, then `~/.config/kagi-cli/config.toml`.
+
+> **Migration note:** A pre-existing `./.kagi.toml` in your working directory is no longer read. Re-run `kagi auth set` (or `kagi auth`) once to re-save your credentials at the new location, or set `KAGI_CONFIG` to the old file path.
 
 **File format:**
 
@@ -260,14 +264,15 @@ kagi auth set --session-token 'https://kagi.com/search?token=SESSION_TOKEN' --ap
 
 ```bash
 # macOS/Linux
-cat > ./.kagi.toml << 'EOF'
+mkdir -p ~/.config/kagi-cli
+cat > ~/.config/kagi-cli/config.toml << 'EOF'
 [auth]
 api_token = "your_api_token"
 session_token = "https://kagi.com/search?token=your_session_token"
 EOF
 
 # Set secure permissions
-chmod 600 ./.kagi.toml
+chmod 600 ~/.config/kagi-cli/config.toml
 ```
 
 ```powershell
@@ -277,7 +282,8 @@ $content = @"
 api_token = `"your_api_token`"
 session_token = `"https://kagi.com/search?token=your_session_token`"
 "@
-$content | Out-File -FilePath ".kagi.toml" -Encoding utf8
+New-Item -ItemType Directory -Force -Path "$HOME\.config\kagi-cli" | Out-Null
+$content | Out-File -FilePath "$HOME\.config\kagi-cli\config.toml" -Encoding utf8
 ```
 
 ### Precedence Rules
@@ -286,10 +292,12 @@ Credentials are resolved in this order (first match wins):
 
 ```
 1. Environment Variables (KAGI_API_KEY, KAGI_API_TOKEN, KAGI_SESSION_TOKEN)
-2. Configuration File (`./.kagi.toml`)
+2. Configuration File (`~/.config/kagi-cli/config.toml`)
 3. Missing (error for commands requiring auth)
 ```
 
+The config file is resolved from `$KAGI_CONFIG` (an explicit full path), then `$XDG_CONFIG_HOME/kagi-cli/config.toml`, then `~/.config/kagi-cli/config.toml`.
+
 This means:
 - Environment variables override config file values
 - You can temporarily test different tokens via env vars
@@ -300,7 +308,7 @@ This means:
 
 ```bash
 # Config file has default session token
-cat ./.kagi.toml
+cat ~/.config/kagi-cli/config.toml
 # [auth]
 # session_token = "https://kagi.com/search?token=DEFAULT_TOKEN"
 
@@ -335,7 +343,7 @@ selected: none
 api key: not configured
 legacy api token: not configured
 session token: not configured
-config path: .kagi.toml
+config path: ~/.config/kagi-cli/config.toml
 ```
 
 Session token only:
@@ -344,7 +352,7 @@ selected: session-token (config)
 api key: not configured
 legacy api token: not configured
 session token: configured via config
-config path: .kagi.toml
+config path: ~/.config/kagi-cli/config.toml
 ```
 
 API key and session token:
@@ -353,7 +361,7 @@ selected: api-key (env)
 api key: configured via env
 legacy api token: not configured
 session token: configured via config
-config path: .kagi.toml
+config path: ~/.config/kagi-cli/config.toml
 ```
 
 ### Validating Credentials
@@ -497,7 +505,7 @@ kagi search "test"
 **Scenario 2: API-first mode works**
 ```bash
 export KAGI_API_KEY='valid_key'
-# .kagi.toml contains: [auth] preferred_auth = "api"
+# ~/.config/kagi-cli/config.toml contains: [auth] preferred_auth = "api"
 kagi search "test"
 # Uses Search API, returns results
 ```
@@ -506,7 +514,7 @@ kagi search "test"
 ```bash
 export KAGI_API_KEY='valid_key'
 export KAGI_SESSION_TOKEN='also_valid'
-# .kagi.toml contains: [auth] preferred_auth = "api"
+# ~/.config/kagi-cli/config.toml contains: [auth] preferred_auth = "api"
 kagi search "test"
 # Tries Search API and gets auth error
 # Falls back to session token path
@@ -527,7 +535,7 @@ kagi search "test"
 
 **DO:**
 - ✅ Use `kagi auth` for local setup so the CLI validates the credential as you save it
-- ✅ Store tokens in `./.kagi.toml` with 600 permissions
+- ✅ Store tokens in `~/.config/kagi-cli/config.toml` with 600 permissions
 - ✅ Use environment variables in CI/CD secrets
 - ✅ Use secret managers (1Password, Vault, etc.)
 - ✅ Rotate tokens periodically
@@ -742,7 +750,7 @@ $env:KAGI_SESSION_TOKEN = [System.Runtime.InteropServices.Marshal]::PtrToStringA
 
 ### Multiple Profiles
 
-For users with multiple Kagi accounts, prefer named profiles in one `.kagi.toml`:
+For users with multiple Kagi accounts, prefer named profiles in one config file (`~/.config/kagi-cli/config.toml`):
 
 ```toml
 [auth]

docs/guides/installation.mdx

@@ -547,7 +547,7 @@ To completely remove *kagi*:
 rm ~/.local/bin/kagi
 
 # Remove config
-rm ./.kagi.toml
+rm ~/.config/kagi-cli/config.toml
 
 # Remove from PATH (edit ~/.bashrc, ~/.zshrc, etc.)
 ```
@@ -559,7 +559,7 @@ rm ./.kagi.toml
 Remove-Item -Recurse -Force "$env:LOCALAPPDATA\kagi"
 
 # Remove config
-Remove-Item ".kagi.toml"
+Remove-Item "$HOME\.config\kagi-cli\config.toml"
 
 # Remove from PATH via System Properties
 ```

docs/guides/quickstart.mdx

@@ -90,7 +90,7 @@ selected: none
 api key: not configured
 legacy api token: not configured
 session token: not configured
-config path: .kagi.toml
+config path: ~/.config/kagi-cli/config.toml
 ```
 
 This is expected - we'll configure credentials next.
@@ -150,7 +150,7 @@ Save the token to a config file:
 kagi auth set --session-token 'https://kagi.com/search?token=YOUR_TOKEN_HERE'
 ```
 
-This creates `./.kagi.toml` with your token. The CLI accepts either:
+This creates `~/.config/kagi-cli/config.toml` with your token. The CLI accepts either:
 - The full Session Link URL (recommended)
 - Just the raw token value
 
@@ -167,7 +167,7 @@ selected: session-token (config)
 api key: not configured
 legacy api token: not configured
 session token: configured via config
-config path: .kagi.toml
+config path: ~/.config/kagi-cli/config.toml
 ```
 
 ### Testing Subscriber Features
@@ -306,9 +306,9 @@ See the [Auth Matrix](/reference/auth-matrix) for the complete command-to-token
 
 Now that you've tested everything, let's create a robust configuration.
 
-### The .kagi.toml File
+### The config file
 
-Kagi uses a TOML configuration file located at `./.kagi.toml`.
+Kagi uses a TOML configuration file located at `~/.config/kagi-cli/config.toml`.
 
 **Basic configuration:**
 
@@ -322,24 +322,25 @@ session_token = "your_session_token_here"
 
 ```bash
 # Create the file
-cat > ./.kagi.toml << 'EOF'
+mkdir -p ~/.config/kagi-cli
+cat > ~/.config/kagi-cli/config.toml << 'EOF'
 [auth]
 api_token = "your_api_token_here"
 session_token = "your_session_token_here"
 EOF
 
 # Set secure permissions
-chmod 600 ./.kagi.toml
+chmod 600 ~/.config/kagi-cli/config.toml
 ```
 
 ### Configuration Precedence
 
 Kagi resolves credentials in this order (first match wins):
 
 1. **Environment variables** (`KAGI_API_KEY`, `KAGI_API_TOKEN`, `KAGI_SESSION_TOKEN`)
-2. **Config file** (`./.kagi.toml`)
+2. **Config file** (`~/.config/kagi-cli/config.toml`)
 
-This means you can override file configuration with environment variables for specific workflows or CI/CD.
+The config file is resolved from `$KAGI_CONFIG` (an explicit full path), then `$XDG_CONFIG_HOME/kagi-cli/config.toml`, then `~/.config/kagi-cli/config.toml`. This means you can override file configuration with environment variables for specific workflows or CI/CD.
 
 ### Shell Profile Integration
 
@@ -379,7 +380,7 @@ $env:KAGI_API_TOKEN = 'your_api_token'
 
 ### Security Best Practices
 
-1. **File permissions**: Set `./.kagi.toml` to 600 (readable only by you)
+1. **File permissions**: Set `~/.config/kagi-cli/config.toml` to 600 (readable only by you)
 2. **Environment variables**: Don't commit these to version control
 3. **Token rotation**: Regenerate tokens periodically
 4. **Separate contexts**: Use different tokens for different environments (dev/staging/prod)

docs/guides/troubleshooting.mdx

@@ -179,7 +179,8 @@ kagi auth check
 kagi auth set --session-token 'https://kagi.com/search?token=YOUR_TOKEN'
 
 # Or manually
-cat > ./.kagi.toml << 'EOF'
+mkdir -p ~/.config/kagi-cli
+cat > ~/.config/kagi-cli/config.toml << 'EOF'
 [auth]
 session_token = "https://kagi.com/search?token=YOUR_TOKEN"
 EOF
@@ -789,7 +790,9 @@ kagi auth check
 
 ### Config File Location
 
-- Repo checkout: `./.kagi.toml`
+- Default: `~/.config/kagi-cli/config.toml`
+
+The config file is resolved from `$KAGI_CONFIG` (an explicit full path), then `$XDG_CONFIG_HOME/kagi-cli/config.toml`, then `~/.config/kagi-cli/config.toml`. A pre-existing `./.kagi.toml` is no longer read; re-run `kagi auth set` (or `kagi auth`) to re-save credentials at the new location, or set `KAGI_CONFIG` to the old file path.
 
 ### Shell Syntax