[MohamedBassem]

No description provided.

[coderabbitai]

Walkthrough

Adds a CLI auth flow with an interactive auth init, XDG-backed config loading/validation (Zod), async global option resolution in the CLI entry, a small build tweak and dependency addition, and updated CLI documentation describing config location and precedence.

Changes

CLI auth + config wiring

Layer / File(s)	Summary
Data Shape / Schema apps/cli/src/lib/config.ts, apps/cli/src/lib/globals.ts	Introduces CliConfig, CliConfigFile and zCliConfigFileSchema (Zod) plus DEFAULT_SERVER_ADDR; adds RawGlobalOptions (optional apiKey, serverAddr, json).
Core Implementation: config I/O & normalization apps/cli/src/lib/config.ts	Adds getConfigPath(), loadConfigFile() (reads & validates JSON), normalizeConfig() and loadConfig() to resolve runtime CliConfig.
Core Implementation: auth command apps/cli/src/commands/auth.ts	New authCmd with auth init subcommand: determines config path, merges normalized existing config, prompts for serverAddr/apiKey (TTY), supports CLI flags and --force, writes JSON with 0o600 permissions, sets exit code on error.
Wiring: CLI entry & runtime resolution apps/cli/src/index.ts	Imports authCmd; removes mandatory options; adds resolveGlobalOptions(opts) and isAuthCommand(); registers auth command; uses async preAction hook to resolve and set global options at runtime; switches to parseAsync and centralized top-level error handling.
Build & Dependencies apps/cli/package.json, apps/cli/vite.config.mts	Adds zod to devDependencies; marks node:os as external in Rollup/Vite config.
Documentation docs/docs/05-integrations/02-command-line.md	Adds auth command to docs, documents --json flag, config file location/example (serverAddr, apiKey), precedence rules, default server address, and karakeep auth init usage.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The pull request description is entirely missing; no content was provided by the author beyond the title.	Add a comprehensive description following the repository template, including: problem statement, solution overview, testing approach with checkboxes, and LLM usage disclosure.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: Add CLI auth config support' accurately summarizes the main change—introducing authentication configuration functionality to the CLI.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[greptile-apps]

Greptile Summary

This PR adds a persistent auth config file (~/.config/karakeep/config.json) for the CLI, an interactive karakeep auth init command to create/update it, and lazy global-option resolution via a preAction hook so the API key and server address are no longer mandatory CLI flags.

Confidence Score: 5/5

Safe to merge; only a P2 UX improvement found on top of issues already tracked in open review threads.

No new P0 or P1 issues were found. The previously flagged bugs (ignored subcommand flags, non-TTY hang) are tracked in open threads. The sole new finding is a P2 suggestion to wrap config-parse errors with the file path for better UX, which does not affect correctness.

apps/cli/src/commands/auth.ts — the open thread about --server-addr/--api-key being silently ignored when passed to auth init directly (vs. at the root level) is still unresolved.

Important Files Changed

Filename	Overview
apps/cli/src/commands/auth.ts	New auth init command for interactive/non-interactive config setup; previously flagged issue with --server-addr/--api-key subcommand flags being ignored (reads rootOpts instead of rawOpts) is unaddressed; non-TTY and overwrite guards are correctly implemented in this PR
apps/cli/src/lib/config.ts	New config file loading/parsing logic with Zod validation; errors from JSON.parse and Zod surface with unhelpful messages lacking file path context
apps/cli/src/index.ts	Global options are now resolved lazily in a preAction hook; isAuthCommand correctly walks up the parent chain to skip auth commands; --api-key/--server-addr are no longer mandatory at the CLI level
apps/cli/vite.config.mts	Added node:os to rollupOptions externals; ssr.noExternal regex already covers all node:* modules so new node:fs/promises and node:readline/promises imports are safe
apps/cli/src/lib/globals.ts	Added RawGlobalOptions interface to represent pre-resolution options before config file merge
docs/docs/05-integrations/02-command-line.md	Documentation updated to describe config file location, format, precedence rules, and auth init command; accurate and complete

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
apps/cli/src/lib/config.ts:35-43
**Unhelpful error messages for malformed config**

When the config file contains invalid JSON, `JSON.parse` throws a `SyntaxError` with no mention of the file path, and when the schema validation fails, a raw `ZodError` is surfaced. In the `preAction` hook these propagate as-is through `program.error(error.message)`, so users see cryptic messages with no hint that the config file is the source. Wrapping errors here would improve UX:

```ts
export function loadConfigFile(): CliConfigFile {
  const configPath = getConfigPath();
  if (!fs.existsSync(configPath)) {
    return {};
  }

  let parsed: unknown;
  try {
    parsed = JSON.parse(fs.readFileSync(configPath, "utf-8"));
  } catch {
    throw new Error(`Failed to parse config file at ${configPath}: invalid JSON`);
  }

  try {
    return zCliConfigFileSchema.parse(parsed);
  } catch {
    throw new Error(`Config file at ${configPath} has an invalid format`);
  }
}
```

