klaudiak 2.1.92 → 2.1.93

package/README.md

@@ -2,26 +2,94 @@
 
 Klaudia Kode is a coding agent wrapper CLI that can run against many LLM providers through a local OpenRouter-compatible proxy.
 
+Use the CLI as `klaudiak`.
+
 ## Quick Start
 
-1. Start the proxy in one terminal:
+1. Install and verify:
 
 ```bash
-npx klaudiak proxy deepseek/deepseek-chat-v3-0324 key sk-or-v1-... --port=10000
+npm i -g klaudiak
+klaudiak --help
 ```
 
-2. Start the coding agent in another terminal:
+2. Start the proxy in one terminal:
 
 ```bash
-npx klaudiak --port=10000
+klaudiak proxy deepseek/deepseek-chat-v3-0324 key sk-or-v1-... --port=10000
+```
+
+3. Start the coding agent in another terminal:
+
+```bash
+klaudiak --port=10000
 ```
 
 If your proxy runs on default port 9090, you can simply run:
 
 ```bash
-npx klaudiak
+klaudiak
+```
+
+## Laziest Setup (Two Commands)
+
+If you want daily usage to be exactly:
+
+```bash
+klaudiak proxy
+klaudiak
+```
+
+set the `default` profile once:
+
+```bash
+klaudiak defaults set default type proxy
+klaudiak defaults set default openrouterModel deepseek/deepseek-chat-v3-0324
+klaudiak defaults set default openrouterApiKey sk-or-v1-...
+klaudiak defaults set default proxyPort 9090
+klaudiak defaults set default anthropicBaseUrl http://localhost:9090
+```
+
+Then every day:
+
+1. Terminal A: `klaudiak proxy`
+2. Terminal B: `klaudiak`
+
+If you choose another port, keep `proxyPort` and `anthropicBaseUrl` aligned to the same value.
+
+Screenshots of this exact lazy flow:
+
+### `klaudiak proxy`
+
+![klaudiak proxy screenshot](.docs/screenshots/openrouter-proxy.png)
+
+### `klaudiak`
+
+![klaudiak screenshot](.docs/screenshots/klaudiak.png)
+
+## Recommended Daily Workflow
+
+For repeat usage, set profile defaults once and then launch with short commands.
+
+```bash
+# Create a dedicated profile
+klaudiak defaults create deepseek
+
+# Save proxy settings to that profile
+klaudiak defaults set deepseek type proxy
+klaudiak defaults set deepseek openrouterModel deepseek/deepseek-chat-v3-0324
+klaudiak defaults set deepseek openrouterApiKey sk-or-v1-...
+klaudiak defaults set deepseek proxyPort 10000
+
+# Terminal A: run proxy from profile (no model/key arguments needed)
+klaudiak proxy --profile=deepseek
+
+# Terminal B: run agent against the same proxy port
+klaudiak --profile=deepseek --port=10000
 ```
 
+This gives you predictable, reusable setup with minimal typing.
+
 ## Command Reference
 
 ### Start agent
@@ -39,11 +107,17 @@ klaudiak --port <port>
 - Any additional args are forwarded to `cli.js` (for example `-p "..."`).
 - `--profile=<name>` loads settings from `~/.klaudiak` profile `<name>`.
 - `--defaults=<name>` is an alias of `--profile=<name>`.
-- `--port=<port>` sets `ANTHROPIC_BASE_URL=http://localhost:<port>` for this run when not already set.
+- `--port=<port>` sets `ANTHROPIC_BASE_URL=http://localhost:<port>` for this run (overrides profile/env base URL).
 - `--port <port>` is also supported.
 
 When no profile flag is passed, Klaudiak always uses the `default` profile.
 
