@lotics/cli 0.24.1 → 0.25.0

package/README.md

@@ -46,9 +46,23 @@ lotics auth api-key                  # interactive prompt
 lotics auth api-key ltk_...          # non-interactive
 ```
 
-API key is saved to `~/.lotics/config.json`. Run `lotics auth logout` to remove saved credentials.
+API key is saved to the config file. Run `lotics auth logout` to remove saved credentials.
 
-Auth priority: `--api-key` flag > `LOTICS_API_KEY` env > `~/.lotics/config.json`.
+Auth priority: `--api-key` flag > `LOTICS_API_KEY` env > config file.
+
+### Config file location
+
+The CLI resolves `.lotics/config.json` by walking up from the current working directory — the first ancestor that has one wins, otherwise the global `~/.lotics/config.json`. A per-directory config lets a project or worktree pin its own account and workspace; commands run from a subdirectory still resolve to it.
+
+Create one by passing `--local` to `lotics auth`:
+
+```bash
+cd my-worktree
+lotics auth api-key ltk_... --local      # writes ./.lotics/config.json
+lotics workspace select wks_...          # auto-resolves to the local config
+```
+
+`.lotics/` should be gitignored. Note: an exported `LOTICS_API_KEY` overrides the config file's key.
 
 ## Workspaces
 

package/dist/src/cli.js

@@ -3,7 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import readline from "node:readline";
 import { LoticsClient, API_BASE_URL } from "./client.js";
-import { resolveAuth, loadConfig, saveConfig, deleteConfig, checkForUpdate } from "./config.js";
+import { resolveAuth, loadConfig, saveConfig, deleteConfig, getConfigPath, checkForUpdate } from "./config.js";
 import { VERSION } from "./version.js";
 import { appCreate, appPull, appDeploy, appDev } from "./app_commands.js";
 function printHelp() {
@@ -58,8 +58,15 @@ FLAGS
   -o <path>          Output dir for downloads
   --as <name>        Override upload filename
   --api-key <key>    API key (overrides saved config and LOTICS_API_KEY)
+  --local            (lotics auth) Save credentials to ./.lotics/config.json
   --version          Show version
 
+CONFIG
+  Credentials resolve from a .lotics/config.json found by walking up from the
+  current directory, else the global ~/.lotics/config.json. Run "lotics auth
+  api-key <key> --local" inside a directory (e.g. a worktree) to pin it to its
+  own account and workspace.
+
 OUTPUT
   Default output is a compact text summary optimized for AI agents —
   use it directly, no parsing needed. --json returns raw structured
@@ -92,13 +99,20 @@ function printAuthHelp() {
   lotics auth whoami                   Show the current account's name, email, and organization
   lotics auth logout                   Remove saved credentials
 
-Signup flags:
-  --name <name>          Display name (defaults to email prefix)
-  --timezone <timezone>  Workspace timezone (defaults to UTC, e.g. Asia/Ho_Chi_Minh)
+Auth flags:
+  --local                Save credentials to ./.lotics/config.json (this directory)
+                         instead of the global ~/.lotics — applies to signup + api-key
+  --name <name>          (signup) Display name (defaults to email prefix)
+  --timezone <timezone>  (signup) Workspace timezone (defaults to UTC, e.g. Asia/Ho_Chi_Minh)
 
 Signup sends a magic link email so you can access the Lotics web app.
 Use lotics auth web to request a new magic link at any time.
-Auth priority: --api-key flag > LOTICS_API_KEY env > saved config.`);
+
+Auth priority: --api-key flag > LOTICS_API_KEY env > config file.
+Config file: .lotics/config.json found by walking up from the current directory,
+else ~/.lotics/config.json. A per-directory config pins a project or worktree to
+its own account and workspace; --local creates one. Note: an exported
+LOTICS_API_KEY env var overrides the config file's key.`);
 }
 function parseArgs(argv) {
     const flags = {
@@ -109,6 +123,7 @@ function parseArgs(argv) {
         apiKey: undefined,
         name: undefined,
         timezone: undefined,
+        local: false,
         version: false,
         help: false,
     };
@@ -142,6 +157,9 @@ function parseArgs(argv) {
             case "--timezone":
                 flags.timezone = argv[++i];
                 break;
+            case "--local":
+                flags.local = true;
+                break;
             case "--version":
             case "-v":
                 flags.version = true;
@@ -223,19 +241,21 @@ async function handleSignup(positionalEmail, flags) {
         }
         process.exit(1);
     }
-    const existing = loadConfig() ?? {};
+    const scope = flags.local ? "local" : "auto";
+    const existing = loadConfig(scope) ?? {};
     saveConfig({
         ...existing,
         api_key: data.api_key,
         email: data.email,
         workspace_id: data.workspace_id,
-    });
+    }, scope);
     console.error(`Account created. You can now use the CLI.`);
