This is written for an AI agent to follow and execute, not a tutorial for humans to read. Goal: enable the agent to "read, modify, and push back" the user's online Apps Script code.
Why use clasp
Without clasp, the agent is blind—every change requires the user to copy it themselves, switch to the browser, paste, and save.
After connecting clasp, it becomes a complete editing loop:clasp pull pull down → modify → clasp push push back.
For projects that need repeated adjustments, this difference gets amplified many times over.
The user you're facing
By default, treat the user as someonewith no programming background(teachers, administrative staff, general users who want to automate daily work).
- Throughout, usethe user's language, don't throw around jargon.
- For places that require the user to act themselves (choosing an account, clicking allow, checking the spreadsheet),stop and explain clearly, then wait for their reply。
- On Windows, always use PowerShell,don't use
&&to chain commands(PowerShell 5.1 will throw syntax errors), use;。
🔴 Six hard red lines
1. Always use a personal Google account
clasp login whenproactively remind them to choose a personal Gmail, not a school or company Workspace account。
A managed Workspace account will return admin_policy_enforced, which issomething only the domain's administrator can resolve(they need to go into the Admin Console and whitelist clasp's OAuth Client ID). The user can't do it themselves, so don't have them keep trying there.
2. Use npx, don't install globally
Always npx @google/clasp ...。
Reason: no need to install first, and itbypasses Windows execution policy restrictions. Only when the user proactively asks to use it regularly should you suggest npm install -g @google/clasp, and be prepared to handle execution policy.
3. If it fails repeatedly, offer a fallback, don't retry endlessly
If clasp login or API authorization fails repeatedly,don't keep looping through retries. Proactively say:
"clasp is stuck here. Let's switch approaches—I'll just give you the code directly, and you paste it into script.google.com. The result is exactly the same, except you'll have to re-paste it every time you make a change afterward. Want to switch?"
clasp is an efficiency upgrade, not a requirement for producing a finished product. Prioritize preserving the finished product.
4. Don't write identifiable personal information into the cloud
Spreadsheet fieldsshould not contain real names, use non-identifying codes instead (numbers, serial numbers, etc.). If the data the user provides has a name field,proactively point it out and suggest removing it。
Also don't include ID numbers, phone numbers, addresses, or parents' contact information.
The reason is very practical: the web app's URL is usually sent out to a group of people, and that'sa public web page; and the spreadsheet itself may also be mistakenly set to readable by anyone.
5. For the web app URL, always use open-web-app --json to get it
Do not assemble the URL yourself. See step 5—scriptId、parentId、deploymentId are three different things; a typo results in "page not found" and looks like a deployment failure, which will lead you to fix the wrong place.
6. Do not overwrite an existing clasp project
Before running clasp create-script , first confirm the current folderdoes not have .clasp.json. If it does, first ask the user whether this is the project they want to connect to; do not overwrite it directly.
Pre-checks (run in order; if any fails, stop and say so)
| Check | How to do it | If it fails |
|---|---|---|
| Node version | node --version |
clasp v3 requires Node 20 or above. If lower or not found → ask them "Do you want me to install Node.js LTS for you?" |
| Apps Script API toggle | Cannot be checked via command;ask the user directly | If not enabled → give them https://script.google.com/home/usersettingsand turn on "Google Apps Script API".Tell them it takes 1–2 minutes to take effect, and do something else during this time; do not wait idly |
| Folder | Whether the current directory is the folder where they want to put the project | If not → first confirm where to create it |
Steps
1. clasp login
npx @google/clasp login
Before running, first say: "In a moment the browser will open;please choose your personal Gmail, then click Allow."
2. Verify login
npx @google/clasp show-authorized-user --json
Seeing the account = success.If you do not see it, do not continue; first handle it according to the error table.
⚠️ The command is
show-authorized-user，notlogin --status—v3 does not have that flag.
3. Create a project
Ask the user what to name it, then choose one depending on the situation:
| Scenario | Command |
|---|---|
| Want tocreatea new spreadsheet and bind it | npx @google/clasp create-script --type sheets --title "專案名" |
| Want to bind to anexistingspreadsheet/document/slides | npx @google/clasp create-script --title "專案名" --parentId "<檔案ID>" |
| Do not bind any file (standalone script) | npx @google/clasp create-script --type standalone --title "專案名" |
--parentIdis the segment in the middle of the file URL:https://docs.google.com/spreadsheets/d/{這一段}/edit- When there is
--parentId,--typewill be ignored。
Benefit of binding to a spreadsheet (container-bound): the data goes directly into a table they can understand, with no need to connect a separate database.
4. Generate code and push it up
- For the architecture, usepure GAS +
google.script.runsame-origin communication，do notusefetchto call your own/exec(there will be CORS issues). appsscript.jsonIt must contain"webapp"settings to be deployable as a web app.npx @google/clasp pushPush it up.
Common starting point: one
Code.gs(backend: read/write the spreadsheet) + oneindex.html(frontend form), user fills out the form →google.script.run.saveData(...)→ data goes into the spreadsheet.
5. Deploy as a web app
🔴 You cannot assemble the URL yourself — this is a pitfall we actually hit
Symptom: the URL given by the agent opens to "page not found" or leads to the wrong page.
Cause: in clasp there arethree URLs, three different IDs, and it is very easy to grab the wrong one:
| What to open | Command | URL source | Which ID to use |
|---|---|---|---|
| Apps Script editor | clasp open-script |
script.google.com/d/<id>/edit |
scriptId |
| bound spreadsheet | clasp open-container |
drive.google.com/open?id=<id> |
parentId |
| deployed web app | clasp open-web-app <id> |
🔴 returned by the API webApp.url |
deploymentId |
🔴 The web app URL "cannot be assembled"; you can only ask the API for it. In the clasp source codethere is no
/macros/s/...URL template at all—it is alwaysdeploymentId → 打 API 拿 entryPoints → 找 entryPointType === 'WEB_APP' → 讀出 webApp.url。So never take the
.clasp.jsoninscriptIdand use it to constructhttps://script.google.com/macros/s/<scriptId>/exec。 That ID is wrong, and what you construct will definitely be a 404. This is exactly where "page not found" comes from.
Correct approach
npx @google/clasp create-deployment --description "第一版"
Get deploymentIdfrom the output, then:
npx @google/clasp open-web-app <deploymentId> --json
--json isglobal flag, which prints the real URL as {"url": "..."} for you to read.Use the URL it prints; do not assemble it yourself.
- If you cannot get deploymentId, first
npx @google/clasp list-deployments。- you must include deploymentId. If you do not include it, clasp only shows a menu in an interactive terminal; in an agent's non-interactive environment it will directly report
Deployment ID is required.- Besides printing the URL, this commandalso opens the browser along the way, which is normal behavior.
- Return
No web app entry point found→ this deployment is not a web app type; go back and confirmappsscript.jsoninwebappsettings.
After getting the correct URL, if the user wants to send it to a group of people,generate a QR Code as a convenience and give it to them.
⚠️ The first deployment will trigger authorization,tell them first：
"A red warning will appear saying 'Google hasn't verified this app.' That is normal—that script was written by you. Please click 'Advanced' in the lower left → 'Go to 〈your project name〉 (unsafe)' → Allow."
6. Ask them to test it
Stop, ask them to actually open the URL and submit an entry, then go to the spreadsheet to confirm the data went in.Wait for them to report back before continuing.
Error handling
| Error | Meaning | What you need to do |
|---|---|---|
admin_policy_enforced |
A managed Workspace account is being used | npx @google/clasp logout, start over andemphasize choosing a personal Gmail |
User has not enabled the Apps Script API |
The toggle is not on orhas not taken effect yet | Give https://script.google.com/home/usersettings, ask them to turn it on,wait 1–2 minutesand retry |
| "Because running scripts is disabled on this system" | Windows execution policy | Using npx instead of a global install can bypass it; if it is already globally installed, use Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned |
| "Google hasn't verified this app" | Normal, your own script | Guide: Advanced → Go to <project name> (unsafe) → Allow |
node: 找不到指令 |
Node not installed | Go back to prerequisites check |
| Command name not found | clasp v3 renamed all the commands(see the mapping table below) | Use the v3 names. Old tutorials and old memory are all v2; following them will first hit "command does not exist" and then you'll start trying things at random |
| The URL you gave opens to "page not found" | 🔴 **You used scriptId to piece together /macros/s/.../exec . **The web app URL can only be obtained from the API |
clasp open-web-app <deploymentId> --json, use the URL it prints out (see step 5) |
No web app entry point found |
This deployment is not of the web app type | Confirm appsscript.json has webapp configured, redeploy |
Deployment ID is required. |
Non-interactive environment didn't carry deploymentId | First list-deployments get the ID then pass it in |
Retrying the same error twice without success → take the fallback in red line 3, don't keep burning time.
v2 → v3 command mapping
| Old (v2, stop using) | New (v3) |
|---|---|
clasp create |
clasp create-script |
clasp clone |
clasp clone-script |
clasp open |
clasp open-script |
clasp deploy |
clasp create-deployment |
clasp deployments |
clasp list-deployments |
clasp undeploy |
clasp delete-deployment |
clasp status |
clasp show-file-status |
clasp login --status |
clasp show-authorized-user |
| (none) | clasp open-container、clasp open-web-app |
Advanced: using clasp itself as MCP (experimental)
clasp v3 has a built-in stdio MCP server, which lets an agent operate Apps Script directly via tool calls instead of constantly issuing shell commands.
npx -y @google/clasp mcp
- Same prerequisites:First
clasp login, first enable the Apps Script API, it uses the same credentials. - Officially marked as EXPERIMENTAL. This skill's main flow deliberately uses only the CLI,stability first。
- Only suggest connecting it when the user proactively asks about it, or wants to maintain the Apps Script project long-term with an agent.
- For how to connect each agent, see
references/platform-notes.md。
Report back after completion
✅ clasp 已登入（帳號：<使用者的 gmail>）
✅ 專案已建立並綁定試算表「<專案名>」
✅ 已部署，網址：<用 open-web-app --json 取得的網址>
✅ QR Code 已產生（如果有需要發給多人）
📋 待你確認：打開網址填一筆，看試算表有沒有進資料
下一步可以做的：
- 加 CalendarApp／MailApp，讓它自動寫行事曆或寄通知
- 把專案資料夾納入 Git 版控
Then stop. Don't take it upon yourself to keep adding features.
Things not to do
- ❌ Don't sign in with a managed Workspace account
- ❌ Don't, when
clasp loginfails, retry infinitely—if it fails twice, propose a fallback - ❌ Don't write real names or other personal data into the spreadsheet or code
- ❌ Don't use
fetchto hit your own/exec(usegoogle.script.run） - ❌ Don't proactively create time-driven triggers for them
- ❌ Don't declare it done before the user has confirmed "the data really went into the spreadsheet"
- ❌ Don't piece together the web app URL yourself（
/macros/s/<scriptId>/execis definitely wrong), always useopen-web-app --jsonto obtain it - ❌ Don't use clasp v2's old command names (
create、open、deploy、deployments、login --status）