@withone/cli 1.17.2 → 1.18.0

package/README.md

@@ -225,6 +225,30 @@ one actions execute stripe <actionId> <connectionKey> \
 | `--form-url-encoded` | Send as application/x-www-form-urlencoded |
 | `--dry-run` | Show the request without executing it |
 
+### `one cache`
+
+Manage the local cache for knowledge and search responses. The CLI automatically caches `actions knowledge` and `actions search` results so repeated calls serve instantly from disk.
+
+```bash
+one cache list                    # List all cached entries with age and status
+one cache list --expired          # Show only expired entries
+one cache clear                   # Clear all cached data
+one cache clear <actionId>        # Clear a specific entry
+one cache update-all              # Re-fetch fresh data for all cached entries
+```
+
+Knowledge and search commands also support cache flags:
+
+```bash
+one actions knowledge gmail <actionId> --no-cache       # Skip cache, fetch fresh
+one actions knowledge gmail <actionId> --cache-status   # Check cache status
+one actions search gmail "send email" --no-cache        # Skip cache for search
+```
+
+Default TTL is 1 hour. Configure via `ONE_CACHE_TTL` environment variable or `cacheTtl` in `~/.one/config.json`.
+
+Note: `actions execute` is never cached — it always hits the API fresh.
+
 ### `one guide [topic]`
 
 Get the full CLI usage guide, designed for AI agents that only have the binary (no MCP, no IDE skills).
@@ -239,7 +263,7 @@ one --agent guide         # full guide as structured JSON
 one --agent guide flows   # single topic as JSON
 ```
 
-Topics: `overview`, `actions`, `flows`, `all` (default).
+Topics: `overview`, `actions`, `flows`, `relay`, `cache`, `all` (default).
 
 In agent mode (`--agent`), the JSON response includes the guide content and an `availableTopics` array so agents can discover what sections exist.
 

package/dist/{chunk-QW4MBV4F.js → chunk-CTL2YHUH.js}

@@ -128,6 +128,81 @@ var OneApi = class {
       method: action.method
     };
   }
+  async requestWithMeta(opts) {
+    let url = `${API_BASE}${opts.path}`;
+    if (opts.queryParams && Object.keys(opts.queryParams).length > 0) {
+      const params = new URLSearchParams(opts.queryParams);
+      url += `?${params.toString()}`;
+    }
+    const headers = {
+      "x-one-secret": this.apiKey,
+      "Content-Type": "application/json",
+      ...opts.headers
+    };
+    if (opts.ifNoneMatch) {
+      headers["If-None-Match"] = opts.ifNoneMatch;
+    }
+    const fetchOpts = {
+      method: opts.method || "GET",
+      headers
+    };
+    if (opts.body !== void 0) {
+      fetchOpts.body = JSON.stringify(opts.body);
+    }
+    const response = await fetch(url, fetchOpts);
+    if (response.status === 304) {
+      return { data: null, etag: opts.ifNoneMatch ?? null, status: 304 };
+    }
+    if (!response.ok) {
+      const text2 = await response.text();
+      throw new ApiError(response.status, text2 || `HTTP ${response.status}`);
+    }
+    const etag = response.headers.get("etag") ?? null;
+    const text = await response.text();
+    const data = text ? JSON.parse(text) : {};
+    return { data, etag, status: response.status };
+  }
+  async getActionKnowledgeWithMeta(actionId, ifNoneMatch) {
+    const result = await this.requestWithMeta({
+      path: "/knowledge",
+      queryParams: { _id: actionId },
+      ifNoneMatch
+    });
+    if (result.status === 304) {
+      return { data: null, etag: result.etag, status: 304 };
+    }
+    const actions = result.data?.rows || [];
+    if (actions.length === 0) {
+      throw new ApiError(404, `Action with ID ${actionId} not found`);
+    }
+    const action = actions[0];
+    const knowledge = {
+      knowledge: action.knowledge || "No knowledge was found",
+      method: action.method || "No method was found"
+    };
+    return { data: knowledge, etag: result.etag, status: result.status };
+  }
+  async searchActionsWithMeta(platform, query, agentType, ifNoneMatch) {
+    const isKnowledgeAgent = !agentType || agentType === "knowledge";
+    const queryParams = {
+      query,
+      limit: "5"
+    };
+    if (isKnowledgeAgent) {
+      queryParams.knowledgeAgent = "true";
+    } else {
+      queryParams.executeAgent = "true";
+    }
+    const result = await this.requestWithMeta({
+      path: `/available-actions/search/${platform}`,
+      queryParams,
+      ifNoneMatch
+    });
+    if (result.status === 304) {
+      return { data: null, etag: result.etag, status: 304 };
+    }
+    return { data: result.data || [], etag: result.etag, status: result.status };
+  }
   async executePassthroughRequest(args, preloadedAction) {
     const action = preloadedAction ?? await this.getActionDetails(args.actionId);
     const method = action.method;
@@ -703,7 +778,7 @@ async function executeSubflowStep(step, context, api, permissions, allowedAction
   if (flowStack.includes(resolvedKey)) {
     throw new Error(`Circular flow detected: ${[...flowStack, resolvedKey].join(" \u2192 ")}`);
   }
-  const { loadFlow: loadFlow2 } = await import("./flow-runner-AJGIUT6E.js");
+  const { loadFlow: loadFlow2 } = await import("./flow-runner-SU4JHSZW.js");
   const subFlow = loadFlow2(resolvedKey);
   const subContext = await executeFlow(
     subFlow,

package/dist/{flow-runner-AJGIUT6E.js → flow-runner-SU4JHSZW.js}

@@ -4,7 +4,7 @@ import {
   loadFlow,
   resolveFlowPath,
   saveFlow
-} from "./chunk-QW4MBV4F.js";
+} from "./chunk-CTL2YHUH.js";
 export {
   FlowRunner,
   listFlows,

package/dist/index.js

@@ -11,7 +11,7 @@ import {
   loadFlow,
   resolveFlowPath,
   saveFlow
-} from "./chunk-QW4MBV4F.js";
+} from "./chunk-CTL2YHUH.js";
 
 // src/index.ts
 import { createRequire as createRequire2 } from "module";
@@ -101,6 +101,15 @@ function getAccessControlFromAllSources() {
 function getAccessControl() {
   return readConfig()?.accessControl ?? {};
 }
+function getCacheTtl() {
+  if (process.env.ONE_CACHE_TTL) {
+    const val = parseInt(process.env.ONE_CACHE_TTL, 10);
+    if (!isNaN(val) && val > 0) return val;
+  }
+  const config = readConfig();
+  if (config?.cacheTtl && config.cacheTtl > 0) return config.cacheTtl;
+  return 3600;
+}
 function updateAccessControl(settings) {
   const config = readConfig();
   if (!config) return;
@@ -1350,6 +1359,123 @@ async function platformsCommand(options) {
 // src/commands/actions.ts
 import * as p6 from "@clack/prompts";
 import pc6 from "picocolors";
+
+// src/lib/cache.ts
+import fs4 from "fs";
+import path4 from "path";
+import os4 from "os";
+var CACHE_BASE = path4.join(os4.homedir(), ".one", "cache");
+var KNOWLEDGE_DIR = path4.join(CACHE_BASE, "knowledge");
+var SEARCH_DIR = path4.join(CACHE_BASE, "search");
+function sanitizeFilename(input) {
+  return input.replace(/[^a-zA-Z0-9_\-\.]/g, "_");
+}
+function knowledgeCachePath(actionId) {
+  return path4.join(KNOWLEDGE_DIR, `${sanitizeFilename(actionId)}.json`);
+}
+function searchCachePath(platform, query, type) {
+  const key = `${platform}_${sanitizeFilename(query)}_${type || "knowledge"}`;
+  return path4.join(SEARCH_DIR, `${key}.json`);
+}
+function readCache(filePath) {
+  try {
+    const content = fs4.readFileSync(filePath, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+function writeCache(filePath, entry) {
+  try {
+    const dir = path4.dirname(filePath);
+    fs4.mkdirSync(dir, { recursive: true });
+    fs4.writeFileSync(filePath, JSON.stringify(entry, null, 2));
+  } catch {
+  }
+}
+function isFresh(entry) {
+  const cachedTime = new Date(entry.cachedAt).getTime();
+  const now = Date.now();
+  return now - cachedTime < entry.ttl * 1e3;
+}
+function getAge(entry) {
+  return Math.floor((Date.now() - new Date(entry.cachedAt).getTime()) / 1e3);
+}
+function buildCacheMeta(entry, hit) {
+  if (!entry) {
+    return { hit: false, age: 0, fresh: false };
+  }
+  return {
+    hit,
+    age: getAge(entry),
+    fresh: isFresh(entry)
+  };
+}
+function formatAge(seconds) {
+  if (seconds < 60) return `${seconds}s`;
+  if (seconds < 3600) return `${Math.floor(seconds / 60)}m`;
+  if (seconds < 86400) {
+    const h2 = Math.floor(seconds / 3600);
+    const m = Math.floor(seconds % 3600 / 60);
+    return m > 0 ? `${h2}h ${m}m` : `${h2}h`;
+  }
+  const d = Math.floor(seconds / 86400);
+  const h = Math.floor(seconds % 86400 / 3600);
+  return h > 0 ? `${d}d ${h}h` : `${d}d`;
+}
+function listCacheEntries() {
+  const entries = [];
+  for (const [dir, type] of [[KNOWLEDGE_DIR, "knowledge"], [SEARCH_DIR, "search"]]) {
+    try {
+      const files = fs4.readdirSync(dir);
+      for (const file of files) {
+        if (!file.endsWith(".json")) continue;
+        const filePath = path4.join(dir, file);
+        const entry = readCache(filePath);
+        if (entry) {
+          entries.push({ type, filePath, entry });
+        }
+      }
+    } catch {
+    }
+  }
+  return entries;
+}
+function clearAll() {
+  let count = 0;
+  for (const dir of [KNOWLEDGE_DIR, SEARCH_DIR]) {
+    try {
+      const files = fs4.readdirSync(dir);
+      for (const file of files) {
+        fs4.unlinkSync(path4.join(dir, file));
+        count++;
+      }
+      fs4.rmdirSync(dir);
+    } catch {
+    }
+  }
+  return count;
+}
+function clearEntry(actionId) {
+  const filePath = knowledgeCachePath(actionId);
+  try {
+    fs4.unlinkSync(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function makeCacheEntry(key, data, etag) {
+  return {
+    key,
+    etag,
+    cachedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    ttl: getCacheTtl(),
+    data
+  };
+}
+
+// src/commands/actions.ts
 function getConfig() {
   const apiKey = getApiKey();
   if (!apiKey) {
@@ -1377,17 +1503,65 @@ async function actionsSearchCommand(platform, query, options) {
   spinner5.start(`Searching actions on ${pc6.cyan(platform)} for "${query}"...`);
   try {
     const agentType = knowledgeAgent ? "knowledge" : options.type;
-    let actions2 = await api.searchActions(platform, query, agentType);
-    actions2 = filterByPermissions(actions2, permissions);
-    actions2 = actions2.filter((a) => isActionAllowed(a.systemId, actionIds));
-    const cleanedActions = actions2.map((action) => ({
-      actionId: action.systemId,
-      title: action.title,
-      method: action.method,
-      path: action.path
-    }));
+    const useCache = options.cache !== false;
+    const cachePath = searchCachePath(platform, query, agentType || "knowledge");
+    const cached = useCache ? readCache(cachePath) : null;
+    let cleanedActions;
+    let cacheHit = false;
+    if (cached && isFresh(cached)) {
+      cleanedActions = cached.data.actions;
+      cacheHit = true;
+    } else {
+      try {
+        const result = await api.searchActionsWithMeta(
+          platform,
+          query,
+          agentType,
+          cached?.etag ?? void 0
+        );
+        if (result.status === 304 && cached) {
+          cached.cachedAt = (/* @__PURE__ */ new Date()).toISOString();
+          writeCache(cachePath, cached);
+          cleanedActions = cached.data.actions;
+          cacheHit = true;
+        } else {
+          let actions2 = result.data;
+          actions2 = filterByPermissions(actions2, permissions);
+          actions2 = actions2.filter((a) => isActionAllowed(a.systemId, actionIds));
+          cleanedActions = actions2.map((action) => ({
+            actionId: action.systemId,
+            title: action.title,
+            method: action.method,
+            path: action.path
+          }));
+          writeCache(cachePath, makeCacheEntry(
+            `${platform}_${query}_${agentType || "knowledge"}`,
+            { actions: cleanedActions },
+            result.etag
+          ));
+        }
+      } catch (fetchError) {
+        if (cached) {
+          process.stderr.write(
+            `Warning: serving cached search results (network unavailable, cached ${formatAge(getAge(cached))} ago)
+`
+          );
+          cleanedActions = cached.data.actions;
+          cacheHit = true;
+        } else {
+          throw fetchError;
+        }
+      }
+    }
     if (isAgentMode()) {
-      json({ actions: cleanedActions });
+      const response = { actions: cleanedActions };
+      if (cacheHit && cached) {
+        response._cache = buildCacheMeta(cached, true);
+      } else {
+        const freshEntry = readCache(cachePath);
+        response._cache = buildCacheMeta(freshEntry, false);
+      }
+      json(response);
       return;
     }
     if (cleanedActions.length === 0) {
@@ -1441,7 +1615,29 @@ Execute:     ${pc6.cyan(`one actions execute ${platform} <actionId> <connectionK
     );
   }
 }