-    console.error(`  Email: ${data.email}`);
+    console.error(`  Email:  ${data.email}`);
+    console.error(`  Config: ${getConfigPath(scope)}`);
     console.error(`\nCheck your email for a magic link to access the Lotics web app.`);
     console.error(`Run "lotics auth web" to request a new link at any time.`);
 }
-async function handleSetup(providedKey) {
+async function handleSetup(providedKey, local) {
     const apiKey = providedKey ?? await prompt("Enter your API key: ");
     if (!apiKey) {
         console.error("No API key provided.");
@@ -252,7 +272,8 @@ async function handleSetup(providedKey) {
         console.error(`Authentication failed: ${message}`);
         process.exit(1);
     }
-    const existing = loadConfig() ?? {};
+    const scope = local ? "local" : "auto";
+    const existing = loadConfig(scope) ?? {};
     const newConfig = { ...existing, api_key: apiKey, email };
     // Auto-resolve workspace
     try {
@@ -269,8 +290,9 @@ async function handleSetup(providedKey) {
         const msg = error instanceof Error ? error.message : String(error);
         console.error(`Warning: could not resolve workspace: ${msg}`);
     }
-    saveConfig(newConfig);
+    saveConfig(newConfig, scope);
     console.error("Authenticated.");
+    console.error(`  Config: ${getConfigPath(scope)}`);
 }
 function requireClient(flags) {
     const auth = resolveAuth(flags);
@@ -356,7 +378,7 @@ async function main() {
             return;
         }
         if (subcommand === "api-key") {
-            await handleSetup(toolArgs ?? flags.apiKey);
+            await handleSetup(toolArgs ?? flags.apiKey, flags.local);
             return;
         }
         if (subcommand === "whoami") {
@@ -377,6 +399,7 @@ async function main() {
                 console.log(`Email:   ${info.email}`);
                 console.log(`Org:     ${info.organization_name} (${info.organization_id})`);
             }
+            console.error(`Config:  ${getConfigPath()}`);
             return;
         }
         if (subcommand === "logout") {
@@ -495,6 +518,7 @@ async function main() {
                 }
             }
         }
+        console.error(`Config: ${getConfigPath()}`);
         return;
     }
     // Ensure workspace is resolved for all remaining commands

package/dist/src/config.d.ts

@@ -5,10 +5,22 @@ export interface LoticsConfig {
     last_update_check?: number;
     latest_version?: string;
 }
-export declare function loadConfig(): LoticsConfig | null;
-export declare function saveConfig(config: LoticsConfig): void;
-export declare function deleteConfig(): void;
-export declare function getConfigPath(): string;
+/**
+ * Where a config operation reads from or writes to.
+ *
+ * - `"auto"` — walk up from the current working directory; the first ancestor
+ *   containing `.lotics/config.json` wins, else the global `~/.lotics`. This
+ *   lets a project or worktree pin its own account and workspace, and keeps
+ *   resolution stable when commands run from a subdirectory.
+ * - `"local"` — `.lotics/config.json` directly under the current working
+ *   directory. Used to bootstrap a per-directory config (`lotics auth --local`)
+ *   before any local file exists for `"auto"` to discover.
+ */
+export type ConfigScope = "auto" | "local";
+export declare function loadConfig(scope?: ConfigScope): LoticsConfig | null;
+export declare function saveConfig(config: LoticsConfig, scope?: ConfigScope): void;
+export declare function deleteConfig(scope?: ConfigScope): void;
+export declare function getConfigPath(scope?: ConfigScope): string;
 /**
  * Check for a newer CLI version. Synchronous — prints a warning to stderr
  * if the cached latest version is newer than current. Kicks off a background

package/dist/src/config.js

@@ -1,31 +1,59 @@
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
-const CONFIG_DIR = path.join(os.homedir(), ".lotics");
-const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
-export function loadConfig() {
+/**
+ * Resolve the config file for a scope.
+ *
+ * Resolution keys on the `config.json` *file*, never the `.lotics` directory:
+ * scaffolded custom-code apps already use `.lotics/` for generated types, so
+ * directory presence cannot signal a local config.
+ */
+function configFileForScope(scope) {
+    if (scope === "local") {
+        return path.join(process.cwd(), ".lotics", "config.json");
+    }
+    let dir = process.cwd();
+    for (;;) {
+        const candidate = path.join(dir, ".lotics", "config.json");
+        if (fs.existsSync(candidate)) {
+            return candidate;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            break;
+        }
+        dir = parent;
+    }
+    return path.join(os.homedir(), ".lotics", "config.json");
+}
+export function loadConfig(scope = "auto") {
     try {
-        const raw = fs.readFileSync(CONFIG_FILE, "utf-8");
+        const raw = fs.readFileSync(configFileForScope(scope), "utf-8");
         return JSON.parse(raw);
     }
     catch {
         return null;
     }
 }
-export function saveConfig(config) {
-    fs.mkdirSync(CONFIG_DIR, { recursive: true });
-    fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + "\n", "utf-8");
+export function saveConfig(config, scope = "auto") {
+    const file = configFileForScope(scope);
+    // The config file holds an API key — keep it owner-only. `mode` on
+    // writeFileSync applies only when the file is created, so chmod after to
+    // also tighten a config written before this protection existed.
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(file, JSON.stringify(config, null, 2) + "\n", { encoding: "utf-8", mode: 0o600 });
+    fs.chmodSync(file, 0o600);
 }
-export function deleteConfig() {
+export function deleteConfig(scope = "auto") {
     try {
-        fs.unlinkSync(CONFIG_FILE);
+        fs.unlinkSync(configFileForScope(scope));
     }
     catch {
         // Already deleted or never existed
     }
 }
-export function getConfigPath() {
-    return CONFIG_FILE;
+export function getConfigPath(scope = "auto") {
+    return configFileForScope(scope);
 }
 const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
 /**

package/dist/src/config.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/config.test.js

@@ -0,0 +1,112 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { loadConfig, saveConfig, deleteConfig, getConfigPath } from "./config.js";
+/**
+ * Config resolution walks up from the current working directory: the first
+ * ancestor with a `.lotics/config.json` wins, otherwise the global
+ * `~/.lotics/config.json`. This lets a project or worktree pin its own
+ * account/workspace and keeps resolution stable when commands run from a
+ * subdirectory. Scope `"local"` targets the current directory exactly — used
+ * to bootstrap a per-directory config before any local file exists.
+ *
+ * These tests pin both `os.homedir()` and `process.cwd()` to temp dirs so the
+ * real home directory is never touched.
+ */
+describe("config file resolution", () => {
+    let homeDir;
+    let projectDir;
+    let originalCwd;
+    beforeEach(() => {
+        originalCwd = process.cwd();
+        homeDir = fs.mkdtempSync(path.join(os.tmpdir(), "lotics-home-"));
+        projectDir = fs.mkdtempSync(path.join(os.tmpdir(), "lotics-project-"));
+        vi.spyOn(os, "homedir").mockReturnValue(homeDir);
+        process.chdir(projectDir);
+    });
+    afterEach(() => {
+        process.chdir(originalCwd);
+        vi.restoreAllMocks();
+        fs.rmSync(homeDir, { recursive: true, force: true });
+        fs.rmSync(projectDir, { recursive: true, force: true });
+    });
+    const globalFile = () => path.join(homeDir, ".lotics", "config.json");
+    const localFile = (dir = projectDir) => path.join(dir, ".lotics", "config.json");
+    function write(file, data) {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(data));
+    }
+    function read(file) {
+        return JSON.parse(fs.readFileSync(file, "utf-8"));
+    }
+    function chdirInto(...segments) {
+        const dir = path.join(projectDir, ...segments);
+        fs.mkdirSync(dir, { recursive: true });
+        process.chdir(dir);
+        return dir;
+    }
+    it("returns null when no config exists anywhere", () => {
+        expect(loadConfig()).toBeNull();
+    });
+    it("reads the global config when no local config exists", () => {
+        write(globalFile(), { api_key: "ltk_global" });
+        expect(loadConfig()?.api_key).toBe("ltk_global");
+        expect(getConfigPath()).toBe(globalFile());
+    });
+    it("prefers a .lotics/config.json in the current directory over the global one", () => {
+        write(globalFile(), { api_key: "ltk_global" });
+        write(localFile(), { api_key: "ltk_local" });
+        expect(loadConfig()?.api_key).toBe("ltk_local");
+        expect(getConfigPath()).toBe(localFile());
+    });
+    it("walks up to an ancestor's config when run from a subdirectory", () => {
+        write(localFile(), { api_key: "ltk_project_root" });
+        chdirInto("backend", "features");
+        expect(loadConfig()?.api_key).toBe("ltk_project_root");
+        expect(getConfigPath()).toBe(localFile());
+    });
+    it("auto saveConfig writes the resolved ancestor file, not the subdirectory", () => {
+        write(localFile(), { api_key: "ltk_old" });
+        const nested = chdirInto("sub");
+        saveConfig({ api_key: "ltk_new" });
+        expect(read(localFile()).api_key).toBe("ltk_new");
+        expect(fs.existsSync(localFile(nested))).toBe(false);
+    });
+    it("auto saveConfig writes the global config when no local config exists", () => {
+        saveConfig({ api_key: "ltk_new" });
+        expect(fs.existsSync(localFile())).toBe(false);
+        expect(read(globalFile()).api_key).toBe("ltk_new");
+    });
+    it("scope 'local' creates ./.lotics/config.json even when none existed", () => {
+        saveConfig({ api_key: "ltk_pinned" }, "local");
+        expect(read(localFile()).api_key).toBe("ltk_pinned");
+        expect(getConfigPath("local")).toBe(localFile());
+    });
+    it("saveConfig writes the credentials file owner-only (0600)", () => {
+        saveConfig({ api_key: "ltk_secret" }, "local");
+        expect(fs.statSync(localFile()).mode & 0o777).toBe(0o600);
+    });
+    it("saveConfig tightens an over-permissive pre-existing config file", () => {
+        write(localFile(), { api_key: "ltk_old" });
+        fs.chmodSync(localFile(), 0o644);
+        saveConfig({ api_key: "ltk_new" }, "local");
+        expect(fs.statSync(localFile()).mode & 0o777).toBe(0o600);
+    });
+    it("loadConfig('local') never inherits the global config", () => {
+        write(globalFile(), { api_key: "ltk_global" });
+        expect(loadConfig("local")).toBeNull();
+    });
+    it("loadConfig('local') ignores an ancestor's config — it reads the exact cwd only", () => {
+        write(localFile(), { api_key: "ltk_root" });
+        chdirInto("sub");
+        expect(loadConfig("local")).toBeNull();
+    });
+    it("deleteConfig removes the active local config, leaving the global one untouched", () => {
+        write(globalFile(), { api_key: "ltk_global" });
+        write(localFile(), { api_key: "ltk_local" });
+        deleteConfig();
+        expect(fs.existsSync(localFile())).toBe(false);
+        expect(fs.existsSync(globalFile())).toBe(true);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.24.1",
+  "version": "0.25.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {