@ariadng/sheets 0.3.4 → 0.4.1

package/dist/cli.cjs

@@ -0,0 +1,1610 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/cli.ts
+var fs3 = __toESM(require("fs/promises"), 1);
+var path2 = __toESM(require("path"), 1);
+var os2 = __toESM(require("os"), 1);
+
+// src/types/index.ts
+var SheetsError = class extends Error {
+  code;
+  status;
+  details;
+  constructor(error) {
+    super(error.message);
+    this.name = "SheetsError";
+    this.code = error.code;
+    this.status = error.status;
+    this.details = error.details;
+  }
+};
+
+// src/http/index.ts
+var BASE_URL = "https://sheets.googleapis.com/v4";
+var MAX_RETRIES = 3;
+var INITIAL_BACKOFF_MS = 1e3;
+var HttpClient = class {
+  getAccessToken;
+  constructor(options) {
+    this.getAccessToken = options.getAccessToken;
+  }
+  async request(path3, options = {}) {
+    const { method = "GET", body, params } = options;
+    let url = `${BASE_URL}${path3}`;
+    if (params) {
+      const searchParams = new URLSearchParams(params);
+      url += `?${searchParams.toString()}`;
+    }
+    let lastError = null;
+    for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+      try {
+        const accessToken = await this.getAccessToken();
+        const response = await fetch(url, {
+          method,
+          headers: {
+            "Authorization": `Bearer ${accessToken}`,
+            "Content-Type": "application/json"
+          },
+          body: body ? JSON.stringify(body) : void 0
+        });
+        if (response.status === 429) {
+          const backoffMs = INITIAL_BACKOFF_MS * Math.pow(2, attempt);
+          await this.sleep(backoffMs);
+          continue;
+        }
+        const data = await response.json();
+        if (!response.ok) {
+          if (data.error) {
+            throw new SheetsError({
+              code: data.error.code,
+              message: data.error.message,
+              status: data.error.status
+            });
+          }
+          throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+        return data;
+      } catch (error) {
+        lastError = error;
+        if (error instanceof SheetsError && error.code !== 429 && error.code !== 500 && error.code !== 503) {
+          throw error;
+        }
+        if (attempt < MAX_RETRIES - 1) {
+          const backoffMs = INITIAL_BACKOFF_MS * Math.pow(2, attempt);
+          await this.sleep(backoffMs);
+        }
+      }
+    }
+    throw lastError || new Error("Request failed after retries");
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+
+// src/auth/constants.ts
+var OAUTH_CLIENT_ID = "344941894490-jmdvo5ghomqi7vuisfrf80hfassk1ma5.apps.googleusercontent.com";
+var OAUTH_CLIENT_SECRET = "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";
+var OAUTH_REDIRECT_URI = "http://localhost:8085/callback";
+var OAUTH_CALLBACK_PORT = 8085;
+var OAUTH_AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth";
+var OAUTH_TOKEN_URL = "https://oauth2.googleapis.com/token";
+var OAUTH_USERINFO_URL = "https://www.googleapis.com/oauth2/v2/userinfo";
+var OAUTH_SCOPES = [
+  "https://www.googleapis.com/auth/spreadsheets",
+  "https://www.googleapis.com/auth/userinfo.email"
+];
+
+// src/auth/oauth.ts
+var OAuthAuth = class {
+  config;
+  cachedToken;
+  expiresAt;
+  constructor(config) {
+    this.config = config;
+    this.cachedToken = config.accessToken;
+    this.expiresAt = config.expiresAt || 0;
+  }
+  async getAccessToken() {
+    if (!this.canRefresh()) {
+      return this.cachedToken;
+    }
+    if (this.isExpired()) {
+      await this.refreshToken();
+    }
+    return this.cachedToken;
+  }
+  canRefresh() {
+    return !!(this.config.refreshToken && this.config.clientId && this.config.clientSecret && this.expiresAt > 0);
+  }
+  isExpired() {
+    return Date.now() >= this.expiresAt - 6e4;
+  }
+  async refreshToken() {
+    if (!this.config.refreshToken || !this.config.clientId || !this.config.clientSecret) {
+      throw new Error("Token expired and missing refresh credentials (refreshToken, clientId, clientSecret)");
+    }
+    const response = await fetch(OAUTH_TOKEN_URL, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        client_id: this.config.clientId,
+        client_secret: this.config.clientSecret,
+        refresh_token: this.config.refreshToken,
+        grant_type: "refresh_token"
+      })
+    });
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Token refresh failed: ${error}`);
+    }
+    const tokenResponse = await response.json();
+    this.cachedToken = tokenResponse.access_token;
+    this.expiresAt = Date.now() + tokenResponse.expires_in * 1e3;
+    if (tokenResponse.refresh_token) {
+      this.config.refreshToken = tokenResponse.refresh_token;
+    }
+  }
+  /**
+   * Get current token state for persistence in automation tools
+   * Returns updated tokens after any refresh operations
+   */
+  getTokenState() {
+    return {
+      accessToken: this.cachedToken,
+      refreshToken: this.config.refreshToken,
+      expiresAt: this.expiresAt
+    };
+  }
+};
+
+// src/auth/service-account.ts
+var crypto = __toESM(require("crypto"), 1);
+var fs = __toESM(require("fs/promises"), 1);
+var TOKEN_URI = "https://oauth2.googleapis.com/token";
+var SCOPE = "https://www.googleapis.com/auth/spreadsheets.readonly";
+var TOKEN_LIFETIME_SECONDS = 3600;
+var ServiceAccountAuth = class {
+  config;
+  credentials = null;
+  cachedToken = null;
+  tokenExpiresAt = 0;
+  constructor(config) {
+    this.config = config;
+  }
+  async getAccessToken() {
+    if (this.cachedToken && Date.now() < this.tokenExpiresAt - 6e4) {
+      return this.cachedToken;
+    }
+    await this.loadCredentials();
+    const jwt = this.createJwt();
+    const token = await this.exchangeJwtForToken(jwt);
+    this.cachedToken = token.access_token;
+    this.tokenExpiresAt = Date.now() + token.expires_in * 1e3;
+    return this.cachedToken;
+  }
+  async loadCredentials() {
+    if (this.credentials) return;
+    if (this.config.credentials) {
+      this.credentials = this.config.credentials;
+      return;
+    }
+    if (!this.config.credentialsPath) {
+      throw new Error("Service account requires credentialsPath or credentials");
+    }
+    const content = await fs.readFile(this.config.credentialsPath, "utf-8");
+    this.credentials = JSON.parse(content);
+  }
+  createJwt() {
+    if (!this.credentials) {
+      throw new Error("Credentials not loaded");
+    }
+    const now = Math.floor(Date.now() / 1e3);
+    const header = {
+      alg: "RS256",
+      typ: "JWT"
+    };
+    const payload = {
+      iss: this.credentials.client_email,
+      scope: SCOPE,
+      aud: TOKEN_URI,
+      iat: now,
+      exp: now + TOKEN_LIFETIME_SECONDS
+    };
+    const encodedHeader = this.base64UrlEncode(JSON.stringify(header));
+    const encodedPayload = this.base64UrlEncode(JSON.stringify(payload));
+    const signatureInput = `${encodedHeader}.${encodedPayload}`;
+    const sign = crypto.createSign("RSA-SHA256");
+    sign.update(signatureInput);
+    const signature = sign.sign(this.credentials.private_key);
+    const encodedSignature = this.base64UrlEncode(signature);
+    return `${signatureInput}.${encodedSignature}`;
+  }
+  base64UrlEncode(input) {
+    const buffer = typeof input === "string" ? Buffer.from(input) : input;
+    return buffer.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+  }
+  async exchangeJwtForToken(jwt) {
+    const response = await fetch(TOKEN_URI, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded"
+      },
+      body: new URLSearchParams({
+        grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+        assertion: jwt
+      })
+    });
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Token exchange failed: ${error}`);
+    }
+    return await response.json();
+  }
+};
+
+// src/auth/user-auth.ts
+var crypto2 = __toESM(require("crypto"), 1);
+var fs2 = __toESM(require("fs/promises"), 1);
+var http = __toESM(require("http"), 1);
+var os = __toESM(require("os"), 1);
+var path = __toESM(require("path"), 1);
+var import_child_process = require("child_process");
+var CONFIG_DIR = path.join(os.homedir(), ".sheets");
+var TOKENS_FILE = path.join(CONFIG_DIR, "tokens.json");
+function generatePKCE() {
+  const codeVerifier = crypto2.randomBytes(32).toString("base64url");
+  const codeChallenge = crypto2.createHash("sha256").update(codeVerifier).digest("base64url");
+  return { codeVerifier, codeChallenge };
+}
+function openBrowser(url) {
+  return new Promise((resolve, reject) => {
+    const platform = process.platform;
+    let command;
+    if (platform === "darwin") {
+      command = `open "${url}"`;
+    } else if (platform === "win32") {
+      command = `start "" "${url}"`;
+    } else {
+      command = `xdg-open "${url}"`;
+    }
+    (0, import_child_process.exec)(command, (error) => {
+      if (error) {
+        reject(new Error(`Failed to open browser: ${error.message}`));
+      } else {
+        resolve();
+      }
+    });
+  });
+}
+function startCallbackServer() {
+  return new Promise((resolve, reject) => {
+    let timeoutId;
+    const server = http.createServer((req, res) => {
+      const url = new URL(req.url || "", `http://localhost:${OAUTH_CALLBACK_PORT}`);
+      if (url.pathname === "/callback") {
+        const code = url.searchParams.get("code");
+        const error = url.searchParams.get("error");
+        if (error) {
+          res.writeHead(400, { "Content-Type": "text/html" });
+          res.end("<html><body><h1>Authorization Failed</h1><p>You can close this window.</p></body></html>");
+          clearTimeout(timeoutId);
+          server.close();
+          reject(new Error(`Authorization error: ${error}`));
+          return;
+        }
+        if (code) {
+          res.writeHead(200, { "Content-Type": "text/html" });
+          res.end("<html><body><h1>Authorization Successful</h1><p>You can close this window.</p></body></html>");
+          clearTimeout(timeoutId);
+          server.close();
+          resolve(code);
+          return;
+        }
+        res.writeHead(400, { "Content-Type": "text/html" });
+        res.end("<html><body><h1>Missing Code</h1></body></html>");
+      } else {
+        res.writeHead(404);
+        res.end();
+      }
+    });
+    server.on("error", (err) => {
+      clearTimeout(timeoutId);
+      reject(new Error(`Callback server error: ${err.message}`));
+    });
+    server.listen(OAUTH_CALLBACK_PORT, () => {
+    });
+    timeoutId = setTimeout(() => {
+      server.close();
+      reject(new Error("Authorization timeout"));
+    }, 5 * 60 * 1e3);
+  });
+}
+function getAuthorizationUrl(codeChallenge, clientId) {
+  const params = new URLSearchParams({
+    client_id: clientId || OAUTH_CLIENT_ID,
+    redirect_uri: OAUTH_REDIRECT_URI,
+    response_type: "code",
+    scope: OAUTH_SCOPES.join(" "),
+    code_challenge: codeChallenge,
+    code_challenge_method: "S256",
+    access_type: "offline",
+    prompt: "consent"
+  });
+  return `${OAUTH_AUTH_URL}?${params.toString()}`;
+}
+async function exchangeCodeForTokens(code, codeVerifier, credentials) {
+  const response = await fetch(OAUTH_TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      client_id: credentials?.clientId || OAUTH_CLIENT_ID,
+      client_secret: credentials?.clientSecret || OAUTH_CLIENT_SECRET,
+      code,
+      code_verifier: codeVerifier,
+      grant_type: "authorization_code",
+      redirect_uri: OAUTH_REDIRECT_URI
+    })
+  });
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Token exchange failed: ${error}`);
+  }
+  return await response.json();
+}
+async function refreshAccessToken(refreshToken) {
+  const response = await fetch(OAUTH_TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      client_id: OAUTH_CLIENT_ID,
+      client_secret: OAUTH_CLIENT_SECRET,
+      refresh_token: refreshToken,
+      grant_type: "refresh_token"
+    })
+  });
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Token refresh failed: ${error}`);
+  }
+  return await response.json();
+}
+async function getUserInfo(accessToken) {
+  const response = await fetch(OAUTH_USERINFO_URL, {
+    headers: { Authorization: `Bearer ${accessToken}` }
+  });
+  if (!response.ok) {
+    throw new Error("Failed to get user info");
+  }
+  return await response.json();
+}
+async function ensureConfigDir() {
+  try {
+    await fs2.mkdir(CONFIG_DIR, { recursive: true });
+  } catch {
+  }
+}
+async function loadStoredTokens() {
+  try {
+    const content = await fs2.readFile(TOKENS_FILE, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+async function saveTokens(tokens) {
+  await ensureConfigDir();
+  await fs2.writeFile(TOKENS_FILE, JSON.stringify(tokens, null, 2));
+}
+async function deleteTokens() {
+  try {
+    await fs2.unlink(TOKENS_FILE);
+  } catch {
+  }
+}
+async function login(credentials) {
+  const { codeVerifier, codeChallenge } = generatePKCE();
+  const authUrl = getAuthorizationUrl(codeChallenge, credentials?.clientId);
+  console.log("Opening browser for Google login...");
+  const codePromise = startCallbackServer();
+  await openBrowser(authUrl);
+  console.log("Waiting for authorization...");
+  const code = await codePromise;
+  console.log("Exchanging code for tokens...");
+  const tokenResponse = await exchangeCodeForTokens(code, codeVerifier, credentials);
+  const userInfo = await getUserInfo(tokenResponse.access_token);
+  const tokens = {
+    accessToken: tokenResponse.access_token,
+    refreshToken: tokenResponse.refresh_token || "",
+    expiresAt: Date.now() + tokenResponse.expires_in * 1e3,
+    email: userInfo.email
+  };
+  await saveTokens(tokens);
+  return tokens;
+}
+var UserAuth = class {
+  tokens = null;
+  async getAccessToken() {
+    if (!this.tokens) {
+      this.tokens = await loadStoredTokens();
+    }
+    if (!this.tokens) {
+      throw new Error('Not logged in. Run "sheets login" first.');
+    }
+    if (Date.now() >= this.tokens.expiresAt - 6e4) {
+      if (!this.tokens.refreshToken) {
+        throw new Error('Token expired and no refresh token. Run "sheets login" again.');
+      }
+      const tokenResponse = await refreshAccessToken(this.tokens.refreshToken);
+      this.tokens.accessToken = tokenResponse.access_token;
+      this.tokens.expiresAt = Date.now() + tokenResponse.expires_in * 1e3;
+      if (tokenResponse.refresh_token) {
+        this.tokens.refreshToken = tokenResponse.refresh_token;
+      }
+      await saveTokens(this.tokens);
+    }
+    return this.tokens.accessToken;
+  }
+};
+
+// src/auth/index.ts
+function createAuthProvider(config) {
+  switch (config.type) {
+    case "oauth":
+      return new OAuthAuth(config);
+    case "service-account":
+      return new ServiceAccountAuth(config);
+    case "user":
+      return new UserAuth();
+    default:
+      throw new Error(`Unknown auth type: ${config.type}`);
+  }
+}
+
+// src/api/index.ts
+function columnLetterToNumber(letters) {
+  let result = 0;
+  for (let i = 0; i < letters.length; i++) {
+    result = result * 26 + (letters.charCodeAt(i) - 64);
+  }
+  return result;
+}
+function columnNumberToLetter(num) {
+  let result = "";
+  while (num > 0) {
+    const remainder = (num - 1) % 26;
+    result = String.fromCharCode(65 + remainder) + result;
+    num = Math.floor((num - 1) / 26);
+  }
+  return result;
+}
+function parseA1Range(range) {
+  const cellRef = range.includes("!") ? range.split("!")[1] : range;
+  const firstCell = cellRef.split(":")[0];
+  const match = firstCell.match(/^([A-Z]+)(\d+)$/i);
+  if (!match) {
+    return { startRow: 1, startCol: 1 };
+  }
+  return {
+    startCol: columnLetterToNumber(match[1].toUpperCase()),
+    startRow: parseInt(match[2], 10)
+  };
+}
+var SheetsClient = class {
+  http;
+  constructor(options) {
+    const authProvider = createAuthProvider(options.auth);
+    this.http = new HttpClient({
+      getAccessToken: () => authProvider.getAccessToken()
+    });
+  }
+  /**
+   * Get a spreadsheet by ID
+   */
+  async getSpreadsheet(spreadsheetId) {
+    return this.http.request(`/spreadsheets/${spreadsheetId}`);
+  }
+  /**
+   * Get list of sheets in a spreadsheet
+   */
+  async getSheets(spreadsheetId) {
+    const spreadsheet = await this.getSpreadsheet(spreadsheetId);
+    return spreadsheet.sheets.map((sheet) => sheet.properties);
+  }
+  /**
+   * Read cell values from a range
+   */
+  async getValues(spreadsheetId, range, options) {
+    const params = {};
+    if (options?.valueRenderOption) {
+      params.valueRenderOption = options.valueRenderOption;
+    }
+    if (options?.dateTimeRenderOption) {
+      params.dateTimeRenderOption = options.dateTimeRenderOption;
+    }
+    if (options?.majorDimension) {
+      params.majorDimension = options.majorDimension;
+    }
+    const encodedRange = encodeURIComponent(range);
+    const response = await this.http.request(
+      `/spreadsheets/${spreadsheetId}/values/${encodedRange}`,
+      { params }
+    );
+    return this.normalizeValueRange(response);
+  }
+  /**
+   * Read cell formulas from a range
+   */
+  async getFormulas(spreadsheetId, range) {
+    return this.getValues(spreadsheetId, range, { valueRenderOption: "FORMULA" });
+  }
+  /**
+   * Read multiple ranges at once
+   */
+  async batchGetValues(spreadsheetId, ranges, options) {
+    const params = {
+      ranges: ranges.join(",")
+    };
+    if (options?.valueRenderOption) {
+      params.valueRenderOption = options.valueRenderOption;
+    }
+    if (options?.dateTimeRenderOption) {
+      params.dateTimeRenderOption = options.dateTimeRenderOption;
+    }
+    if (options?.majorDimension) {
+      params.majorDimension = options.majorDimension;
+    }
+    const response = await this.http.request(
+      `/spreadsheets/${spreadsheetId}/values:batchGet`,
+      { params }
+    );
+    return {
+      spreadsheetId: response.spreadsheetId,
+      valueRanges: (response.valueRanges || []).map((vr) => this.normalizeValueRange(vr))
+    };
+  }
+  /**
+   * Clear values from a single range
+   */
+  async clearValues(spreadsheetId, range) {
+    const encodedRange = encodeURIComponent(range);
+    return this.http.request(
+      `/spreadsheets/${spreadsheetId}/values/${encodedRange}:clear`,
+      { method: "POST" }
+    );
+  }
+  /**
+   * Clear values from multiple ranges
+   */
+  async batchClearValues(spreadsheetId, ranges) {
+    return this.http.request(
+      `/spreadsheets/${spreadsheetId}/values:batchClear`,
+      { method: "POST", body: { ranges } }
+    );
+  }
+  /**
+   * Write values to a range (or starting cell)
+   * Range can be "A1" or "A1:D10" - data array determines actual extent
+   */
+  async updateValues(spreadsheetId, range, values, options) {
+    const params = {
+      valueInputOption: options?.valueInputOption || "USER_ENTERED"
+    };
+    if (options?.includeValuesInResponse) {
+      params.includeValuesInResponse = "true";
+    }
+    if (options?.responseValueRenderOption) {
+      params.responseValueRenderOption = options.responseValueRenderOption;
+    }
+    if (options?.responseDateTimeRenderOption) {
+      params.responseDateTimeRenderOption = options.responseDateTimeRenderOption;
+    }
+    const encodedRange = encodeURIComponent(range);
+    return this.http.request(
+      `/spreadsheets/${spreadsheetId}/values/${encodedRange}`,
+      {
+        method: "PUT",
+        params,
+        body: {
+          majorDimension: options?.majorDimension || "ROWS",
+          values
+        }
+      }
+    );
+  }
+  /**
+   * Write to multiple ranges in one request
+   */
+  async batchUpdateValues(spreadsheetId, data, options) {
+    return this.http.request(
+      `/spreadsheets/${spreadsheetId}/values:batchUpdate`,
+      {
+        method: "POST",
+        body: {
+          valueInputOption: options?.valueInputOption || "USER_ENTERED",
+          data: data.map((d) => ({
+            range: d.range,
+            majorDimension: options?.majorDimension || "ROWS",
+            values: d.values
+          })),
+          includeValuesInResponse: options?.includeValuesInResponse || false,
+          responseValueRenderOption: options?.responseValueRenderOption,
+          responseDateTimeRenderOption: options?.responseDateTimeRenderOption
+        }
+      }
+    );
+  }
+  /**
+   * Append rows after the last row of detected table
+   */
+  async appendValues(spreadsheetId, range, values, options) {
+    const params = {
+      valueInputOption: options?.valueInputOption || "USER_ENTERED"
+    };
+    if (options?.insertDataOption) {
+      params.insertDataOption = options.insertDataOption;
+    }
+    if (options?.includeValuesInResponse) {
+      params.includeValuesInResponse = "true";
+    }
+    if (options?.responseValueRenderOption) {
+      params.responseValueRenderOption = options.responseValueRenderOption;
+    }
+    if (options?.responseDateTimeRenderOption) {
+      params.responseDateTimeRenderOption = options.responseDateTimeRenderOption;
+    }
+    const encodedRange = encodeURIComponent(range);
+    return this.http.request(
+      `/spreadsheets/${spreadsheetId}/values/${encodedRange}:append`,
+      {
+        method: "POST",
+        params,
+        body: {
+          majorDimension: options?.majorDimension || "ROWS",
+          values
+        }
+      }
+    );
+  }
+  /**
+   * Search for values matching a query across sheets
+   */
+  async searchValues(spreadsheetId, query, options) {
+    const caseSensitive = options?.caseSensitive ?? false;
+    const exactMatch = options?.exactMatch ?? false;
+    const useRegex = options?.regex ?? false;
+    const limit = options?.limit;
+    const matchType = useRegex ? "regex" : exactMatch ? "exact" : "contains";
+    let matcher;
+    if (useRegex) {
+      const flags = caseSensitive ? "" : "i";
+      const regex = new RegExp(query, flags);
+      matcher = (cellValue) => regex.test(cellValue);
+    } else if (exactMatch) {
+      if (caseSensitive) {
+        matcher = (cellValue) => cellValue === query;
+      } else {
+        const lowerQuery = query.toLowerCase();
+        matcher = (cellValue) => cellValue.toLowerCase() === lowerQuery;
+      }
+    } else {
+      if (caseSensitive) {
+        matcher = (cellValue) => cellValue.includes(query);
+      } else {
+        const lowerQuery = query.toLowerCase();
+        matcher = (cellValue) => cellValue.toLowerCase().includes(lowerQuery);
+      }
+    }
+    const matches = [];
+    const allSheets = await this.getSheets(spreadsheetId);
+    let sheetsToSearch;
+    if (options?.sheetIndex !== void 0) {
+      const sheet = allSheets.find((s) => s.index === options.sheetIndex);
+      if (!sheet) {
+        throw new Error(`Sheet index ${options.sheetIndex} not found.`);
+      }
+      sheetsToSearch = [sheet];
+    } else if (options?.gid !== void 0) {
+      const sheet = allSheets.find((s) => s.sheetId === options.gid);
+      if (!sheet) {
+        throw new Error(`Sheet with gid ${options.gid} not found.`);
+      }
+      sheetsToSearch = [sheet];
+    } else if (options?.range && options.range.includes("!")) {
+      sheetsToSearch = [];
+    } else {
+      sheetsToSearch = allSheets.filter((s) => !s.hidden);
+    }
+    if (options?.range && options.range.includes("!")) {
+      const valueRange = await this.getValues(spreadsheetId, options.range);
+      const sheetName = options.range.split("!")[0].replace(/^'|'$/g, "").replace(/''/g, "'");
+      const sheet = allSheets.find((s) => s.title === sheetName);
+      const { startRow, startCol } = parseA1Range(options.range);
+      this.collectMatches(
+        valueRange,
+        sheetName,
+        sheet?.sheetId ?? 0,
+        startRow,
+        startCol,
+        matcher,
+        matches,
+        limit
+      );
+    } else {
+      for (const sheet of sheetsToSearch) {
+        if (limit && matches.length >= limit) break;
+        const escapedTitle = sheet.title.replace(/'/g, "''");
+        const range = options?.range ? `'${escapedTitle}'!${options.range}` : `'${escapedTitle}'`;
+        try {
+          const valueRange = await this.getValues(spreadsheetId, range);
+          const { startRow, startCol } = parseA1Range(valueRange.range);
+          this.collectMatches(
+            valueRange,
+            sheet.title,
+            sheet.sheetId,
+            startRow,
+            startCol,
+            matcher,
+            matches,
+            limit
+          );
+        } catch {
+          continue;
+        }
+      }
+    }
+    return {
+      query,
+      matchType,
+      caseSensitive,
+      totalMatches: matches.length,
+      matches
+    };
+  }
+  collectMatches(valueRange, sheetName, sheetId, startRow, startCol, matcher, matches, limit) {
+    for (let rowIndex = 0; rowIndex < valueRange.values.length; rowIndex++) {
+      if (limit && matches.length >= limit) return;
+      const row = valueRange.values[rowIndex];
+      for (let colIndex = 0; colIndex < row.length; colIndex++) {
+        if (limit && matches.length >= limit) return;
+        const cell = row[colIndex];
+        const cellValue = cell.value;
+        if (cellValue == null) continue;
+        const stringValue = String(cellValue);
+        if (matcher(stringValue)) {
+          const actualRow = startRow + rowIndex;
+          const actualCol = startCol + colIndex;
+          matches.push({
+            sheet: sheetName,
+            sheetId,
+            address: columnNumberToLetter(actualCol) + actualRow,
+            row: actualRow,
+            column: actualCol,
+            value: cellValue
+          });
+        }
+      }
+    }
+  }
+  normalizeValueRange(raw) {
+    const values = (raw.values || []).map(
+      (row) => row.map((cell) => ({
+        value: cell
+      }))
+    );
+    return {
+      range: raw.range,
+      majorDimension: raw.majorDimension || "ROWS",
+      values
+    };
+  }
+};
+function createClient(options) {
+  return new SheetsClient(options);
+}
+
+// src/cli.ts
+var VERSION = "0.3.4";
+var CLAUDE_SKILL_CONTENT = `---
+name: sheets
+description: Read data from Google Sheets spreadsheets. Use this skill when the user wants to fetch, read, or analyze data from a Google Sheets URL or spreadsheet ID.
+---
+
+# Google Sheets CLI
+
+Use \`npx -y @ariadng/sheets\` to read data from Google Sheets.
+
+**Important**: Always use \`npx -y\` to skip the installation confirmation prompt.
+
+## Authentication
+
+Before reading spreadsheets, check if the user is logged in:
+
+\`\`\`bash
+npx -y @ariadng/sheets whoami
+\`\`\`
+
+If not logged in (exit code 1), ask the user to run:
+
+\`\`\`bash
+npx -y @ariadng/sheets login
+\`\`\`
+
+## Extract Spreadsheet ID
+
+From a Google Sheets URL like:
+\`https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit\`
+
+The spreadsheet ID is the string between \`/d/\` and \`/edit\`.
+
+## Commands
+
+### Get spreadsheet metadata
+\`\`\`bash
+npx -y @ariadng/sheets get SPREADSHEET_ID --format json
+\`\`\`
+
+### List all sheets
+\`\`\`bash
+npx -y @ariadng/sheets list SPREADSHEET_ID --format json
+\`\`\`
+
+### Read cell values
+\`\`\`bash
+npx -y @ariadng/sheets read SPREADSHEET_ID "Sheet1!A1:D10" --format json
+\`\`\`
+
+### Read formulas
+\`\`\`bash
+npx -y @ariadng/sheets read SPREADSHEET_ID "Sheet1!A1:D10" --formula --format json
+\`\`\`
+
+### Read by sheet index (for emoji/special character sheet names)
+\`\`\`bash
+npx -y @ariadng/sheets read SPREADSHEET_ID "A1:D10" -i 0 --format json
+\`\`\`
+
+### Read by gid (sheet ID from URL)
+\`\`\`bash
+npx -y @ariadng/sheets read SPREADSHEET_ID "A1:D10" --gid 123456789 --format json
+\`\`\`
+
+## Handling Emoji/Special Character Sheet Names
+
+Shell argument parsing can corrupt emoji characters. Use \`-i\` (sheet index) or \`--gid\` instead:
+
+1. First, list sheets to find the index and gid:
+\`\`\`bash
+npx -y @ariadng/sheets list SPREADSHEET_ID --format json
+\`\`\`
+
+2. Then read using index or gid:
+\`\`\`bash
+# By index (0-based)
+npx -y @ariadng/sheets read SPREADSHEET_ID "A1:D10" -i 3 --format json
+
+# By gid (from URL #gid=... or list output)
+npx -y @ariadng/sheets read SPREADSHEET_ID "A1:D10" --gid 745108136 --format json
+\`\`\`
+
+### Write values
+\`\`\`bash
+# Single value
+npx -y @ariadng/sheets write SPREADSHEET_ID "Sheet1!A1" "Hello"
+
+# Formula
+npx -y @ariadng/sheets write SPREADSHEET_ID "Sheet1!B10" "=SUM(B1:B9)"
+
+# JSON array (starting cell, expands automatically)
+npx -y @ariadng/sheets write SPREADSHEET_ID "Sheet1!A1" '[["Name","Age"],["Alice",30]]' --format json
+
+# From file
+npx -y @ariadng/sheets write SPREADSHEET_ID "A1" -i 0 --input data.json --format json
+
+# Store formula as text (not computed)
+npx -y @ariadng/sheets write SPREADSHEET_ID "A1" "=SUM(A:A)" --raw
+\`\`\`
+
+### Append rows
+\`\`\`bash
+# Append to table
+npx -y @ariadng/sheets append SPREADSHEET_ID "Sheet1!A:D" '[["New Item",10,5,"=B2*C2"]]' --format json
+
+# Insert rows (push existing down)
+npx -y @ariadng/sheets append SPREADSHEET_ID "Sheet1!A:A" --insert-rows '[["Inserted"]]' --format json
+\`\`\`
+
+### Clear cell values
+\`\`\`bash
+# Clear single range
+npx -y @ariadng/sheets clear SPREADSHEET_ID "Sheet1!A1:D10" --format json
+
+# Clear multiple ranges
+npx -y @ariadng/sheets clear SPREADSHEET_ID "Sheet1!A1:B5" "Sheet2!C1:D5" --format json
+
+# Clear by sheet index
+npx -y @ariadng/sheets clear SPREADSHEET_ID "A1:D10" -i 0 --format json
+\`\`\`
+
+### Search for values
+\`\`\`bash
+# Search all sheets (case-insensitive, contains)
+npx -y @ariadng/sheets search SPREADSHEET_ID "search term" --format json
+
+# Search specific range
+npx -y @ariadng/sheets search SPREADSHEET_ID "term" "Sheet1!A1:D100" --format json
+
+# Search by sheet index
+npx -y @ariadng/sheets search SPREADSHEET_ID "term" -i 0 --format json
+
+# Exact match
+npx -y @ariadng/sheets search SPREADSHEET_ID "exact value" --exact --format json
+
+# Regex search
+npx -y @ariadng/sheets search SPREADSHEET_ID "[0-9]{3}-[0-9]{4}" --regex --format json
+
+# Case-sensitive with limit
+npx -y @ariadng/sheets search SPREADSHEET_ID "Term" --case-sensitive --limit 10 --format json
+\`\`\`
+
+## Range Format
+
+- \`Sheet1!A1:D10\` - Cells A1 to D10 on Sheet1
+- \`Sheet1!A:A\` - Entire column A
+- \`Sheet1!1:1\` - Entire row 1
+- \`A1:D10\` - Range on first sheet (or use with -i/--gid)
+
+## Tips
+
+- Always use \`npx -y\` to avoid interactive prompts
+- Always use \`--format json\` for structured, parseable output
+- Use \`-i\` or \`--gid\` for sheets with emoji or special characters
+- Check authentication status before making requests
+- Handle errors gracefully and inform the user
+`;
+function parseArgs(args) {
+  const options = { format: "table", formula: false };
+  const positionals = [];
+  let command = "";
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--credentials" && args[i + 1]) {
+      options.credentials = args[++i];
+    } else if (arg === "--token" && args[i + 1]) {
+      options.token = args[++i];
+    } else if (arg === "--client" && args[i + 1]) {
+      options.client = args[++i];
+    } else if (arg === "--format" && args[i + 1]) {
+      options.format = args[++i];
+    } else if (arg === "--formula") {
+      options.formula = true;
+    } else if ((arg === "--sheet-index" || arg === "-i") && args[i + 1]) {
+      options.sheetIndex = parseInt(args[++i], 10);
+    } else if (arg === "--gid" && args[i + 1]) {
+      options.gid = parseInt(args[++i], 10);
+    } else if (arg === "--input" && args[i + 1]) {
+      options.input = args[++i];
+    } else if (arg === "--raw") {
+      options.raw = true;
+    } else if (arg === "--by-columns") {
+      options.byColumns = true;
+    } else if (arg === "--insert-rows") {
+      options.insertRows = true;
+    } else if (arg === "--case-sensitive") {
+      options.caseSensitive = true;
+    } else if (arg === "--exact") {
+      options.exact = true;
+    } else if (arg === "--regex") {
+      options.regex = true;
+    } else if (arg === "--limit" && args[i + 1]) {
+      options.limit = parseInt(args[++i], 10);
+    } else if (arg === "--version" || arg === "--help") {
+      command = arg;
+    } else if (!arg.startsWith("-")) {
+      if (!command) {
+        command = arg;
+      } else {
+        positionals.push(arg);
+      }
+    }
+  }
+  return { command, positionals, options };
+}
+function printHelp() {
+  console.log(`
+Google Sheets CLI v${VERSION}
+
+Usage:
+    sheets <command> [options]
+
+Commands:
+    login                          Login with Google account
+    logout                         Logout and remove stored tokens
+    whoami                         Show current logged-in user
+    auth <credentials-file>        Test service account authentication
+    get <spreadsheet-id>           Get spreadsheet metadata
+    list <spreadsheet-id>          List sheets in a spreadsheet
+    read <spreadsheet-id> <range>  Read cell values
+    write <spreadsheet-id> <range> [values]  Write values to cells
+    append <spreadsheet-id> <range> [values] Append rows to table
+    clear <spreadsheet-id> <range> Clear cell values (preserves formatting)
+    search <id> <query> [range]    Search for values in cells
+    install-claude-skill           Install Claude Code skill
+
+Options:
+    --client <file>        OAuth client JSON file (for login)
+    --credentials <file>   Service account JSON file
+    --token <token>        OAuth access token
+    --format <json|table>  Output format (default: table)
+    --formula              Show formulas instead of values
+    --sheet-index, -i <n>  Sheet index (use 'list' to see indexes)
+    --gid <id>             Sheet ID (from URL #gid=...)
+    --input <file>         Read values from JSON file (- for stdin)
+    --raw                  Store values exactly (formulas as text)
+    --by-columns           Write data column-by-column
+    --insert-rows          Insert rows, push existing data down (append)
+    --case-sensitive       Case-sensitive search (default: insensitive)
+    --exact                Exact match only (default: contains)
+    --regex                Treat query as regular expression
+    --limit <n>            Maximum number of results to return
+    --version              Show version number
+    --help                 Show help
+
+Examples:
+    sheets login
+    sheets login --client client_secret.json
+    sheets get 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms
+    sheets read 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms Sheet1!A1:D10
+    sheets install-claude-skill
+`);
+}
+function printVersion() {
+  console.log(VERSION);
+}
+function getRangeErrorSuggestions(errorMessage, range) {
+  const suggestions = [];
+  if (errorMessage.includes("Unable to parse range")) {
+    if (range && range.includes("\\")) {
+      suggestions.push("Detected backslash in range - this may be caused by shell escaping.");
+      suggestions.push("Try using single quotes around the entire command or avoid piping.");
+    }
+    if (range && (range.includes("[") || range.includes("]") || range.includes(" "))) {
+      suggestions.push("Sheet names with brackets or spaces need proper quoting.");
+      suggestions.push('Example: sheets read ID "[Sheet Name]!A1:B10"');
+    }
+    suggestions.push("Verify the sheet name matches exactly (including trailing spaces).");
+    suggestions.push("Use: sheets list <spreadsheet-id> to see all sheet names.");
+  }
+  return suggestions;
+}
+async function getAuthConfig(options) {
+  if (options.token) {
+    return { type: "oauth", accessToken: options.token };
+  }
+  if (options.credentials) {
+    return { type: "service-account", credentialsPath: options.credentials };
+  }
+  const storedTokens = await loadStoredTokens();
+  if (storedTokens) {
+    return { type: "user" };
+  }
+  throw new Error('Not authenticated. Run "sheets login" or use --credentials');
+}
+async function loadClientCredentials(clientPath) {
+  const content = await fs3.readFile(clientPath, "utf-8");
+  const data = JSON.parse(content);
+  const installed = data.installed || data.web;
+  if (installed) {
+    return {
+      clientId: installed.client_id,
+      clientSecret: installed.client_secret
+    };
+  }
+  if (data.clientId && data.clientSecret) {
+    return data;
+  }
+  throw new Error("Invalid client credentials file");
+}
+async function cmdLogin(options) {
+  try {
+    let credentials;
+    if (options.client) {
+      credentials = await loadClientCredentials(options.client);
+    }
+    const tokens = await login(credentials);
+    console.log(`
+Login successful! Logged in as ${tokens.email}`);
+  } catch (error) {
+    const e = error;
+    console.error(`Login failed: ${e.message}`);
+    process.exit(1);
+  }
+}
+async function cmdLogout() {
+  await deleteTokens();
+  console.log("Logged out successfully.");
+}
+async function cmdWhoami() {
+  const tokens = await loadStoredTokens();
+  if (!tokens) {
+    console.log('Not logged in. Run "sheets login" to authenticate.');
+    process.exit(1);
+  }
+  console.log(`Logged in as: ${tokens.email || "Unknown"}`);
+  const expiresAt = new Date(tokens.expiresAt);
+  const isExpired = Date.now() >= tokens.expiresAt;
+  console.log(`Token expires: ${expiresAt.toLocaleString()}${isExpired ? " (expired, will refresh)" : ""}`);
+}
+async function cmdAuth(credentialsPath) {
+  try {
+    await fs3.access(credentialsPath);
+    const content = await fs3.readFile(credentialsPath, "utf-8");
+    const credentials = JSON.parse(content);
+    if (credentials.type !== "service_account") {
+      throw new Error("Invalid credentials file: expected service_account type");
+    }
+    const client = createClient({
+      auth: { type: "service-account", credentialsPath }
+    });
+    console.log("Testing authentication...");
+    console.log(`  Project: ${credentials.project_id}`);
+    console.log(`  Client Email: ${credentials.client_email}`);
+    try {
+      await client.getSpreadsheet("test-auth-only");
+    } catch (error) {
+      const e = error;
+      if (e.code === 404 || e.code === 403) {
+        console.log("\nAuthentication successful!");
+        return;
+      }
+      throw error;
+    }
+  } catch (error) {
+    const e = error;
+    console.error(`Authentication failed: ${e.message}`);
+    process.exit(1);
+  }
+}
+async function cmdInstallClaudeSkill() {
+  const homeDir = os2.homedir();
+  const skillDir = path2.join(homeDir, ".claude", "skills", "sheets");
+  const skillFile = path2.join(skillDir, "SKILL.md");
+  try {
+    await fs3.mkdir(skillDir, { recursive: true });
+    await fs3.writeFile(skillFile, CLAUDE_SKILL_CONTENT, "utf-8");
+    console.log("Claude skill installed successfully!");
+    console.log(`Location: ${skillFile}`);
+    console.log("");
+    console.log("You can now use /sheets in Claude Code to read Google Sheets data.");
+  } catch (error) {
+    const e = error;
+    console.error(`Failed to install Claude skill: ${e.message}`);
+    process.exit(1);
+  }
+}
+async function cmdGet(spreadsheetId, options) {
+  const authConfig = await getAuthConfig(options);
+  const client = createClient({ auth: authConfig });
+  const spreadsheet = await client.getSpreadsheet(spreadsheetId);
+  if (options.format === "json") {
+    console.log(JSON.stringify(spreadsheet, null, 2));
+  } else {
+    console.log(`Title: ${spreadsheet.properties.title}`);
+    console.log(`ID: ${spreadsheet.spreadsheetId}`);
+    console.log(`Locale: ${spreadsheet.properties.locale || "N/A"}`);
+    console.log(`Timezone: ${spreadsheet.properties.timeZone || "N/A"}`);
+    console.log(`Sheets: ${spreadsheet.sheets.length}`);
+    if (spreadsheet.spreadsheetUrl) {
+      console.log(`URL: ${spreadsheet.spreadsheetUrl}`);
+    }
+  }
+}
+async function cmdList(spreadsheetId, options) {
+  const authConfig = await getAuthConfig(options);
+  const client = createClient({ auth: authConfig });
+  const sheets = await client.getSheets(spreadsheetId);
+  if (options.format === "json") {
+    console.log(JSON.stringify(sheets, null, 2));
+  } else {
+    console.log("Sheets:");
+    sheets.forEach((sheet) => {
+      const grid = sheet.gridProperties;
+      const size = grid ? ` (${grid.rowCount} x ${grid.columnCount})` : "";
+      const hidden = sheet.hidden ? " [hidden]" : "";
+      console.log(`  ${sheet.index}. ${sheet.title}${size}${hidden}`);
+      console.log(`     gid: ${sheet.sheetId}`);
+    });
+  }
+}
+async function cmdRead(spreadsheetId, range, options) {
+  const authConfig = await getAuthConfig(options);
+  const client = createClient({ auth: authConfig });
+  let resolvedRange = range;
+  if (options.sheetIndex !== void 0 || options.gid !== void 0) {
+    const sheets = await client.getSheets(spreadsheetId);
+    let targetSheet;
+    if (options.sheetIndex !== void 0) {
+      targetSheet = sheets.find((s) => s.index === options.sheetIndex);
+      if (!targetSheet) {
+        throw new Error(`Sheet index ${options.sheetIndex} not found. Use 'sheets list' to see available sheets.`);
+      }
+    } else if (options.gid !== void 0) {
+      targetSheet = sheets.find((s) => s.sheetId === options.gid);
+      if (!targetSheet) {
+        throw new Error(`Sheet with gid ${options.gid} not found. Use 'sheets list' to see available sheets.`);
+      }
+    }
+    if (targetSheet) {
+      const escapedTitle = targetSheet.title.replace(/'/g, "''");
+      resolvedRange = `'${escapedTitle}'!${range}`;
+    }
+  }
+  const valueRange = options.formula ? await client.getFormulas(spreadsheetId, resolvedRange) : await client.getValues(spreadsheetId, resolvedRange);
+  if (options.format === "json") {
+    console.log(JSON.stringify(valueRange, null, 2));
+  } else {
+    console.log(`Range: ${valueRange.range}`);
+    console.log("");
+    if (valueRange.values.length === 0) {
+      console.log("(empty)");
+      return;
+    }
+    const colWidths = [];
+    valueRange.values.forEach((row) => {
+      row.forEach((cell, i) => {
+        const len = String(cell.value ?? "").length;
+        colWidths[i] = Math.max(colWidths[i] || 0, len, 3);
+      });
+    });
+    valueRange.values.forEach((row) => {
+      const cells = row.map((cell, i) => {
+        const val = String(cell.value ?? "");
+        return val.padEnd(colWidths[i]);
+      });
+      console.log(cells.join(" | "));
+    });
+  }
+}
+async function cmdClear(spreadsheetId, ranges, options) {
+  const authConfig = await getAuthConfig(options);
+  const client = createClient({ auth: authConfig });
+  let resolvedRanges = ranges;
+  if (options.sheetIndex !== void 0 || options.gid !== void 0) {
+    const sheets = await client.getSheets(spreadsheetId);
+    let targetSheet;
+    if (options.sheetIndex !== void 0) {
+      targetSheet = sheets.find((s) => s.index === options.sheetIndex);
+      if (!targetSheet) {
+        throw new Error(`Sheet index ${options.sheetIndex} not found. Use 'sheets list' to see available sheets.`);
+      }
+    } else if (options.gid !== void 0) {
+      targetSheet = sheets.find((s) => s.sheetId === options.gid);
+      if (!targetSheet) {
+        throw new Error(`Sheet with gid ${options.gid} not found. Use 'sheets list' to see available sheets.`);
+      }
+    }
+    if (targetSheet) {
+      const escapedTitle = targetSheet.title.replace(/'/g, "''");
+      resolvedRanges = ranges.map((range) => `'${escapedTitle}'!${range}`);
+    }
+  }
+  const result = await client.batchClearValues(spreadsheetId, resolvedRanges);
+  if (options.format === "json") {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log("Cleared ranges:");
+    result.clearedRanges.forEach((range) => {
+      console.log(`  - ${range}`);
+    });
+  }
+}
+async function parseWriteValues(valuesArg, inputPath) {
+  let jsonStr;
+  if (inputPath) {
+    if (inputPath === "-") {
+      const chunks = [];
+      for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+      }
+      jsonStr = Buffer.concat(chunks).toString("utf-8").trim();
+    } else {
+      jsonStr = await fs3.readFile(inputPath, "utf-8");
+    }
+  } else if (valuesArg) {
+    jsonStr = valuesArg;
+  } else {
+    throw new Error("No values provided. Use inline JSON or --input <file>");
+  }
+  try {
+    const parsed = JSON.parse(jsonStr);
+    if (Array.isArray(parsed) && (parsed.length === 0 || Array.isArray(parsed[0]))) {
+      return parsed;
+    }
+    if (Array.isArray(parsed)) {
+      return [parsed];
+    }
+    return [[parsed]];
+  } catch {
+    return [[jsonStr]];
+  }
+}
+async function cmdWrite(spreadsheetId, range, valuesArg, options) {
+  const authConfig = await getAuthConfig(options);
+  const client = createClient({ auth: authConfig });
+  let resolvedRange = range;
+  if (options.sheetIndex !== void 0 || options.gid !== void 0) {
+    const sheets = await client.getSheets(spreadsheetId);
+    let targetSheet;
+    if (options.sheetIndex !== void 0) {
+      targetSheet = sheets.find((s) => s.index === options.sheetIndex);
+      if (!targetSheet) {
+        throw new Error(`Sheet index ${options.sheetIndex} not found.`);
+      }
+    } else if (options.gid !== void 0) {
+      targetSheet = sheets.find((s) => s.sheetId === options.gid);
+      if (!targetSheet) {
+        throw new Error(`Sheet with gid ${options.gid} not found.`);
+      }
+    }
+    if (targetSheet) {
+      const escapedTitle = targetSheet.title.replace(/'/g, "''");
+      resolvedRange = `'${escapedTitle}'!${range}`;
+    }
+  }
+  const values = await parseWriteValues(valuesArg, options.input);
+  const result = await client.updateValues(spreadsheetId, resolvedRange, values, {
+    valueInputOption: options.raw ? "RAW" : "USER_ENTERED",
+    majorDimension: options.byColumns ? "COLUMNS" : "ROWS"
+  });
+  if (options.format === "json") {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(`Updated: ${result.updatedRange}`);
+    console.log(`  Rows: ${result.updatedRows}`);
+    console.log(`  Columns: ${result.updatedColumns}`);
+    console.log(`  Cells: ${result.updatedCells}`);
+  }
+}
+async function cmdAppend(spreadsheetId, range, valuesArg, options) {
+  const authConfig = await getAuthConfig(options);
+  const client = createClient({ auth: authConfig });
+  let resolvedRange = range;
+  if (options.sheetIndex !== void 0 || options.gid !== void 0) {
+    const sheets = await client.getSheets(spreadsheetId);
+    let targetSheet;
+    if (options.sheetIndex !== void 0) {
+      targetSheet = sheets.find((s) => s.index === options.sheetIndex);
+      if (!targetSheet) {
+        throw new Error(`Sheet index ${options.sheetIndex} not found.`);
+      }
+    } else if (options.gid !== void 0) {
+      targetSheet = sheets.find((s) => s.sheetId === options.gid);
+      if (!targetSheet) {
+        throw new Error(`Sheet with gid ${options.gid} not found.`);
+      }
+    }
+    if (targetSheet) {
+      const escapedTitle = targetSheet.title.replace(/'/g, "''");
+      resolvedRange = `'${escapedTitle}'!${range}`;
+    }
+  }
+  const values = await parseWriteValues(valuesArg, options.input);
+  const result = await client.appendValues(spreadsheetId, resolvedRange, values, {
+    valueInputOption: options.raw ? "RAW" : "USER_ENTERED",
+    majorDimension: options.byColumns ? "COLUMNS" : "ROWS",
+    insertDataOption: options.insertRows ? "INSERT_ROWS" : "OVERWRITE"
+  });
+  if (options.format === "json") {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(`Appended to: ${result.updates.updatedRange}`);
+    if (result.tableRange) {
+      console.log(`  Table range: ${result.tableRange}`);
+    }
+    console.log(`  Rows: ${result.updates.updatedRows}`);
+    console.log(`  Columns: ${result.updates.updatedColumns}`);
+    console.log(`  Cells: ${result.updates.updatedCells}`);
+  }
+}
+async function cmdSearch(spreadsheetId, query, range, options) {
+  const authConfig = await getAuthConfig(options);
+  const client = createClient({ auth: authConfig });
+  const result = await client.searchValues(spreadsheetId, query, {
+    range,
+    sheetIndex: options.sheetIndex,
+    gid: options.gid,
+    caseSensitive: options.caseSensitive,
+    exactMatch: options.exact,
+    regex: options.regex,
+    limit: options.limit
+  });
+  if (options.format === "json") {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    if (result.matches.length === 0) {
+      console.log(`No matches found for "${query}"`);
+      return;
+    }
+    console.log(`Found ${result.totalMatches} match${result.totalMatches === 1 ? "" : "es"} for "${query}":`);
+    console.log("");
+    const headers = ["Sheet", "Address", "Row", "Col", "Value"];
+    const colWidths = headers.map((h) => h.length);
+    result.matches.forEach((m) => {
+      colWidths[0] = Math.max(colWidths[0], m.sheet.length);
+      colWidths[1] = Math.max(colWidths[1], m.address.length);
+      colWidths[2] = Math.max(colWidths[2], String(m.row).length);
+      colWidths[3] = Math.max(colWidths[3], String(m.column).length);
+      const valueStr = String(m.value ?? "").substring(0, 50);
+      colWidths[4] = Math.max(colWidths[4], valueStr.length);
+    });
+    console.log(headers.map((h, i) => h.padEnd(colWidths[i])).join(" | "));
+    console.log(colWidths.map((w) => "-".repeat(w)).join("-+-"));
+    result.matches.forEach((m) => {
+      const valueStr = String(m.value ?? "").substring(0, 50);
+      const row = [
+        m.sheet.padEnd(colWidths[0]),
+        m.address.padEnd(colWidths[1]),
+        String(m.row).padEnd(colWidths[2]),
+        String(m.column).padEnd(colWidths[3]),
+        valueStr.padEnd(colWidths[4])
+      ];
+      console.log(row.join(" | "));
+    });
+  }
+}
+async function main() {
+  const { command, positionals, options } = parseArgs(process.argv.slice(2));
+  if (!command || command === "help" || command === "--help") {
+    printHelp();
+    return;
+  }
+  if (command === "--version") {
+    printVersion();
+    return;
+  }
+  try {
+    switch (command) {
+      case "login":
+        await cmdLogin(options);
+        break;
+      case "logout":
+        await cmdLogout();
+        break;
+      case "whoami":
+        await cmdWhoami();
+        break;
+      case "auth": {
+        const credentialsPath = positionals[0];
+        if (!credentialsPath) {
+          console.error("Usage: sheets auth <credentials-file>");
+          process.exit(1);
+        }
+        await cmdAuth(credentialsPath);
+        break;
+      }
+      case "get": {
+        const spreadsheetId = positionals[0];
+        if (!spreadsheetId) {
+          console.error("Usage: sheets get <spreadsheet-id>");
+          process.exit(1);
+        }
+        await cmdGet(spreadsheetId, options);
+        break;
+      }
+      case "list": {
+        const spreadsheetId = positionals[0];
+        if (!spreadsheetId) {
+          console.error("Usage: sheets list <spreadsheet-id>");
+          process.exit(1);
+        }
+        await cmdList(spreadsheetId, options);
+        break;
+      }
+      case "read": {
+        const spreadsheetId = positionals[0];
+        const range = positionals[1];
+        if (!spreadsheetId || !range) {
+          console.error("Usage: sheets read <spreadsheet-id> <range>");
+          process.exit(1);
+        }
+        await cmdRead(spreadsheetId, range, options);
+        break;
+      }
+      case "write": {
+        const spreadsheetId = positionals[0];
+        const range = positionals[1];
+        const values = positionals[2];
+        if (!spreadsheetId || !range) {
+          console.error("Usage: sheets write <spreadsheet-id> <range> [values]");
+          console.error("       sheets write <id> <range> --input <file>");
+          process.exit(1);
+        }
+        await cmdWrite(spreadsheetId, range, values, options);
+        break;
+      }
+      case "append": {
+        const spreadsheetId = positionals[0];
+        const range = positionals[1];
+        const values = positionals[2];
+        if (!spreadsheetId || !range) {
+          console.error("Usage: sheets append <spreadsheet-id> <range> [values]");
+          console.error("       sheets append <id> <range> --input <file>");
+          process.exit(1);
+        }
+        await cmdAppend(spreadsheetId, range, values, options);
+        break;
+      }
+      case "clear": {
+        const spreadsheetId = positionals[0];
+        const ranges = positionals.slice(1);
+        if (!spreadsheetId || ranges.length === 0) {
+          console.error("Usage: sheets clear <spreadsheet-id> <range> [range2] [range3] ...");
+          process.exit(1);
+        }
+        await cmdClear(spreadsheetId, ranges, options);
+        break;
+      }
+      case "search": {
+        const spreadsheetId = positionals[0];
+        const query = positionals[1];
+        const range = positionals[2];
+        if (!spreadsheetId || !query) {
+          console.error("Usage: sheets search <spreadsheet-id> <query> [range]");
+          console.error('       sheets search <id> "search term" "Sheet1!A1:D100"');
+          process.exit(1);
+        }
+        await cmdSearch(spreadsheetId, query, range, options);
+        break;
+      }
+      case "install-claude-skill":
+        await cmdInstallClaudeSkill();
+        break;
+      default:
+        console.error(`Unknown command: ${command}`);
+        printHelp();
+        process.exit(1);
+    }
+  } catch (error) {
+    const e = error;
+    console.error(`Error: ${e.message}`);
+    if (e.name === "SheetsError") {
+      const sheetsErr = e;
+      if (sheetsErr.status) {
+        console.error(`Status: ${sheetsErr.status}`);
+      }
+    }
+    const range = positionals[1];
+    const suggestions = getRangeErrorSuggestions(e.message, range);
+    if (suggestions.length > 0) {
+      console.error("");
+      console.error("Suggestions:");
+      suggestions.forEach((s) => console.error(`  - ${s}`));
+    }
+    process.exit(1);
+  }
+}
+main();
+//# sourceMappingURL=cli.cjs.map