_{Reviews (2): Last reviewed commit: "fix cli auth init review feedback" | Re-trigger Greptile}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b823fa8bcc

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Honor --force when config file is malformed

Loading the existing config before the overwrite path means karakeep auth init --force still fails if config.json contains invalid JSON or fails schema validation. In this flow, loadConfigFile() throws before the command can rewrite the file, so users cannot recover a broken config via the documented init command and must manually delete/edit it first.

Useful? React with 👍 / 👎.

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@apps/cli/src/commands/auth.ts`:
- Around line 54-59: The auth init handler currently builds opts from
command.parent?.parent?.opts() (rootOpts) which ignores subcommand flags; change
it to prefer rawOpts values when present: construct opts by taking serverAddr
and apiKey from rawOpts (falling back to rootOpts only if
rawOpts.serverAddr/rawOpts.apiKey are undefined), and keep force as
Boolean(rawOpts.force); update the code locations referencing rootOpts/opts in
the auth init handler so subcommand-provided --api-key/--server-addr are
honored.
- Around line 66-75: When a config file exists and opts.force is false, the code
currently creates a readline interface and calls rl.question which can block in
non-interactive contexts; add a TTY guard before creating readline: check
process.stdin.isTTY and if it's false, fail fast (e.g., throw or return with a
clear error message) instead of prompting. Update the branch around the
pathExists(configPath) && !opts.force check so that when !process.stdin.isTTY
you do not call readline.createInterface or rl.question, but instead handle the
non-interactive case (error/exit or skip) to avoid blocking.

In `@docs/docs/05-integrations/02-command-line.md`:
- Around line 131-133: Add a language identifier to the fenced code block
containing the command "karakeep auth init" so Markdown lint (MD040) is
satisfied; update the triple-backtick opening fence to include bash (or sh),
e.g. ```bash, leaving the command line content unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 2fb2f435-6d95-4c8d-88d9-45183472c4c9

📥 Commits

Reviewing files that changed from the base of the PR and between 6ccf1fe and b823fa8.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (7)

• apps/cli/package.json
• apps/cli/src/commands/auth.ts
• apps/cli/src/index.ts
• apps/cli/src/lib/config.ts
• apps/cli/src/lib/globals.ts
• apps/cli/vite.config.mts
• docs/docs/05-integrations/02-command-line.md

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

auth init ignores its own --api-key/--server-addr options.

The handler reads values from command.parent?.parent?.opts() instead of rawOpts, so subcommand-provided values can be dropped.

Proposed fix

-    const rootOpts = command.parent?.parent?.opts() as AuthInitOptions;
+    const rootOpts = command.parent?.parent?.opts() as
+      | Partial<AuthInitOptions>
+      | undefined;
     const opts = {
-      serverAddr: rootOpts.serverAddr,
-      apiKey: rootOpts.apiKey,
+      serverAddr: rawOpts.serverAddr ?? rootOpts?.serverAddr,
+      apiKey: rawOpts.apiKey ?? rootOpts?.apiKey,
       force: Boolean(rawOpts.force),
     };

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@apps/cli/src/commands/auth.ts` around lines 54 - 59, The auth init handler
currently builds opts from command.parent?.parent?.opts() (rootOpts) which
ignores subcommand flags; change it to prefer rawOpts values when present:
construct opts by taking serverAddr and apiKey from rawOpts (falling back to
rootOpts only if rawOpts.serverAddr/rawOpts.apiKey are undefined), and keep
force as Boolean(rawOpts.force); update the code locations referencing
rootOpts/opts in the auth init handler so subcommand-provided
--api-key/--server-addr are honored.

[coderabbitai]

♻️ Duplicate comments (1)

apps/cli/src/commands/auth.ts (1)

65-70: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

auth init still drops its own --api-key/--server-addr values.

At Line 65-70, opts is built only from rootOpts, so subcommand flags (rawOpts.apiKey / rawOpts.serverAddr) are ignored.

Suggested fix

-    const rootOpts = command.parent?.parent?.opts() as AuthInitOptions;
+    const rootOpts = command.parent?.parent?.opts() as
+      | Partial<AuthInitOptions>
+      | undefined;
     const opts = {
-      serverAddr: rootOpts.serverAddr,
-      apiKey: rootOpts.apiKey,
+      serverAddr: rawOpts.serverAddr ?? rootOpts?.serverAddr,
+      apiKey: rawOpts.apiKey ?? rootOpts?.apiKey,
       force: Boolean(rawOpts.force),
     };

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@apps/cli/src/commands/auth.ts` around lines 65 - 70, The opts object is
incorrectly sourced only from rootOpts, dropping subcommand flags; update
construction of opts (near command, rawOpts, rootOpts, AuthInitOptions) to
prefer rawOpts.apiKey and rawOpts.serverAddr when provided and fall back to
rootOpts otherwise, e.g. set serverAddr: rawOpts.serverAddr ??
rootOpts.serverAddr and apiKey: rawOpts.apiKey ?? rootOpts.apiKey, and keep
force: Boolean(rawOpts.force) so subcommand flags override parent defaults.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Duplicate comments:
In `@apps/cli/src/commands/auth.ts`:
- Around line 65-70: The opts object is incorrectly sourced only from rootOpts,
dropping subcommand flags; update construction of opts (near command, rawOpts,
rootOpts, AuthInitOptions) to prefer rawOpts.apiKey and rawOpts.serverAddr when
provided and fall back to rootOpts otherwise, e.g. set serverAddr:
rawOpts.serverAddr ?? rootOpts.serverAddr and apiKey: rawOpts.apiKey ??
rootOpts.apiKey, and keep force: Boolean(rawOpts.force) so subcommand flags
override parent defaults.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: b670729c-4d9a-4217-a171-c2922d5b700d