+Behavior details that matter:
+
+- Agent arguments are forwarded to `cli.js` after removing `--profile/--defaults` and `--port`.
+- If running against `localhost`/`127.0.0.1`, Klaudiak auto-enables `--bare` unless you already passed it.
+- If running against `localhost` and no Anthropic auth env vars are set, Klaudiak injects local placeholder auth values to avoid OAuth/login fallback.
+
 ### Start proxy
 
 ```bash
@@ -98,6 +172,22 @@ Supported fields:
 - `openrouterModel`
 - `openrouterApiKey`
 
+Notes:
+
+- Profile names must match `^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$`.
+- `default` profile always exists and cannot be deleted.
+- `klaudiak` auto-creates `~/.klaudiak` on first run.
+
+## Configuration Precedence
+
+For agent startup, effective values follow this order:
+
+1. Existing environment variables (for example `ANTHROPIC_API_KEY`, `ANTHROPIC_MODEL`, `ANTHROPIC_BASE_URL`)
+2. Selected profile values from `~/.klaudiak`
+3. CLI `--port` (overrides base URL to `http://localhost:<port>`)
+
+Practical rule: if you pass `--port`, that port wins for `ANTHROPIC_BASE_URL`.
+
 ## How It Works
 
 ```text
@@ -106,6 +196,13 @@ Klaudia Kode CLI --> local proxy (default :9090) --> OpenRouter/provider
 
 The agent speaks Anthropic-compatible protocol to the local proxy. The proxy translates and routes requests to the model/provider you selected.
 
+## Power Tips
+
+- Use profiles per provider/model combo so you can switch quickly with `--profile=<name>`.
+- Keep proxy and agent ports explicit when debugging: `klaudiak proxy ... --port=10000` and `klaudiak --port=10000`.
+- Use `klaudiak defaults show <name>` to confirm values before running.
+- Store secrets in profile only on trusted machines, and rotate keys periodically.
+
 ## Troubleshooting
 
 ### Proxy not running
@@ -131,12 +228,24 @@ Make sure:
 - API key starts with an OpenRouter key format such as `sk-or-v1-...`
 - Model string is valid for your provider account
 
+### Profile not found
+
+If you pass `--profile=<name>` and get a not-found error:
+
+1. Check available profiles with `klaudiak defaults list`.
+2. Create it with `klaudiak defaults create <name>`.
+3. Set required fields using `klaudiak defaults set ...`.
+
+### Invalid profile file JSON
+
+If `~/.klaudiak` contains invalid JSON, Klaudiak recreates it with defaults and prints a warning.
+
 ## Migration from Klaudiak
 
 - Package/command is now `klaudiak`
 - Legacy aliases are removed
 - Proxy command contract is standardized as:
-	- `klaudiak proxy <model> key <apiKey> --port=<port>`
+  - `klaudiak proxy <model> key <apiKey> --port=<port>`
 
 ## Requirements
 

package/klaudiak-help.md

@@ -1,14 +1,32 @@
 Klaudia Kode CLI
 
-install using 
-$ npm install -g klaudiak
-
 Usage:
-  klaudiak
-  klaudiak --port=<port>
-  klaudiak proxy <model> key <apiKey> --port=<port>
+  klaudiak [agentArgs...]
+  klaudiak [agentArgs...] --profile=<name>
+  klaudiak [agentArgs...] --defaults=<name>
+  klaudiak [agentArgs...] --port=<port>
+  klaudiak [agentArgs...] --port <port>
+  klaudiak defaults <list|show|create|delete|set|unset>
+  klaudiak proxy
+  klaudiak proxy --profile=<name>
+  klaudiak proxy <model> key <apiKey> [--port=<port>|--port <port>]
 
 Examples:
   klaudiak
+  klaudiak -p "say hi"
+  klaudiak --profile=gemini
+  klaudiak --defaults=gemini
   klaudiak --port=10000
+  klaudiak --port 10000
+  klaudiak proxy
+  klaudiak proxy --profile=default
+  klaudiak defaults create gemini
+  klaudiak defaults list
+  klaudiak defaults show gemini
+  klaudiak defaults set gemini type proxy
+  klaudiak defaults set gemini openrouterModel google/gemini-2.5-pro
+  klaudiak defaults set gemini openrouterApiKey sk-or-v1-...
+  klaudiak defaults unset gemini anthropicApiKey
+  klaudiak defaults delete gemini
   klaudiak proxy deepseek/deepseek-chat-v3-0324 key sk-or-v1-... --port=10000
+  klaudiak proxy deepseek/deepseek-chat-v3-0324 key sk-or-v1-... --port 10000

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klaudiak",
-  "version": "2.1.92",
+  "version": "2.1.93",
   "bin": {
     "klaudiak": "klaudiak.js"
   },