@withone/cli 1.27.1 → 1.29.0

package/README.md

@@ -124,15 +124,22 @@ Set up your API key and install the MCP server into your AI agents.
 one init
 ```
 
-Supports Claude Code, Claude Desktop, Cursor, Windsurf, Codex, and Kiro. Installs globally by default, or per-project with `-p` so your team can share configs (each person uses their own API key).
+Supports Claude Code, Claude Desktop, Cursor, Windsurf, Codex, and Kiro.
 
-If you've already set up, `one init` shows your current status and lets you update your key, install to more agents, or reconfigure.
+**Global vs. project scope.** `one init` is interactive and asks where the setup should live:
+
+- **Global** (`~/.one/config.json`) — applies to every folder. Best when you only need one workspace / API key.
+- **Project** (`~/.one/projects/<slug>/config.json`) — scoped to the current project, stored under your home directory so secrets never land in git. Use this when different projects need different API keys, connections, or access control.
+
+When you run `one` in a project, it uses the project config if one exists and falls back to the global config otherwise. Use `one config path` to see which config is active and the full resolution order.
+
+If you've already set up, `one init` shows your current status for the active scope and lets you update your key, install to more agents, or reconfigure.
 
 | Flag | What it does |
 |------|-------------|
 | `-y` | Skip confirmations |
-| `-g` | Install globally (default) |
-| `-p` | Install for current project only |
+| `-g` | Non-interactive: write the One config globally (`~/.one/config.json`) |
+| `-p` | Non-interactive: write the One config for this project (`~/.one/projects/<slug>/config.json`) |
 
 ### `one add <platform>`
 
@@ -391,6 +398,30 @@ Settings propagate automatically to all installed agent configs.
 
 Auto-sync refuses to resurrect skills if you opted out of skill installation during `one init` — the canonical dir has to already exist.
 
+### Project config (`.onerc`)
+
+Drop a `.onerc` file in your project root to override global settings per-project. Simple `KEY=VALUE` format; `#` for comments. Read from the current working directory (no parent lookup).
+
+| Key | Purpose |
+|-----|---------|
+| `ONE_SECRET` | API key (also honored as env var) |
+| `ONE_API_BASE` | API base URL (also honored as env var) |
+| `ONE_PERMISSIONS` | `admin` / `write` / `read` |
+| `ONE_CONNECTION_KEYS` | Comma-separated connection-key allowlist |
+| `ONE_ACTION_IDS` | Comma-separated action-ID allowlist |
+| `ONE_KNOWLEDGE_AGENT` | `true` / `false` — knowledge-only mode |
+
+Precedence: env var > `.onerc` > `~/.one/config.json`.
+
+```bash
+# .onerc
+ONE_SECRET=sk_live_xxx
+ONE_API_BASE=https://development-api.withone.ai
+ONE_PERMISSIONS=read
+```
+
+> ⚠️ **Add `.onerc` to your `.gitignore`.** If you put `ONE_SECRET` in it, committing the file will leak your API key. Treat `.onerc` like `.env` — never check it in.
+
 ## The workflow
 
 The power of One is in the workflow. Every interaction follows the same pattern:

package/dist/index.js

@@ -36,24 +36,88 @@ import path from "path";
 import os from "os";
 var CONFIG_DIR = path.join(os.homedir(), ".one");
 var CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
-function getConfigPath() {
-  return CONFIG_FILE;
+var PROJECTS_DIR = path.join(CONFIG_DIR, "projects");
+function getProjectRoot(cwd = process.cwd()) {
+  let dir = path.resolve(cwd);
+  const root = path.parse(dir).root;
+  while (dir !== root) {
+    if (fs.existsSync(path.join(dir, ".git")) || fs.existsSync(path.join(dir, "package.json"))) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  return path.resolve(cwd);
 }
-function configExists() {
-  return fs.existsSync(CONFIG_FILE);
+function getProjectSlug(projectRoot = getProjectRoot()) {
+  return projectRoot.replace(/[\\/]/g, "-");
 }
-function readConfig() {
-  if (!configExists()) {
-    return null;
+function getProjectConfigDir(projectRoot = getProjectRoot()) {
+  return path.join(PROJECTS_DIR, getProjectSlug(projectRoot));
+}
+function getProjectConfigPath(projectRoot = getProjectRoot()) {
+  return path.join(getProjectConfigDir(projectRoot), "config.json");
+}
+function getGlobalConfigPath() {
+  return CONFIG_FILE;
+}
+function resolveConfig() {
+  const projectRoot = getProjectRoot();
+  const projectSlug = getProjectSlug(projectRoot);
+  const projectPath = getProjectConfigPath(projectRoot);
+  if (fs.existsSync(projectPath)) {
+    const config2 = readConfigFile(projectPath);
+    if (config2) {
+      return { config: config2, scope: "project", path: projectPath, projectRoot, projectSlug };
+    }
   }
+  if (fs.existsSync(CONFIG_FILE)) {
+    const config2 = readConfigFile(CONFIG_FILE);
+    if (config2) {
+      return { config: config2, scope: "global", path: CONFIG_FILE, projectRoot, projectSlug };
+    }
+  }
+  return { config: null, scope: null, path: CONFIG_FILE, projectRoot, projectSlug };
+}
+function readConfigFile(filePath) {
   try {
-    const content = fs.readFileSync(CONFIG_FILE, "utf-8");
+    const content = fs.readFileSync(filePath, "utf-8");
     return JSON.parse(content);
   } catch {
     return null;
   }
 }
-function writeConfig(config2) {
+function configExists() {
+  return resolveConfig().config !== null;
+}
+function globalConfigExists() {
+  return fs.existsSync(CONFIG_FILE);
+}
+function projectConfigExists(projectRoot = getProjectRoot()) {
+  return fs.existsSync(getProjectConfigPath(projectRoot));
+}
+function readConfig() {
+  return resolveConfig().config;
+}
+function readGlobalConfig() {
+  if (!fs.existsSync(CONFIG_FILE)) return null;
+  return readConfigFile(CONFIG_FILE);
+}
+function readProjectConfig() {
+  const projectPath = getProjectConfigPath();
+  if (!fs.existsSync(projectPath)) return null;
+  return readConfigFile(projectPath);
+}
+function writeConfig(config2, scope) {
+  const targetScope = scope ?? resolveConfig().scope ?? "global";
+  if (targetScope === "project") {
+    const dir = getProjectConfigDir();
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true, mode: 448 });
+    }
+    const filePath = getProjectConfigPath();
+    fs.writeFileSync(filePath, JSON.stringify(config2, null, 2), { mode: 384 });
+    return;
+  }
   if (!fs.existsSync(CONFIG_DIR)) {
     fs.mkdirSync(CONFIG_DIR, { mode: 448 });
   }
@@ -879,24 +943,98 @@ async function initCommand(options) {
   if (isAgentMode()) {
     error("This command requires interactive input. Run without --agent.");
   }
-  const existingConfig = readConfig();
   printBanner();
+  const scope = await chooseConfigScope(options);
+  if (scope === null) {
+    p3.cancel("Setup cancelled.");
+    return;
+  }
+  const existingConfig = scope === "project" ? readProjectConfig() : readGlobalConfig();
   if (existingConfig) {
-    await handleExistingConfig(existingConfig.apiKey, options);
+    await handleExistingConfig(existingConfig.apiKey, scope, options);
     return;
   }
-  await freshSetup(options);
+  await freshSetup(scope, options);
+}
+async function chooseConfigScope(options) {
+  if (options.global) return "global";
+  if (options.project) return "project";
+  const resolved = resolveConfig();
+  const hasGlobal = globalConfigExists();
+  const hasProject = projectConfigExists();
+  const projectRoot = resolved.projectRoot;
+  const projectName = path4.basename(projectRoot);
+  const homeGlobal = tildify(getGlobalConfigPath());
+  const homeProject = tildify(getProjectConfigPath(projectRoot));
+  if (hasProject) {
+    console.log();
+    console.log(`  ${pc2.dim("Project:")}  ${projectName}   ${pc2.dim(projectRoot)}`);
+    console.log(`  ${pc2.bold("Active config:")} ${pc2.cyan("project")} ${pc2.dim("\xB7 " + homeProject)}`);
+    console.log();
+    if (hasGlobal) {
+      const which2 = await p3.select({
+        message: "Which config do you want to edit?",
+        options: [
+          { value: "project", label: `This project (${projectName})`, hint: homeProject },
+          { value: "global", label: "Global (all folders)", hint: homeGlobal }
+        ],
+        initialValue: "project"
+      });
+      if (p3.isCancel(which2)) return null;
+      return which2;
+    }
+    return "project";
+  }
+  console.log();
+  console.log(`  ${pc2.bold("Initializing One")}`);
+  console.log(`  ${pc2.dim("\u2500".repeat(42))}`);
+  console.log(`  ${pc2.dim("Project:")}  ${projectName}   ${pc2.dim(projectRoot)}`);
+  console.log(`  ${pc2.dim("Global:")}   ${hasGlobal ? pc2.green("\u2713 configured") : pc2.yellow("\u2014 not set up")}   ${pc2.dim(homeGlobal)}`);
+  console.log(`  ${pc2.dim("Project:")}  ${pc2.yellow("\u2014 not set up")}   ${pc2.dim(homeProject)}`);
+  console.log();
+  const defaultScope = hasGlobal ? "project" : "global";
+  const hint = hasGlobal ? "Your global config stays as-is. This folder gets its own setup." : "No global config yet \u2014 this becomes your default for every folder.";
+  p3.note(hint, defaultScope === "project" ? "Recommended: project" : "Recommended: global");
+  const which = await p3.select({
+    message: "Where should this setup live?",
+    options: [
+      {
+        value: "project",
+        label: `This project only  (${projectName})`,
+        hint: "different API key / connections just for this folder"
+      },
+      {
+        value: "global",
+        label: "Globally (all folders)",
+        hint: "applies everywhere you run `one`"
+      }
+    ],
+    initialValue: defaultScope
+  });
+  if (p3.isCancel(which)) return null;
+  return which;
+}
+function tildify(filePath) {
+  const home = os4.homedir();
+  return filePath.startsWith(home) ? "~" + filePath.slice(home.length) : filePath;
+}
+function scopeLabel(scope) {
+  return scope === "project" ? pc2.cyan("[project]") : pc2.magenta("[global]");
 }
-async function handleExistingConfig(apiKey, options) {
+function scopedMessage(scope, message) {
+  return `${scopeLabel(scope)} ${message}`;
+}
+async function handleExistingConfig(apiKey, scope, options) {
   const statuses = getAgentStatuses();
   const masked = maskApiKey(apiKey);
   const skillInstalled = isSkillInstalled2();
+  const activeConfigPath = scope === "project" ? getProjectConfigPath() : getGlobalConfigPath();
   console.log();
-  console.log(`  ${pc2.bold("Current Setup")}`);
+  console.log(`  ${pc2.bold("Current Setup")} ${scopeLabel(scope)}`);
   console.log(`  ${pc2.dim("\u2500".repeat(42))}`);
   console.log(`  ${pc2.dim("API Key:")}  ${masked}`);
   console.log(`  ${pc2.dim("Skill:")}    ${skillInstalled ? pc2.green("installed") : pc2.yellow("not installed")}`);
-  console.log(`  ${pc2.dim("Config:")}   ${getConfigPath()}`);
+  console.log(`  ${pc2.dim("Config:")}   ${tildify(activeConfigPath)}`);
   const ac = getAccessControl();
   if (Object.keys(ac).length > 0) {
     console.log();
@@ -938,7 +1076,7 @@ async function handleExistingConfig(apiKey, options) {
     label: "Start fresh (reconfigure everything)"
   });
   const action = await p3.select({
-    message: "What would you like to do?",
+    message: scopedMessage(scope, "What would you like to do?"),
     options: actionOptions
   });
   if (p3.isCancel(action)) {
@@ -965,21 +1103,21 @@ async function handleExistingConfig(apiKey, options) {
       p3.outro("Done.");
       break;
     case "update-key":
-      await handleUpdateKey(statuses);
+      await handleUpdateKey(statuses, scope);
       break;
     case "access-control":
       await configCommand();
       break;
     case "start-fresh":
-      await freshSetup({ yes: true });
+      await freshSetup(scope, { yes: true });
       break;
   }
 }
-async function handleUpdateKey(statuses) {
+async function handleUpdateKey(statuses, scope) {
   p3.note(`Get your API key at:
-${pc2.cyan(getApiKeyUrl())}`, "API Key");
+${pc2.cyan(getApiKeyUrl())}`, `API Key ${scopeLabel(scope)}`);
   const openBrowser = await p3.confirm({
-    message: "Open browser to get API key?",
+    message: scopedMessage(scope, "Open browser to get API key?"),
     initialValue: true
   });
   if (p3.isCancel(openBrowser)) {
@@ -990,7 +1128,7 @@ ${pc2.cyan(getApiKeyUrl())}`, "API Key");
     await openApiKeyPage();
   }
   const newKey = await p3.text({
-    message: "Enter your new One API key:",
+    message: scopedMessage(scope, "Enter your new One API key:"),
     placeholder: "sk_live_...",
     validate: (value) => {
       if (!value) return "API key is required";
@@ -1026,13 +1164,18 @@ ${pc2.cyan(getApiKeyUrl())}`, "API Key");
       reinstalled.push(`${s.agent.name} (project)`);
     }
   }
-  const config2 = readConfig();
-  writeConfig({
-    apiKey: newKey,
-    installedAgents: config2?.installedAgents ?? [],
-    createdAt: config2?.createdAt ?? (/* @__PURE__ */ new Date()).toISOString(),
-    accessControl: config2?.accessControl
-  });
+  const current = scope === "project" ? readProjectConfig() : readGlobalConfig();
+  writeConfig(
+    {
+      apiKey: newKey,
+      installedAgents: current?.installedAgents ?? [],
+      createdAt: current?.createdAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+      accessControl: current?.accessControl,
+      apiBase: current?.apiBase,
+      cacheTtl: current?.cacheTtl
+    },
+    scope
+  );
   if (reinstalled.length > 0) {
     p3.log.success(`Updated MCP configs: ${reinstalled.join(", ")}`);
   }
@@ -1195,11 +1338,11 @@ function printOnboardingPrompt() {
   console.log(pc2.cyan("  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
   console.log();
 }
-async function freshSetup(options) {
+async function freshSetup(scope, options) {
   p3.note(`Get your API key at:
-${pc2.cyan(getApiKeyUrl())}`, "API Key");
+${pc2.cyan(getApiKeyUrl())}`, `API Key ${scopeLabel(scope)}`);
   const openBrowser = await p3.confirm({
-    message: "Open browser to get API key?",
+    message: scopedMessage(scope, "Open browser to get API key?"),
     initialValue: true
   });
   if (p3.isCancel(openBrowser)) {
@@ -1210,7 +1353,7 @@ ${pc2.cyan(getApiKeyUrl())}`, "API Key");
     await openApiKeyPage();
   }
   const apiKey = await p3.text({
-    message: "Enter your One API key:",
+    message: scopedMessage(scope, "Enter your One API key:"),
     placeholder: "sk_live_...",
     validate: (value) => {
       if (!value) return "API key is required";
@@ -1234,15 +1377,24 @@ ${pc2.cyan(getApiKeyUrl())}`, "API Key");
     process.exit(1);
   }
   spinner5.stop("API key validated");
-  writeConfig({
-    apiKey,
-    installedAgents: [],
-    createdAt: (/* @__PURE__ */ new Date()).toISOString()
-  });
+  writeConfig(
+    {
+      apiKey,
+      installedAgents: [],
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    },
+    scope
+  );
   await promptSkillInstall();
   await promptConnectIntegrations(apiKey);
+  const savedPath = scope === "project" ? getProjectConfigPath() : getGlobalConfigPath();
+  const resolutionHint = scope === "project" ? `When you run ${pc2.cyan("one")} from ${pc2.bold(path4.basename(getProjectRoot()))}, it uses this project config.
+From anywhere else, it falls back to your global config.` : `This config applies to every folder unless a project config is set.`;
   p3.note(
-    `Config saved to: ${pc2.dim(getConfigPath())}`,
+    `${scopeLabel(scope)} Config saved to:
+${pc2.dim(tildify(savedPath))}
+
+${resolutionHint}`,
     "Setup Complete"
   );
   printOnboardingPrompt();
@@ -3870,7 +4022,7 @@ var GUIDE_OVERVIEW = `# One CLI \u2014 Agent Guide
 
 ## Setup
 
-1. Run \`one init\` to configure your API key
+1. Run \`one init\` to configure your API key (interactive \u2014 can be global or per-project)
 2. Run \`one add <platform>\` to connect platforms via OAuth
 3. Run \`one --agent connection list\` to verify connections
 
@@ -4650,12 +4802,46 @@ program.hook("postAction", async () => {
   if (!isNewerVersion(info.version, current)) return;
   autoUpdate(info.version, info.publishedAt);
 });
-program.command("init").description("Set up One and install MCP to your AI agents").option("-y, --yes", "Skip confirmations").option("-g, --global", "Install MCP globally (available in all projects)").option("-p, --project", "Install MCP for this project only (creates .mcp.json)").action(async (options) => {
+program.command("init").description("Set up One and install MCP to your AI agents (interactive: picks global or project scope)").option("-y, --yes", "Skip confirmations").option("-g, --global", "Write the One config globally (~/.one/config.json) \u2014 skips the scope picker").option("-p, --project", "Write the One config for this project only (~/.one/projects/<slug>/) \u2014 skips the scope picker").action(async (options) => {
   await initCommand(options);
 });
 var config = program.command("config").description("Configure the CLI (access control, skills, ...)").action(async () => {
   await configCommand();
 });
+config.command("path").description("Show the active config path, scope, and the fallback chain (project \u2192 global)").action(() => {
+  const resolved = resolveConfig();
+  const globalPath = getGlobalConfigPath();
+  const projectPath = getProjectConfigPath(resolved.projectRoot);
+  const hasGlobal = globalConfigExists();
+  const hasProject = projectConfigExists(resolved.projectRoot);
+  if (isAgentMode()) {
+    json({
+      command: "config path",
+      scope: resolved.scope,
+      path: resolved.path,
+      projectRoot: resolved.projectRoot,
+      projectSlug: resolved.projectSlug,
+      fallback: {
+        project: { path: projectPath, exists: hasProject },
+        global: { path: globalPath, exists: hasGlobal }
+      }
+    });
+    return;
+  }
+  if (!resolved.scope) {
+    console.log("No One config found.");
+    console.log(`  project: ${projectPath} (not set up)`);
+    console.log(`  global:  ${globalPath} (not set up)`);
+    console.log("\nRun 'one init' to get started.");
+    return;
+  }
+  console.log(`Active:   ${resolved.scope}`);
+  console.log(`Path:     ${resolved.path}`);
+  console.log(`
+Resolution order (first match wins):`);
+  console.log(`  1. project  ${projectPath}  ${hasProject ? "\u2713" : "\u2014"}`);
+  console.log(`  2. global   ${globalPath}   ${hasGlobal ? "\u2713" : "\u2014"}`);
+});
 var configSkills = config.command("skills").description("Manage locally-installed skill files");
 configSkills.command("sync").description("Re-copy packaged skill files over the local install (runs automatically after CLI upgrades)").action(async () => {
   const result = forceSyncSkills();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withone/cli",
-  "version": "1.27.1",
+  "version": "1.29.0",
   "description": "CLI for managing One",
   "type": "module",
   "files": [

package/skills/one/SKILL.md

@@ -22,6 +22,8 @@ description: |
 
 You have access to the One CLI which lets you interact with 250+ third-party platforms through their APIs. Always include the `--agent` flag right after `one` for structured JSON output.
 
+If the user wants a separate API key / connections for a specific project (vs. their default), walk them through running `one init` from that project folder and picking the "project" scope — see `references/scoping.md`.
+
 ## Core Workflow: search -> knowledge -> execute
 
 Always follow this sequence when the user wants to do something on a connected platform:

package/skills/one/references/scoping.md

@@ -0,0 +1,35 @@
+# Project vs. global config
+
+The One CLI can be configured at two scopes:
+
+- **Global** — `~/.one/config.json`. Applies everywhere the user runs `one`.
+- **Project** — `~/.one/projects/<slug>/config.json`, where `<slug>` is the project root path with slashes replaced by dashes (e.g. `/Users/jane/acme` → `-Users-jane-acme`). Only applies when running `one` from inside that project folder.
+
+**Resolution order:** env vars → `.onerc` in cwd → project config → global config. Project config wins when present; otherwise the CLI falls back to the global config.
+
+## When to suggest project scope
+
+Suggest project scope when the user wants any of the following for a specific folder only, without changing their default setup:
+
+- A different One API key (e.g. sandbox workspace for a client project)
+- A different set of connections / connection keys
+- Different access control (permissions, scoped connections, knowledge-only mode)
+
+## How to set it up
+
+Do **not** hand-edit `.onerc` or config files. Walk the user through the interactive init:
+
+```bash
+cd /path/to/the/project
+one init
+```
+
+When `init` asks "Where should this setup live?", pick **"This project only"**. Init will write the config to `~/.one/projects/<slug>/config.json` and everything else (skill install, MCP) stays untouched.
+
+To see which config is currently active and the full fallback chain:
+
+```bash
+one --agent config path
+```
+
+To switch an existing project back to using the global config, delete its project config file — the CLI will automatically fall back to global on the next run.