/setup-clasp.en

description: "Lesson command"
duration: "~10 min"
prerequisites: ["Node.js 18 or higher installed", "Have a Google account", "Browser available"]
level: "beginner"
tags: ["setup", "gas", "clasp", "google"]
nonInteractiveMode: incompatible

Google Apps Script CLI (clasp) Setup

Step 0: Check Setup Progress

**What the AI auto-runs:** 1. Run `uv run python tools/setup_progress.py show --current setup-clasp` to display progress 2. Auto-detect existing installation status:

• Run `npx -y @google/clasp --version`
• If clasp is already available and `npx -y @google/clasp list` works, you can just run Step 5 (test) and mark it as complete
• If not available, start from Step 1

What You'll Do in This Session

| Item | Details | |------|---------| | Goal | Install clasp (Google Apps Script CLI), complete OAuth authentication, and be able to create, edit, and deploy GAS projects from your local machine | | Duration | ~10 minutes | | Prerequisites | Node.js 18+ installed, a Google account, and a browser available | | Skill Level | CLI command entry required (npx clasp execution + clasp login) | | Cost | Free |

**Session flow:** 1. Check your Node.js version 2. Verify clasp is available via npx (no global install needed, AI checks automatically) 3. Enable the Apps Script API in the browser (AI opens the browser automatically) 4. Perform OAuth authentication with clasp login 5. Functionality test (AI runs automatically)

> **Hint**: If the AI's response stops midway, type "please continue" or "it stopped" to resume.

---

Readiness Check

**AskQuestion configuration:**

{
  "title": "Pre-session confirmation",
  "questions": [{
    "id": "readiness",
    "prompt": "Are you ready?",
    "options": [
      {"id": "ready", "label": "Ready! Let's start"},
      {"id": "chrome", "label": "Automate browser operations with /chrome"},
      {"id": "check_prereq", "label": "I want to check the prerequisites"},
      {"id": "different_lesson", "label": "I want to go to a different lesson"}
    ]
  }]
}

(ready -> Proceed to Step 1) (chrome -> After opening the browser in Step 3, follow the "Automating with Chrome integration" section for automatic execution) (check_prereq -> Guide: "You're ready if you have Node.js 18+ installed and can log into a browser with a Google account. Node.js will be checked in the next step.") (different_lesson -> Display module list)

---

Step 1: Check Node.js

**What the AI does:** 1. Run `node --version` to check the Node.js version 2. Verify that the version is 18 or higher

**If Node.js is 18 or higher:** Display "Confirmed Node.js v{version}. Moving to Step 2." and proceed to Step 2

**If Node.js is not installed or below 18 — AskQuestion:**

{
  "title": "Step 1: Node.js installation required",
  "questions": [{
    "id": "node_status",
    "prompt": "clasp requires Node.js 18 or higher. Please install it from the following URL:\n\nhttps://nodejs.org/\n\nClick the 'LTS' version download button and follow the installer instructions.\n\nAfter installation, restart your terminal.",
    "options": [
      {"id": "installed", "label": "I installed Node.js"},
      {"id": "help", "label": "I don't know how to install it"},
      {"id": "skip", "label": "Set up later (skip)"}
    ]
  }]
}

(installed -> Re-run `node --version` to verify. If 18+, proceed to Step 2) (help -> Guide: "Go to https://nodejs.org/ and click the green 'LTS' button to download. Open the downloaded file and follow the on-screen instructions to complete the installation.") (skip -> Guide: "clasp setup requires Node.js. Please re-run /setup-clasp later." and end)

---

Step 2: Verify clasp availability

**What the AI auto-runs:** 1. Run `npx -y @google/clasp --version` to verify clasp is available via npx 2. Check the execution result

> **Note**: No global installation (`npm install -g`) is needed. Using `npx @google/clasp` lets you always run the latest version of clasp without installing it.

**On successful verification:** Display "clasp is available via npx. Moving to Step 3." and proceed to Step 3

**If npx execution fails — AskQuestion:**

{
  "title": "Step 2: npx execution error",
  "questions": [{
    "id": "npx_error",
    "prompt": "An error occurred running npx @google/clasp. Please check the following:\n\n1. Whether Node.js and npm are correctly installed\n2. Whether your network connection is active (npx downloads the package on first run)",
    "options": [
      {"id": "retry", "label": "Try again"},
      {"id": "check_node", "label": "Go back to Node.js check (Step 1)"},
      {"id": "help", "label": "I want to know other methods"}
    ]
  }]
}

(retry -> Re-run `npx -y @google/clasp --version`. If successful, proceed to Step 3) (check_node -> Go back to Step 1) (help -> Guide: "Check your network connection. If you're behind a proxy, you may need to configure npm proxy settings.")

---

Step 3: Enable the Apps Script API

**What the AI does:** 1. Auto-detect the OS (Mac / Windows / Linux) 2. Run the following command to open the browser automatically:

# Mac:
open https://script.google.com/home/usersettings
# Windows:
start https://script.google.com/home/usersettings
# Linux:
xdg-open https://script.google.com/home/usersettings

**After the browser opens, display the following AskQuestion:**

{
  "title": "Step 3: Enable the Apps Script API",
  "questions": [{
    "id": "api_status",
    "prompt": "Did the browser open? Follow these steps to enable the Apps Script API:\n\n1. Log in with your Google account\n2. Find the 'Google Apps Script API' toggle switch\n3. Turn the toggle to 'On'\n\n* If it's already on, leave it as is.\n\nDone?",
    "options": [
      {"id": "done", "label": "I enabled the API! (or it was already on)"},
      {"id": "browser_not_open", "label": "The browser didn't open"},
      {"id": "no_toggle", "label": "I can't find the toggle switch"},
      {"id": "org_restriction", "label