-async function actionsKnowledgeCommand(platform, actionId) {
+async function actionsKnowledgeCommand(platform, actionId, options) {
+  const cachePath = knowledgeCachePath(actionId);
+  if (options.cacheStatus) {
+    const entry = readCache(cachePath);
+    if (!entry) {
+      json({
+        cached: false,
+        path: cachePath
+      });
+    } else {
+      const age = getAge(entry);
+      json({
+        cached: true,
+        cachedAt: entry.cachedAt,
+        age: formatAge(age),
+        ttl: entry.ttl,
+        expired: !isFresh(entry),
+        etag: entry.etag,
+        path: cachePath
+      });
+    }
+    return;
+  }
   intro2(pc6.bgCyan(pc6.black(" One ")));
   const { apiKey, actionIds, connectionKeys } = getConfig();
   const api = new OneApi(apiKey);
@@ -1469,15 +1665,57 @@ async function actionsKnowledgeCommand(platform, actionId) {
   const spinner5 = createSpinner();
   spinner5.start(`Loading knowledge for action ${pc6.dim(actionId)}...`);
   try {
-    const { knowledge, method } = await api.getActionKnowledge(actionId);
+    const useCache = options.cache !== false;
+    const cached = useCache ? readCache(cachePath) : null;
+    let knowledgeData;
+    let cacheHit = false;
+    let cacheEntry = cached;
+    if (cached && isFresh(cached) && useCache) {
+      knowledgeData = cached.data;
+      cacheHit = true;
+    } else {
+      try {
+        const result = await api.getActionKnowledgeWithMeta(
+          actionId,
+          cached?.etag ?? void 0
+        );
+        if (result.status === 304 && cached) {
+          cached.cachedAt = (/* @__PURE__ */ new Date()).toISOString();
+          writeCache(cachePath, cached);
+          knowledgeData = cached.data;
+          cacheHit = true;
+        } else {
+          knowledgeData = result.data;
+          const newEntry = makeCacheEntry(actionId, knowledgeData, result.etag);
+          writeCache(cachePath, newEntry);
+          cacheEntry = newEntry;
+        }
+      } catch (fetchError) {
+        if (cached) {
+          process.stderr.write(
+            `Warning: serving cached knowledge (network unavailable, cached ${formatAge(getAge(cached))} ago)
+`
+          );
+          knowledgeData = cached.data;
+          cacheHit = true;
+        } else {
+          throw fetchError;
+        }
+      }
+    }
     const knowledgeWithGuidance = buildActionKnowledgeWithGuidance(
-      knowledge,
-      method,
+      knowledgeData.knowledge,
+      knowledgeData.method,
       platform,
       actionId
     );
     if (isAgentMode()) {
-      json({ knowledge: knowledgeWithGuidance, method });
+      const response = {
+        knowledge: knowledgeWithGuidance,
+        method: knowledgeData.method,
+        _cache: buildCacheMeta(cacheEntry, cacheHit)
+      };
+      json(response);
       return;
     }
     spinner5.stop("Knowledge loaded");
@@ -2197,26 +2435,26 @@ function validateStepsArray(steps, pathPrefix, errors) {
   const validTypes = FLOW_SCHEMA.stepTypes.map((st) => st.type);
   for (let i = 0; i < steps.length; i++) {
     const step = steps[i];
-    const path4 = `${pathPrefix}[${i}]`;
+    const path5 = `${pathPrefix}[${i}]`;
     if (!step || typeof step !== "object" || Array.isArray(step)) {
-      errors.push({ path: path4, message: "Step must be an object" });
+      errors.push({ path: path5, message: "Step must be an object" });
       continue;
     }
     const s = step;
     if (!s.id || typeof s.id !== "string") {
-      errors.push({ path: `${path4}.id`, message: 'Step must have a string "id"' });
+      errors.push({ path: `${path5}.id`, message: 'Step must have a string "id"' });
     }
     if (!s.name || typeof s.name !== "string") {
-      errors.push({ path: `${path4}.name`, message: 'Step must have a string "name"' });
+      errors.push({ path: `${path5}.name`, message: 'Step must have a string "name"' });
     }
     if (!s.type || !validTypes.includes(s.type)) {
-      errors.push({ path: `${path4}.type`, message: `Step type must be one of: ${validTypes.join(", ")}` });
+      errors.push({ path: `${path5}.type`, message: `Step type must be one of: ${validTypes.join(", ")}` });
       continue;
     }
     if (s.onError && typeof s.onError === "object") {
       const oe = s.onError;
       if (!FLOW_SCHEMA.errorStrategies.includes(oe.strategy)) {
-        errors.push({ path: `${path4}.onError.strategy`, message: `Error strategy must be one of: ${FLOW_SCHEMA.errorStrategies.join(", ")}` });
+        errors.push({ path: `${path5}.onError.strategy`, message: `Error strategy must be one of: ${FLOW_SCHEMA.errorStrategies.join(", ")}` });
       }
     }
     const descriptor = getStepTypeDescriptor(s.type);
@@ -2226,14 +2464,14 @@ function validateStepsArray(steps, pathPrefix, errors) {
     if (!configObj || typeof configObj !== "object") {
       const hint = detectFlatConfigHint(s, descriptor);
       errors.push({
-        path: `${path4}.${configKey}`,
+        path: `${path5}.${configKey}`,
         message: `${capitalize(descriptor.type)} step must have a "${configKey}" config object${hint}`
       });
       continue;
     }
     const config = configObj;
     for (const [fieldName, fd] of Object.entries(descriptor.fields)) {
-      const fieldPath = `${path4}.${configKey}.${fieldName}`;
+      const fieldPath = `${path5}.${configKey}.${fieldName}`;
       const value = config[fieldName];
       if (fd.required && (value === void 0 || value === null || value === "")) {
         errors.push({ path: fieldPath, message: `${capitalize(descriptor.type)} must have ${fd.type === "string" ? "a string" : fd.type === "array" ? "a" : "a"} "${fieldName}"` });
@@ -2285,16 +2523,16 @@ function validateStepIds(flow2) {
   function collectIds(steps, pathPrefix) {
     for (let i = 0; i < steps.length; i++) {
       const step = steps[i];
-      const path4 = `${pathPrefix}[${i}]`;
+      const path5 = `${pathPrefix}[${i}]`;
       if (seen.has(step.id)) {
-        errors.push({ path: `${path4}.id`, message: `Duplicate step ID: "${step.id}"` });
+        errors.push({ path: `${path5}.id`, message: `Duplicate step ID: "${step.id}"` });
       } else {
         seen.add(step.id);
       }
       for (const { configKey, fieldName } of nestedKeys) {
         const config = step[configKey];
         if (config && Array.isArray(config[fieldName])) {
-          collectIds(config[fieldName], `${path4}.${configKey}.${fieldName}`);
+          collectIds(config[fieldName], `${path5}.${configKey}.${fieldName}`);
         }
       }
     }
@@ -2341,7 +2579,7 @@ function validateSelectorReferences(flow2) {
     }
     return selectors;
   }
-  function checkSelectors(selectors, path4) {
+  function checkSelectors(selectors, path5) {
     for (const selector of selectors) {
       const parts = selector.split(".");
       if (parts.length < 3) continue;
@@ -2349,12 +2587,12 @@ function validateSelectorReferences(flow2) {
       if (root === "input") {
         const inputName = parts[2];
         if (!inputNames.has(inputName)) {
-          errors.push({ path: path4, message: `Selector "${selector}" references undefined input "${inputName}"` });
+          errors.push({ path: path5, message: `Selector "${selector}" references undefined input "${inputName}"` });
         }
       } else if (root === "steps") {
         const stepId = parts[2];
         if (!allStepIds.has(stepId)) {
-          errors.push({ path: path4, message: `Selector "${selector}" references undefined step "${stepId}"` });
+          errors.push({ path: path5, message: `Selector "${selector}" references undefined step "${stepId}"` });
         }
       }
     }
@@ -2402,7 +2640,7 @@ function validateFlow(flow2) {
 }
 
 // src/commands/flow.ts
-import fs4 from "fs";
+import fs5 from "fs";
 function getConfig2() {
   const apiKey = getApiKey();
   if (!apiKey) {
@@ -2460,7 +2698,7 @@ async function flowCreateCommand(key, options) {
     if (raw.startsWith("@")) {
       const filePath = raw.slice(1);
       try {
-        raw = fs4.readFileSync(filePath, "utf-8");
+        raw = fs5.readFileSync(filePath, "utf-8");
       } catch (err) {
         error(`Cannot read file "${filePath}": ${err.message}`);
       }
@@ -2643,7 +2881,7 @@ async function flowValidateCommand(keyOrPath) {
   let flowData;
   try {
     const flowPath = resolveFlowPath(keyOrPath);
-    const content = fs4.readFileSync(flowPath, "utf-8");
+    const content = fs5.readFileSync(flowPath, "utf-8");
     flowData = JSON.parse(content);
   } catch (err) {
     spinner5.stop("Validation failed");
@@ -3312,8 +3550,122 @@ async function relayEventTypesCommand(platform) {
   }
 }
 
-// src/commands/guide.ts
+// src/commands/cache.ts
 import pc9 from "picocolors";
+async function cacheClearCommand(actionId) {
+  if (actionId) {
+    const deleted = clearEntry(actionId);
+    if (isAgentMode()) {
+      json({ cleared: deleted, actionId });
+      return;
+    }
+    if (deleted) {
+      console.log(`Cleared cache for ${pc9.cyan(actionId)}`);
+    } else {
+      console.log(`No cache entry found for ${pc9.dim(actionId)}`);
+    }
+  } else {
+    const count = clearAll();
+    if (isAgentMode()) {
+      json({ cleared: true, count });
+      return;
+    }
+    console.log(`Cleared ${count} cached ${count === 1 ? "entry" : "entries"}`);
+  }
+}
+async function cacheListCommand(options) {
+  const entries = listCacheEntries();
+  const filtered = options.expired ? entries.filter((e) => !isFresh(e.entry)) : entries;
+  if (isAgentMode()) {
+    json({
+      entries: filtered.map((e) => ({
+        type: e.type,
+        key: e.entry.key,
+        cachedAt: e.entry.cachedAt,
+        age: formatAge(getAge(e.entry)),
+        ttl: e.entry.ttl,
+        fresh: isFresh(e.entry),
+        etag: e.entry.etag,
+        path: e.filePath
+      }))
+    });
+    return;
+  }
+  if (filtered.length === 0) {
+    console.log(options.expired ? "No expired cache entries" : "No cached entries");
+    return;
+  }
+  const rows = filtered.map((e) => ({
+    type: e.type,
+    key: e.entry.key,
+    age: formatAge(getAge(e.entry)),
+    status: isFresh(e.entry) ? pc9.green("fresh") : pc9.yellow("expired")
+  }));
+  printTable(
+    [
+      { key: "type", label: "Type" },
+      { key: "key", label: "Key" },
+      { key: "age", label: "Age" },
+      { key: "status", label: "Status" }
+    ],
+    rows
+  );
+}
+async function cacheUpdateAllCommand() {
+  const apiKey = getApiKey();
+  if (!apiKey) {
+    error("Not configured. Run `one init` first.");
+  }
+  const api = new OneApi(apiKey);
+  const entries = listCacheEntries();
+  if (entries.length === 0) {
+    if (isAgentMode()) {
+      json({ updated: 0, failed: 0, entries: [] });
+      return;
+    }
+    console.log("No cached entries to update");
+    return;
+  }
+  const spinner5 = createSpinner();
+  spinner5.start(`Updating ${entries.length} cached ${entries.length === 1 ? "entry" : "entries"}...`);
+  let updated = 0;
+  let failed = 0;
+  const errors = [];
+  for (const e of entries) {
+    try {
+      if (e.type === "knowledge") {
+        const result = await api.getActionKnowledgeWithMeta(e.entry.key);
+        const newEntry = makeCacheEntry(e.entry.key, result.data, result.etag);
+        writeCache(e.filePath, newEntry);
+        updated++;
+      } else {
+        const refreshed = { ...e.entry, cachedAt: (/* @__PURE__ */ new Date()).toISOString() };
+        writeCache(e.filePath, refreshed);
+        updated++;
+      }
+    } catch (err) {
+      failed++;
+      errors.push({
+        key: e.entry.key,
+        error: err instanceof Error ? err.message : "Unknown error"
+      });
+    }
+  }
+  spinner5.stop(`Updated ${updated} ${updated === 1 ? "entry" : "entries"}${failed > 0 ? `, ${failed} failed` : ""}`);
+  if (isAgentMode()) {
+    json({ updated, failed, errors: errors.length > 0 ? errors : void 0 });
+    return;
+  }
+  if (errors.length > 0) {
+    console.log();
+    for (const e of errors) {
+      console.log(`  ${pc9.red("\u2717")} ${e.key}: ${pc9.dim(e.error)}`);
+    }
+  }
+}
+
+// src/commands/guide.ts
+import pc10 from "picocolors";
 
 // src/lib/guide-content.ts
 var GUIDE_OVERVIEW = `# One CLI \u2014 Agent Guide
@@ -3404,6 +3756,7 @@ Request specific sections:
 - \`one guide actions\` \u2014 Actions reference (search, knowledge, execute)
 - \`one guide flows\` \u2014 Workflow engine reference (step types, selectors, examples)
 - \`one guide relay\` \u2014 Webhook relay reference (templates, passthrough actions)
+- \`one guide cache\` \u2014 Cache management (TTL, flags, commands)
 - \`one guide all\` \u2014 Everything
 
 ## Important Notes
@@ -3555,11 +3908,93 @@ Any connected platform can be a destination via passthrough actions.
 3. \`relay deliveries --event-id <id>\` \u2014 check delivery status and errors
 4. \`relay event <id>\` \u2014 inspect full payload to verify template paths
 `;
+var GUIDE_CACHE = `# One Cache \u2014 Reference
+
+## Overview
+
+The One CLI caches \`actions knowledge\` and \`actions search\` responses locally so repeated calls serve instantly from disk instead of hitting the API. This is the single biggest latency win for agents who call knowledge for the same actions repeatedly.
+
+Cache location: \`~/.one/cache/knowledge/\` and \`~/.one/cache/search/\`
+
+## How It Works
+
+- **First call**: fetches from the API, writes to cache, serves the response
+- **Subsequent calls (within TTL)**: serves from cache instantly, no API call
+- **After TTL expires**: makes a conditional request (ETag). If content unchanged, refreshes the cache timestamp. If changed, writes fresh data.
+- **Network failure with stale cache**: serves the stale cache with a warning \u2014 never fails hard when a cache exists
+
+Default TTL: 3600 seconds (1 hour). Configure via \`ONE_CACHE_TTL\` env var or \`cacheTtl\` in \`~/.one/config.json\`.
+
+## What Gets Cached
+
+| Cached | Not Cached |
+|--------|-----------|
+| \`actions knowledge\` (API docs, change infrequently) | \`actions execute\` (live data, always fresh) |
+| \`actions search\` results | \`connection list\` (changes with add/remove) |
+
+## Agent Mode \`_cache\` Metadata
+
+In \`--agent\` mode, knowledge and search responses include a \`_cache\` field:
+
+\`\`\`json
+{
+  "knowledge": "...",
+  "method": "POST",
+  "_cache": {
+    "hit": true,
+    "age": 1423,
+    "fresh": true
+  }
+}
+\`\`\`
+
+Use this to programmatically decide whether to force-refresh.
+
+## Cache Flags
+
+\`\`\`bash
+# Skip cache, fetch fresh (result still gets cached for next time)
+one --agent actions knowledge <platform> <actionId> --no-cache
+
+# Check cache status without fetching
+one --agent actions knowledge <platform> <actionId> --cache-status
+
+# Same for search
+one --agent actions search <platform> "<query>" --no-cache
+\`\`\`
+
+## Cache Management Commands
+
+\`\`\`bash
+one cache list                    # List all cached entries with age and status
+one cache list --expired          # List only expired entries
+one cache clear                   # Delete all cached knowledge and search data
+one cache clear <actionId>        # Delete one specific entry
+one cache update-all              # Re-fetch fresh data for all cached entries
+\`\`\`
+
+All cache commands respect \`--agent\` for JSON output.
+
+## When to Force-Refresh
+
+- After a platform updates its API docs (rare)
+- If you suspect stale data is causing issues
+- Use \`one cache update-all\` to proactively warm the entire cache
+
+## Configuration
+
+| Setting | Source | Example |
+|---------|--------|---------|
+| TTL (seconds) | \`ONE_CACHE_TTL\` env var | \`ONE_CACHE_TTL=7200\` |
+| TTL (seconds) | \`cacheTtl\` in \`~/.one/config.json\` | \`"cacheTtl": 7200\` |
+| Default | \u2014 | 3600 (1 hour) |
+`;
 var TOPICS = [
   { topic: "overview", description: "Setup, features, and quick start for each" },
   { topic: "actions", description: "Search, read docs, and execute platform actions" },
   { topic: "flows", description: "Build and execute multi-step workflows" },
   { topic: "relay", description: "Receive webhooks and forward to other platforms" },
+  { topic: "cache", description: "Local caching for knowledge and search responses" },
   { topic: "all", description: "Complete guide (all topics combined)" }
 ];
 function getGuideContent(topic) {
@@ -3572,10 +4007,12 @@ function getGuideContent(topic) {
       return { title: "One CLI \u2014 Agent Guide: Workflows", content: GUIDE_FLOWS };
     case "relay":
       return { title: "One CLI \u2014 Agent Guide: Relay", content: GUIDE_RELAY };
+    case "cache":
+      return { title: "One CLI \u2014 Agent Guide: Cache", content: GUIDE_CACHE };
     case "all":
       return {
         title: "One CLI \u2014 Agent Guide: Complete",
-        content: [GUIDE_OVERVIEW, GUIDE_ACTIONS, GUIDE_FLOWS, GUIDE_RELAY].join("\n---\n\n")
+        content: [GUIDE_OVERVIEW, GUIDE_ACTIONS, GUIDE_FLOWS, GUIDE_RELAY, GUIDE_CACHE].join("\n---\n\n")
       };
   }
 }
@@ -3584,7 +4021,7 @@ function getAvailableTopics() {
 }
 
 // src/commands/guide.ts
-var VALID_TOPICS = ["overview", "actions", "flows", "relay", "all"];
+var VALID_TOPICS = ["overview", "actions", "flows", "relay", "cache", "all"];
 async function guideCommand(topic = "all") {
   if (!VALID_TOPICS.includes(topic)) {
     error(
@@ -3597,14 +4034,14 @@ async function guideCommand(topic = "all") {
     json({ topic, title, content, availableTopics });
     return;
   }
-  intro2(pc9.bgCyan(pc9.black(" One Guide ")));
+  intro2(pc10.bgCyan(pc10.black(" One Guide ")));
   console.log();
   console.log(content);
-  console.log(pc9.dim("\u2500".repeat(60)));
+  console.log(pc10.dim("\u2500".repeat(60)));
   console.log(
-    pc9.dim("Available topics: ") + availableTopics.map((t) => pc9.cyan(t.topic)).join(", ")
+    pc10.dim("Available topics: ") + availableTopics.map((t) => pc10.cyan(t.topic)).join(", ")
   );
-  console.log(pc9.dim(`Run ${pc9.cyan("one guide <topic>")} for a specific section.`));
+  console.log(pc10.dim(`Run ${pc10.cyan("one guide <topic>")} for a specific section.`));
 }
 
 // src/lib/platform-meta.ts
@@ -3947,14 +4384,14 @@ async function fetchLatestVersionInfo() {
     return null;
   }
 }
-function readCache() {
+function readCache3() {
   try {
     return JSON.parse(readFileSync(CACHE_PATH, "utf8"));
   } catch {
     return null;
   }
 }
-function writeCache(latestVersion, publishedAt) {
+function writeCache2(latestVersion, publishedAt) {
   try {
     mkdirSync(join(homedir(), ".one"), { recursive: true });
     writeFileSync(CACHE_PATH, JSON.stringify({ lastCheck: Date.now(), latestVersion, publishedAt }));
@@ -3963,16 +4400,16 @@ function writeCache(latestVersion, publishedAt) {
 }
 async function checkLatestVersion() {
   const info = await fetchLatestVersionInfo();
-  if (info) writeCache(info.version, info.publishedAt);
+  if (info) writeCache2(info.version, info.publishedAt);
   return info?.version ?? null;
 }
 async function checkLatestVersionCached() {
-  const cache = readCache();
-  if (cache && Date.now() - cache.lastCheck < CHECK_INTERVAL_MS) {
-    return { version: cache.latestVersion, publishedAt: cache.publishedAt ?? null };
+  const cache2 = readCache3();
+  if (cache2 && Date.now() - cache2.lastCheck < CHECK_INTERVAL_MS) {
+    return { version: cache2.latestVersion, publishedAt: cache2.publishedAt ?? null };
   }
   const info = await fetchLatestVersionInfo();
-  if (info) writeCache(info.version, info.publishedAt);
+  if (info) writeCache2(info.version, info.publishedAt);
   return info;
 }
 function getCurrentVersion() {
@@ -4054,6 +4491,11 @@ program.name("one").option("--agent", "Machine-readable JSON output (no colors,
     one flow execute <key>                Execute a workflow
     one flow validate <key>               Validate a flow
 
+  Cache:
+    one cache list                        List cached entries with age and status
+    one cache clear                       Clear all cached knowledge and search data
+    one cache update-all                  Re-fetch fresh data for all cached entries
+
   Webhook Relay:
     one relay create                      Create a relay endpoint for a connection
     one relay list                        List relay endpoints
@@ -4113,11 +4555,11 @@ program.command("platforms").alias("p").description("List available platforms").
   await platformsCommand(options);
 });
 var actions = program.command("actions").alias("a").description("Search, explore, and execute platform actions (workflow: search \u2192 knowledge \u2192 execute)");
-actions.command("search <platform> <query>").description('Search for actions on a platform (e.g. one actions search gmail "send email")').option("-t, --type <type>", "execute (to run it) or knowledge (to learn about it). Default: knowledge").action(async (platform, query, options) => {
+actions.command("search <platform> <query>").description('Search for actions on a platform (e.g. one actions search gmail "send email")').option("-t, --type <type>", "execute (to run it) or knowledge (to learn about it). Default: knowledge").option("--no-cache", "Skip cache, fetch fresh from API").action(async (platform, query, options) => {
   await actionsSearchCommand(platform, query, options);
 });
-actions.command("knowledge <platform> <actionId>").alias("k").description("Get full docs for an action \u2014 MUST call before execute to know required params").action(async (platform, actionId) => {
-  await actionsKnowledgeCommand(platform, actionId);
+actions.command("knowledge <platform> <actionId>").alias("k").description("Get full docs for an action \u2014 MUST call before execute to know required params").option("--no-cache", "Skip cache, fetch fresh from API").option("--cache-status", "Print cache metadata without fetching").action(async (platform, actionId, options) => {
+  await actionsKnowledgeCommand(platform, actionId, options);
 });
 actions.command("execute <platform> <actionId> <connectionKey>").alias("x").description('Execute an action \u2014 pass connectionKey from "one list", actionId from "actions search"').option("-d, --data <json>", "Request body as JSON").option("--path-vars <json>", "Path variables as JSON").option("--query-params <json>", "Query parameters as JSON").option("--headers <json>", "Additional headers as JSON").option("--form-data", "Send as multipart/form-data").option("--form-url-encoded", "Send as application/x-www-form-urlencoded").option("--dry-run", "Show request that would be sent without executing").action(async (platform, actionId, connectionKey, options) => {
   await actionsExecuteCommand(platform, actionId, connectionKey, {
@@ -4183,6 +4625,16 @@ relay.command("deliveries").description("List delivery attempts for an endpoint
 relay.command("event-types <platform>").description("List supported webhook event types for a platform").action(async (platform) => {
   await relayEventTypesCommand(platform);
 });
+var cache = program.command("cache").description("Manage the local knowledge and search cache");
+cache.command("clear [actionId]").description("Clear all cached data, or a specific action by ID").action(async (actionId) => {
+  await cacheClearCommand(actionId);
+});
+cache.command("list").alias("ls").description("List all cached entries with age and status").option("--expired", "Show only expired entries").action(async (options) => {
+  await cacheListCommand(options);
+});
+cache.command("update-all").description("Re-fetch fresh data for all cached entries").action(async () => {
+  await cacheUpdateAllCommand();
+});
 program.command("guide [topic]").description("Full CLI usage guide for agents (topics: overview, actions, flows, relay, all)").action(async (topic) => {
   await guideCommand(topic);
 });

package/package.json

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

package/skills/one/SKILL.md

@@ -100,6 +100,18 @@ All errors return JSON: `{"error": "message"}`. Parse output as JSON and check f
 - JSON values passed to `-d`, `--path-vars`, `--query-params` must be valid JSON (use single quotes around JSON to avoid shell escaping)
 - Do NOT pass path or query parameters inside the `-d` body flag
 
+## Caching
+
+Knowledge and search responses are cached locally (`~/.one/cache/`). Subsequent calls for the same action serve instantly from disk.
+
+- Cache is automatic — no setup required
+- Default TTL: 1 hour (configurable via `ONE_CACHE_TTL` env var)
+- In `--agent` mode, responses include a `_cache` field: `{"hit": true, "age": 1423, "fresh": true}`
+- Use `--no-cache` to force a fresh fetch: `one --agent actions knowledge <platform> <actionId> --no-cache`
+- Use `--cache-status` to check cache state without fetching
+- Manage cache: `one cache list`, `one cache clear`, `one cache update-all`
+- `actions execute` is NEVER cached — always fresh
+
 ## Beyond Single Actions
 
 One also supports more advanced patterns. Read the relevant reference file before using these: