@google/clasp 3.0.6-alpha → 3.1.1

package/README.md

@@ -1,5 +1,7 @@
 # Clasp
 
+Note: This is not an officially support Google product.
+
 ![build status](https://github.com/google/clasp/actions/workflows/ci.yaml/badge.svg)
 <a href="https://coveralls.io/github/google/clasp?branch=master"><img src="https://coveralls.io/repos/github/google/clasp/badge.svg?branch=master" alt="Coverage Status"></a>
 <a href="https://www.npmjs.com/package/@google/clasp"><img src="https://img.shields.io/npm/v/@google/clasp.svg" alt="npm Version"></a>
@@ -64,6 +66,18 @@ Then enable the Google Apps Script API: https://script.google.com/home/usersetti
 
 ![Enable Apps Script API](https://user-images.githubusercontent.com/744973/54870967-a9135780-4d6a-11e9-991c-9f57a508bdf0.gif)
 
+### Installing as a Gemini CLI Extension
+
+You can install clasp as an Gemini CLI extensions using the following command:
+
+```sh
+gemini extensions install https://github.com/google/clasp
+```
+
+This makes clasp available as an MCP server in Gemini CLI. 
+
+Make sure to enable the Google Apps Script API (as explained above) and perform a `clasp login` (with your specific login parameters) before you use the extension.
+
 ## Commands
 
 The following command provide basic Apps Script project management.
@@ -78,6 +92,7 @@ clasp
 - [`clasp logout`](#logout)
 - [`clasp create-script [--title <title>] [--type <type>] [--rootDir <dir>] [--parentId <id>]`](#create)
 - [`clasp clone-script <scriptId | scriptURL> [versionNumber] [--rootDir <dir>]`](#clone)
+- [`clasp delete-script [--force]`](#delete)
 - [`clasp pull [--versionNumber]`](#pull)
 - [`clasp push [--watch] [--force]`](#push)
 - [`clasp show-file-status [--json]`](#status)
@@ -313,6 +328,7 @@ a `.claspignore` file, set this option to true.
 - `--project <file>`: Reads project settings from a file other than `.clasp.json`. Intended to support multiple deployment targets.
 - `--auth <file>`: (**DEPRECATED**) Reads credentials from a file other than `.clasprc.json`. Use the `--user` option to maintain multiple authorized accounts.
 - `--ignore <file>`: Reads ignore patterns from a file other than `.claspignore`.
+- `--json`: Show output in JSON format.
 
 ### Login
 
@@ -386,6 +402,19 @@ Clones the script project from script.google.com.
 - `clasp clone-script "https://script.google.com/d/15ImUCpyi1Jsd8yF8Z6wey_7cw793CymWTLxOqwMka3P1CzE5hQun6qiC/edit"`
 - `clasp clone-script "15ImUCpyi1Jsd8yF8Z6wey_7cw793CymWTLxOqwMka3P1CzE5hQun6qiC" --rootDir ./src`
 
+### Delete
+
+Interactively deletes a script or a project and the `.clasp.json` file. Prompt the user for confirmation if the --force option is not specified.
+
+#### Options
+
+- `-f` `--force`: Bypass any confirmation messages. It’s not a good idea to do this unless you want to run clasp from a script.
+
+#### Examples
+
+- `clasp delete-script`
+- `clasp delete-script -f`
+
 ### Pull
 
 Fetches a project from either a provided or saved script ID.
@@ -462,7 +491,8 @@ List deployments of a script.
 
 #### Examples
 
-- `clasp list-deployments`
+- `clasp list-deployments`: List all deployments for the current project
+- `clasp list-deployments [scriptId]`: List all deployments for a script ID
 
 ### Deploy
 
@@ -531,9 +561,12 @@ Creates an immutable version of the script.
 
 List versions of a script.
 
+#### Options
+
 #### Examples
 
-- `clasp list-versions`
+- `clasp list-versions`: List all versions for the current project
+- `clasp list-versions [scriptId]`: List all versions for a script ID
 
 ### List
 

package/build/src/auth/auth.js

@@ -1,3 +1,18 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// This file contains functions for initializing and managing authentication,
+// including OAuth2 client creation, authorization flows, and credential storage.
 import { readFileSync } from 'fs';
 import os from 'os';
 import path from 'path';
@@ -8,6 +23,14 @@ import { FileCredentialStore } from './file_credential_store.js';
 import { LocalServerAuthorizationCodeFlow } from './localhost_auth_code_flow.js';
 import { ServerlessAuthorizationCodeFlow } from './serverless_auth_code_flow.js';
 const debug = Debug('clasp:auth');
+/**
+ * Initializes authentication, loading credentials if available or preparing for a new auth flow.
+ * @param {InitOptions} options - Options for initializing authentication.
+ * @param {string} [options.authFilePath] - Path to the credentials file. Defaults to ~/.clasprc.json.
+ * @param {string} [options.userKey] - Identifier for the user credentials to load. Defaults to 'default'.
+ * @param {boolean} [options.useApplicationDefaultCredentials] - Whether to use Application Default Credentials.
+ * @returns {Promise<AuthInfo>} An AuthInfo object with the credential store and potentially loaded credentials.
+ */
 export async function initAuth(options) {
     var _a, _b, _c;
     const authFilePath = (_a = options.authFilePath) !== null && _a !== void 0 ? _a : path.join(os.homedir(), '.clasprc.json');
@@ -28,6 +51,12 @@ export async function initAuth(options) {
         user: (_c = options.userKey) !== null && _c !== void 0 ? _c : 'default',
     };
 }
+/**
+ * Fetches user information (email, ID) using the provided OAuth2 client.
+ * @param {OAuth2Client} credentials - An authorized OAuth2 client.
+ * @returns {Promise<{email?: string | null; id?: string | null} | undefined>}
+ * User's email and ID, or undefined if an error occurs or no data is returned.
+ */
 export async function getUserInfo(credentials) {
     debug('Fetching user info');
     const api = google.oauth2('v2');
@@ -50,8 +79,9 @@ export async function getUserInfo(credentials) {
 /**
  * Creates an an unauthorized oauth2 client given the client secret file. If no path is provided,
  * teh default client is returned.
- * @param clientSecretPath
- * @returns
+ * @param {string} [clientSecretPath] - Optional path to a client secrets JSON file.
+ * If not provided, the default clasp OAuth client is used.
+ * @returns {OAuth2Client} An unauthorized OAuth2 client instance.
  */
 export function getUnauthorizedOuth2Client(clientSecretPath) {
     if (clientSecretPath) {
@@ -61,8 +91,11 @@ export function getUnauthorizedOuth2Client(clientSecretPath) {
 }
 /**
  * Create an authorized oauth2 client from saved credentials.
- * @param userKey
- * @returns
+ * @param {CredentialStore} store - The credential store to load from.
+ * @param {string} [userKey='default'] - The user key for the credentials.
+ * @returns {Promise<OAuth2Client | undefined>} An authorized OAuth2 client if credentials
+ * are found and valid, otherwise undefined. The client is configured to auto-refresh
+ * tokens and save them back to the store.
  */
 export async function getAuthorizedOAuth2Client(store, userKey) {
     if (!userKey) {
@@ -89,12 +122,10 @@ export async function getAuthorizedOAuth2Client(store, userKey) {
     return client;
 }
 /**
- * Requests authorization to manage Apps Script projects.
- * @param {boolean} useLocalhost Uses a local HTTP server if true. Manual entry o.w.
- * @param {ClaspCredentials?} creds An optional credentials object.
- * @param {string[]} [scopes=[]] List of OAuth scopes to authorize.
- * @param {number?} redirectPort Optional custom port for the local HTTP server during the authorization process.
- *                               If not specified, a random available port will be used.
+ * Initiates an OAuth 2.0 authorization flow to obtain user consent and credentials.
+ * It selects between a local server flow or a serverless (manual) flow based on options.
+ * @param {AuthorizationOptions} options - Configuration for the authorization flow.
+ * @returns {Promise<OAuth2Client>} The authorized OAuth2 client.
  */
 export async function authorize(options) {
     let flow;
@@ -111,6 +142,13 @@ export async function authorize(options) {
     debug('Auth complete');
     return client;
 }
+/**
+ * Saves the obtained OAuth2 client credentials to the provided credential store.
+ * It also sets up an event listener on the client to save refreshed tokens.
+ * @param {CredentialStore} store - The credential store.
+ * @param {string} userKey - The user key for saving credentials.
+ * @param {OAuth2Client} oauth2Client - The OAuth2 client whose credentials are to be saved.
+ */
 async function saveOauthClientCredentials(store, userKey, oauth2Client) {
     var _a, _b;
     const savedCredentials = {
@@ -177,6 +215,12 @@ function createDefaultOAuthClient() {
     debug('Created built-in oauth client, id: %s', client._clientId);
     return client;
 }
+/**
+ * Attempts to create an OAuth2Client using Google Application Default Credentials (ADC).
+ * This is typically used in server environments where credentials can be automatically discovered.
+ * @returns {Promise<OAuth2Client | undefined>} An OAuth2Client if ADC are available and valid,
+ * otherwise undefined.
+ */
 export async function createApplicationDefaultCredentials() {
     const defaultCreds = await new GoogleAuth({
         scopes: [

package/build/src/auth/auth_code_flow.js

@@ -1,7 +1,35 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+/**
+ * Base class for managing the OAuth 2.0 Authorization Code Flow.
+ * It provides common logic for generating authorization URLs,
+ * handling user authorization, and exchanging codes for tokens.
+ * Specific implementations will override methods to define how the
+ * redirect URI is obtained and how the user is prompted for the code.
+ */
 export class AuthorizationCodeFlow {
     constructor(oauth2client) {
         this.oauth2Client = oauth2client;
     }
+    /**
+     * Initiates the authorization process.
+     * This method generates an authorization URL, prompts the user for authorization,
+     * exchanges the authorization code for tokens, and sets the credentials
+     * on the OAuth2 client.
+     * @param {string | string[]} scopes - The scope(s) for which authorization is requested.
+     * @returns {Promise<OAuth2Client>} The authorized OAuth2 client.
+     */
     async authorize(scopes) {
         const scope = Array.isArray(scopes) ? scopes.join(' ') : scopes;
         const redirectUri = await this.getRedirectUri();
@@ -18,13 +46,36 @@ export class AuthorizationCodeFlow {
         this.oauth2Client.setCredentials(tokens.tokens);
         return this.oauth2Client;
     }
+    /**
+     * Abstract method to get the redirect URI.
+     * Subclasses must implement this to provide the specific redirect URI
+     * for their authorization flow.
+     * @returns {Promise<string>} The redirect URI.
+     * @throws {Error} If not implemented by the subclass.
+     */
     async getRedirectUri() {
         throw new Error('Not implemented');
     }
+    /**
+     * Abstract method to prompt the user for the authorization code.
+     * Subclasses must implement this to define how the user is prompted
+     * (e.g., via a local server, manual input).
+     * @param {string} _authorizationUrl - The URL to which the user should be directed
+     * for authorization.
+     * @returns {Promise<string>} The authorization code obtained from the user.
+     * @throws {Error} If not implemented by the subclass.
+     */
     async promptAndReturnCode(_authorizationUrl) {
         throw new Error('Not implemented');
     }
 }
+/**
+ * Parses an authorization response URL (typically from a redirect)
+ * to extract the authorization code or an error.
+ * @param {string} url - The full URL from the authorization server's redirect.
+ * @returns {{code: string | null; error: string | null}} An object containing
+ * the 'code' if successful, or an 'error' if the authorization failed.
+ */
 export function parseAuthResponseUrl(url) {
     const urlParts = new URL(url, 'http://localhost/').searchParams;
     const code = urlParts.get('code');

package/build/src/auth/credential_store.js

@@ -1 +1,14 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
 export {};

package/build/src/auth/file_credential_store.js

@@ -1,3 +1,19 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// This file implements the `CredentialStore` interface, providing a file-based
+// mechanism for storing and managing user credentials. It handles different
+// file formats for compatibility with older versions of clasp.
 import fs from 'fs';
 function hasLegacyLocalCredentials(store) {
     return store.token && store.oauth2ClientSettings;
@@ -5,10 +21,23 @@ function hasLegacyLocalCredentials(store) {
 function hasLegacyGlobalCredentials(store) {
     return !!store.access_token;
 }
+/**
+ * Implements the `CredentialStore` interface using a local JSON file.
+ * This class handles saving, loading, and deleting OAuth 2.0 credentials
+ * for different users. It also supports migrating credentials from older
+ * clasp file formats.
+ */
 export class FileCredentialStore {
     constructor(filePath) {
         this.filePath = filePath;
     }
+    /**
+     * Saves credentials for a given user.
+     * If credentials are provided as undefined, it effectively removes the user's credentials.
+     * @param {string} user - The identifier for the user.
+     * @param {StoredCredential | undefined} credentials - The credentials to save, or undefined to clear.
+     * @returns {Promise<void>}
+     */
     async save(user, credentials) {
         const store = this.readFile();
         if (!store.tokens) {
@@ -17,6 +46,12 @@ export class FileCredentialStore {
         store.tokens[user] = credentials;
         this.writeFile(store);
     }
+    /**
+     * Deletes credentials for a specific user.
+     * If deleting the 'default' user, it also cleans up legacy credential formats.
+     * @param {string} user - The identifier for the user whose credentials are to be deleted.
+     * @returns {Promise<void>}
+     */
     async delete(user) {
         let store = this.readFile();
         if (!store.tokens) {
@@ -24,41 +59,61 @@ export class FileCredentialStore {
         }
         store.tokens[user] = undefined;
         if (user === 'default') {
-            // Remove legacy keys if default user
+            // If the 'default' user's token is deleted, we also clean up any potential
+            // top-level V1 credential keys to ensure a clean state and prevent
+            // V1 credentials from being loaded unintentionally after a V3 'default' delete.
             store = {
-                tokens: store.tokens,
+                tokens: store.tokens, // Keep other named tokens if they exist
             };
         }
         this.writeFile(store);
     }
+    /**
+     * Deletes all stored credentials by clearing the tokens map.
+     * @returns {Promise<void>}
+     */
     async deleteAll() {
         await this.writeFile({
             tokens: {},
         });
     }
+    /**
+     * Loads credentials for a given user.
+     * It supports loading credentials from the current format as well as
+     * attempting to load from legacy V1 local and global file formats
+     * if the user is 'default' and no V3 credentials are found.
+     * @param {string} user - The identifier for the user.
+     * @returns {Promise<StoredCredential | null>} The stored credentials if found, otherwise null.
+     */
     async load(user) {
         var _a, _b, _c;
         const store = this.readFile();
         const credentials = (_a = store.tokens) === null || _a === void 0 ? void 0 : _a[user];
         if (credentials) {
-            return credentials;
+            return credentials; // Modern V3 token found for the user.
         }
+        // The following logic attempts to load legacy V1 credentials
+        // ONLY if the requested user is 'default' and no V3 'default' token was found.
         if (user !== 'default') {
-            return null;
+            return null; // For non-default users, only V3 tokens are considered.
         }
+        // Check for V1 local file format (usually from older .clasprc.json in project root)
         if (hasLegacyLocalCredentials(store)) {
-            // Support previous un
+            // Convert V1 local format to StoredCredential format.
             return {
                 type: 'authorized_user',
-                ...store.token,
+                ...store.token, // Spread V1 token properties
                 client_id: (_b = store.oauth2ClientSettings) === null || _b === void 0 ? void 0 : _b.clientId,
                 client_secret: (_c = store.oauth2ClientSettings) === null || _c === void 0 ? void 0 : _c.clientSecret,
             };
         }
+        // Check for V1 global file format (usually from older ~/.clasprc.json)
         if (hasLegacyGlobalCredentials(store)) {
+            // Convert V1 global format to StoredCredential format.
+            // Note: Default client_id and client_secret are used here as global V1 didn't store them.
             return {
                 type: 'authorized_user',
-                access_token: store.access_token,
+                access_token: store.access_token, // Map V1 fields
                 refresh_token: store.refresh_token,
                 expiry_date: store.exprity_date,
                 token_type: store.token_type,

package/build/src/auth/localhost_auth_code_flow.js

@@ -1,18 +1,48 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// This file implements the `AuthorizationCodeFlow` for local development
+// environments. It starts a local HTTP server to receive the authorization
+// code after the user grants permission.
 import { createServer } from 'http';
 import open from 'open';
 import enableDestroy from 'server-destroy';
 import { intl } from '../intl.js';
 import { AuthorizationCodeFlow, parseAuthResponseUrl } from './auth_code_flow.js';
+/**
+ * Implements the Authorization Code Flow by starting a local HTTP server
+ * to act as the redirect URI. This is suitable for CLI environments
+ * where a browser can be opened and a local server can receive the
+ * authorization code.
+ */
 export class LocalServerAuthorizationCodeFlow extends AuthorizationCodeFlow {
     constructor(oauth2client) {
         super(oauth2client);
         this.port = 0;
     }
+    /**
+     * Starts a local HTTP server and returns its address as the redirect URI.
+     * The server will listen on the configured port (or a random available port if 0).
+     * @returns {Promise<string>} The local redirect URI (e.g., "http://localhost:1234").
+     * @throws {Error} If the server cannot be started (e.g., port in use).
+     */
     async getRedirectUri() {
         this.server = await new Promise((resolve, reject) => {
             const s = createServer();
-            enableDestroy(s);
+            enableDestroy(s); // Allows the server to be destroyed gracefully.
+            // Try to listen on the specified port (or a random one if port is 0).
             s.listen(this.port, () => resolve(s)).on('error', (err) => {
+                // Handle common server errors like port already in use.
                 if (err.code === 'EADDRINUSE') {
                     const msg = intl.formatMessage({ id: "smVcjx", defaultMessage: [{ type: 0, value: "Error: Port " }, { type: 1, value: "port" }, { type: 0, value: " is already in use. Please specify a different port with --redirect-port" }] }, {
                         port: this.port,
@@ -32,6 +62,15 @@ export class LocalServerAuthorizationCodeFlow extends AuthorizationCodeFlow {
         const { port } = this.server.address();
         return `http://localhost:${port}`;
     }
+    /**
+     * Prompts the user to authorize by opening the provided authorization URL
+     * in their default web browser. It then waits for the local server (started by
+     * `getRedirectUri`) to receive the callback containing the authorization code.
+     * @param {string} authorizationUrl - The URL to open for user authorization.
+     * @returns {Promise<string>} The authorization code extracted from the redirect.
+     * @throws {Error} If the server is not started, the request URL is missing, or an error
+     * parameter is present in the redirect URL.
+     */
     async promptAndReturnCode(authorizationUrl) {
         return await new Promise((resolve, reject) => {
             if (!this.server) {
@@ -43,21 +82,24 @@ export class LocalServerAuthorizationCodeFlow extends AuthorizationCodeFlow {
                     reject(new Error('Missing URL in request'));
                     return;
                 }
-                const { code, error } = parseAuthResponseUrl(request.url);
+                const { code, error } = parseAuthResponseUrl(request.url); // Extract code or error from the redirect URL.
                 if (code) {
-                    resolve(code);
+                    resolve(code); // Successfully obtained the authorization code.
                 }
                 else {
-                    reject(error);
+                    reject(error); // An error occurred during authorization.
                 }
+                // Send a simple response to the browser.
                 const msg = intl.formatMessage({ id: "ZT8LeG", defaultMessage: [{ type: 0, value: "Logged in! You may close this page." }] });
                 response.end(msg);
             });
+            // Open the authorization URL in the user's default browser.
             void open(authorizationUrl);
+            // Log the authorization URL to the console as a fallback or for visibility.
             const msg = intl.formatMessage({ id: "NbCrKh", defaultMessage: [{ type: 0, value: "`\uD83D\uDD11 Authorize clasp by visiting this url: " }, { type: 1, value: "url" }] }, {
                 url: authorizationUrl,
             });
             console.log(msg);
-        }).finally(() => { var _a; return (_a = this.server) === null || _a === void 0 ? void 0 : _a.destroy(); });
+        }).finally(() => { var _a; return (_a = this.server) === null || _a === void 0 ? void 0 : _a.destroy(); }); // Ensure the server is destroyed after completion or error.
     }
 }

package/build/src/auth/serverless_auth_code_flow.js

@@ -1,20 +1,57 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
 import inquirer from 'inquirer';
 import { intl } from '../intl.js';
 import { AuthorizationCodeFlow, parseAuthResponseUrl } from './auth_code_flow.js';
+/**
+ * Implements the Authorization Code Flow for environments where a local
+ * server cannot be started (e.g., serverless functions, some CI environments).
+ * It prompts the user to manually open the authorization URL in a browser
+ * on another device and then paste the resulting redirect URL (containing
+ * the authorization code) back into the CLI.
+ */
 export class ServerlessAuthorizationCodeFlow extends AuthorizationCodeFlow {
     constructor(oauth2client) {
         super(oauth2client);
     }
+    /**
+     * Returns a hardcoded redirect URI.
+     * This URI is typically configured in the OAuth client settings in GCP Console
+     * and is used by Google's authorization server to redirect the user after
+     * successful authorization.
+     * @returns {Promise<string>} The redirect URI.
+     */
     async getRedirectUri() {
         return 'http://localhost:8888';
     }
+    /**
+     * Prompts the user to manually open the authorization URL in a browser
+     * on another device and then paste the resulting redirect URL (which contains
+     * the authorization code) back into the CLI.
+     * @param {string} authorizationUrl - The URL to display to the user for authorization.
+     * @returns {Promise<string>} The authorization code extracted from the URL pasted by the user.
+     * @throws {Error} If the pasted URL contains an error or no code.
+     */
     async promptAndReturnCode(authorizationUrl) {
-        const prompt = intl.formatMessage({ id: "Tx67iE", defaultMessage: [{ type: 0, value: "Authorize clasp by visiting the following URL on another device: " }, { type: 1, value: "url" }, { type: 0, value: " After authorization, copy the URL in the browser. Enter the URL from your browser after completing authorization" }] }, {
+        const urlMessage = intl.formatMessage({ id: "7EHKbR", defaultMessage: [{ type: 0, value: "\uD83D\uDD11 Authorize clasp by visiting this url: " }, { type: 1, value: "url" }] }, {
             url: authorizationUrl,
         });
+        console.log(urlMessage);
+        const promptMessage = intl.formatMessage({ id: "xADuBP", defaultMessage: [{ type: 0, value: "After authorizing, copy the URL from your browser and paste it here:" }] });
         const answer = await inquirer.prompt([
             {
-                message: prompt,
+                message: promptMessage,
                 name: 'url',
                 type: 'input',
             },

package/build/src/commands/clone-script.js

@@ -1,3 +1,17 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// This file defines the 'clone-script' command for the clasp CLI.
 import { Command } from 'commander';
 import inquirer from 'inquirer';
 import { intl } from '../intl.js';
@@ -9,23 +23,28 @@ export const command = new Command('clone-script')
     .option('--rootDir <rootDir>', 'Local root directory in which clasp will store your project files.')
     .action(async function (scriptId, versionNumber) {
     var _a;
-    let clasp = this.opts().clasp;
+    const options = this.optsWithGlobals();
+    let clasp = options.clasp;
     if (clasp.project.exists()) {
         const msg = intl.formatMessage({ id: "kk5+4G", defaultMessage: [{ type: 0, value: "Project file already exists." }] });
         this.error(msg);
     }
-    const rootDir = this.opts().rootDir;
+    const rootDir = options.rootDir;
     clasp.withContentDir(rootDir !== null && rootDir !== void 0 ? rootDir : '.');
+    // Determine the script ID to clone.
+    // Priority: 1. Directly provided scriptId argument. 2. Extracted from a URL. 3. Selected from a list in interactive mode.
     if (scriptId) {
+        // If a scriptId is provided, check if it's a full URL and extract the ID.
         const match = scriptId.match(/https:\/\/script\.google\.com\/d\/([^/]+)\/.*/);
         if (match) {
-            scriptId = match[1];
+            scriptId = match[1]; // Use the extracted ID from the URL.
         }
         else {
-            scriptId = scriptId.trim();
+            scriptId = scriptId.trim(); // Otherwise, use the provided ID as is (after trimming).
         }
     }
     else if (isInteractive()) {
+        // If no scriptId is provided and the session is interactive, prompt the user to choose.
         const projects = await clasp.project.listScripts();
         const choices = projects.results.map(file => ({
             name: `${file.name.padEnd(20)} - https://script.google.com/d/${file.id}/edit`,
@@ -49,12 +68,23 @@ export const command = new Command('clone-script')
     }
     try {
         const cloningScriptMsg = intl.formatMessage({ id: "UTMHnH", defaultMessage: [{ type: 0, value: "Cloning script..." }] });
+        // Perform the cloning operation:
+        // 1. Configure the clasp instance with the determined script ID.
+        // 2. Pull the files from the remote project (optionally a specific version).
+        // 3. Update the local .clasp.json project settings file.
         const files = await withSpinner(cloningScriptMsg, async () => {
             clasp = clasp.withScriptId(scriptId);
             const files = await clasp.files.pull(versionNumber);
+            // After successfully pulling files, update the local project settings (e.g., .clasp.json)
+            // to reflect the cloned scriptId and other relevant configurations.
             clasp.project.updateSettings();
             return files;
         });
+        if (options.json) {
+            console.log(JSON.stringify({ scriptId, files: files.map(f => f.localPath) }, null, 2));
+            return;
+        }
+        // Log the paths of the cloned files.
         files.forEach(f => console.log(`└─ ${f.localPath}`));
         const successMessage = intl.formatMessage({ id: "XABSyD", defaultMessage: [{ type: 0, value: "Cloned " }, { type: 6, value: "count", options: { "=0": { value: [{ type: 0, value: "no files." }] }, one: { value: [{ type: 0, value: "one file." }] }, other: { value: [{ type: 7 }, { type: 0, value: " files" }] } }, offset: 0, pluralType: "cardinal" }, { type: 0, value: "." }] }, {
             count: files.length,
@@ -62,10 +92,12 @@ export const command = new Command('clone-script')
         console.log(successMessage);
     }
     catch (error) {
+        // Handle specific error codes from the API, like an invalid script ID.
         if (((_a = error.cause) === null || _a === void 0 ? void 0 : _a.code) === 'INVALID_ARGUMENT') {
             const msg = intl.formatMessage({ id: "jRe7cT", defaultMessage: [{ type: 0, value: "Invalid script ID." }] });
-            this.error(msg);
+            this.error(msg); // Output a user-friendly error and exit.
         }
+        // For other errors, rethrow to be caught by the global error handler.
         throw error;
     }
 });