📥 Commits

Reviewing files that changed from the base of the PR and between b823fa8 and fbe44ae.

📒 Files selected for processing (3)

• apps/cli/src/commands/auth.ts
• apps/cli/src/index.ts
• docs/docs/05-integrations/02-command-line.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/docs/05-integrations/02-command-line.md

[MohamedBassem]

@codex review
@greptile review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fbe44ae9d8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Avoid unconditional config parsing in option resolution

resolveGlobalOptions always calls loadConfig() before checking CLI/env overrides, so any malformed ~/.config/karakeep/config.json causes every non-auth command to fail even when --api-key and --server-addr are explicitly provided. This is a regression from the documented precedence (CLI options should win) and can lock users out of the CLI until they manually repair the config file.

Useful? React with 👍 / 👎.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@apps/cli/src/index.ts`:
- Around line 16-28: The function resolveGlobalOptions calls loadConfig even
when an explicit apiKey is provided but serverAddr is missing; update
resolveGlobalOptions so that if opts.apiKey is present you do not call
loadConfig — return an object using opts.apiKey and opts.serverAddr ??
DEFAULT_SERVER_ADDR (and opts.json) directly; only call loadConfig when
opts.apiKey is not provided (or other values truly need backing from config).
Reference resolveGlobalOptions, loadConfig, DEFAULT_SERVER_ADDR, and
RawGlobalOptions to locate and change the logic.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 93feff3b-52f1-44e7-a05d-ff8c3f9405f8

📥 Commits

Reviewing files that changed from the base of the PR and between fbe44ae and eb3fa87.

📒 Files selected for processing (1)

• apps/cli/src/index.ts

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Avoid parsing config when an explicit API key is already sufficient.

This still calls loadConfig() whenever only serverAddr is missing. Because DEFAULT_SERVER_ADDR already exists, a broken config file will make karakeep --api-key ... <cmd> fail even though the CLI has enough information to proceed.

Suggested fix

 function resolveGlobalOptions(opts: RawGlobalOptions) {
-  if (opts.apiKey && opts.serverAddr) {
+  if (opts.apiKey) {
     return {
       apiKey: opts.apiKey,
-      serverAddr: opts.serverAddr,
+      serverAddr: opts.serverAddr ?? DEFAULT_SERVER_ADDR,
       json: opts.json,
     };
   }
 
   const config = loadConfig();
   const apiKey = opts.apiKey ?? config.apiKey;

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	function resolveGlobalOptions(opts: RawGlobalOptions) {
	if (opts.apiKey && opts.serverAddr) {
	return {
	apiKey: opts.apiKey,
	serverAddr: opts.serverAddr,
	json: opts.json,
	};
	}
	const config = loadConfig();
	const apiKey = opts.apiKey ?? config.apiKey;
	const serverAddr =
	opts.serverAddr ?? config.serverAddr ?? DEFAULT_SERVER_ADDR;
	function resolveGlobalOptions(opts: RawGlobalOptions) {
	if (opts.apiKey) {
	return {
	apiKey: opts.apiKey,
	serverAddr: opts.serverAddr ?? DEFAULT_SERVER_ADDR,
	json: opts.json,
	};
	}
	const config = loadConfig();
	const apiKey = opts.apiKey ?? config.apiKey;
	const serverAddr =
	opts.serverAddr ?? config.serverAddr ?? DEFAULT_SERVER_ADDR;

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/cli/src/index.ts` around lines 16 - 28, The function
resolveGlobalOptions calls loadConfig even when an explicit apiKey is provided
but serverAddr is missing; update resolveGlobalOptions so that if opts.apiKey is
present you do not call loadConfig — return an object using opts.apiKey and
opts.serverAddr ?? DEFAULT_SERVER_ADDR (and opts.json) directly; only call
loadConfig when opts.apiKey is not provided (or other values truly need backing
from config). Reference resolveGlobalOptions, loadConfig, DEFAULT_SERVER_ADDR,
and RawGlobalOptions to locate and change the logic.