# google/clasp: managing Apps Script projects from the command line

> clasp is Google's command line tool for pulling Apps Script projects onto your machine, pushing them back, and managing deployments. It is for developers who have outgrown the script.google.com editor, but it no longer transpiles TypeScript.

**google/clasp** — 🔗 Command Line Apps Script Projects

- Repository: https://github.com/google/clasp
- Website: https://developers.google.com/apps-script/guides/clasp
- Stars: 5,849 · Forks: 512
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/google-clasp

## The problem: Apps Script projects that live only in a browser tab

Apps Script is edited at script.google.com. That is fine for a twenty-line trigger, and painful for anything larger. There is no local diff, no branch, no code review, and no way to run your usual linter over the code. The README frames the tool plainly: clasp lets you "develop your Apps Script projects locally", which in practice means checking the code into source control, collaborating with other developers, and using your own editor.

The intended audience is a developer who already writes Apps Script and has hit the ceiling of the web editor. It is not a replacement for the Apps Script runtime, and it is not a hosting platform. Everything still executes on Google's servers. clasp is the transport layer between your filesystem and that runtime. The README also carries a note worth reading before you standardise on it: this is not an officially supported Google product.

## How clasp maps a flat script project onto folders

The mechanism that matters most is the file conversion. On script.google.com a project is flat, so two files named tests/slides.gs and tests/sheets.gs exist as paths in a single namespace. Locally, clasp turns that into a tests directory containing slides.js and sheets.js. Pull writes those files to disk; push walks the directory and sends them back.

That conversion is one-way in a subtle sense: .gs becomes .js on the way down, and the file extension you see locally is the one clasp manages. The repository ships a .claspignore file at the top level, which is the mechanism for excluding files from an upload, the same role .gitignore plays for git. Configuration for the local project lives in .clasp.json, and the Apps Script manifest is appsscript.json.

Beyond file transfer, clasp manages deployment versions. The command list includes create-deployment, delete-deployment, list-deployments, create-version and list-versions. A version is an immutable snapshot; a deployment is a pointer that can be updated to a new version. The README describes the run feature as offering instant deployment, which is a different path from the versioned deployment commands and worth understanding separately before you wire either into a release process.

## Installing clasp and pushing your first script

clasp installs globally from npm. The README gives one command for this, and package.json declares an engine requirement of Node >=20.0.0, so check your Node version first.

```bash
npm install -g @google/clasp
```

After the install, the README says to enable the Google Apps Script API at script.google.com/home/usersettings. This is a separate switch from your Google account's normal OAuth consent, and commands will fail until it is on. Then authenticate:

```bash
clasp login
```

The README notes that most commands require you to run clasp login and then clasp create or clasp clone before the rest will work. To start a new project and push a file, the README's own demo does this:

```bash
clasp create "Hello"
echo 'function hello() {
  Logger.log("Hello, Apps Script!");
}' >> hello.js
clasp push
clasp deploy
```

Running clasp with no arguments prints the command list, which is the fastest way to see what your installed version actually supports. If you already have a script, clasp clone-script takes a script ID or a script URL, with an optional version number and a --rootDir flag. For iterating on a file without re-running push, clasp push accepts a --watch flag, which the README lists alongside --force.

## The 3.x break: no more TypeScript transpilation

If you used clasp 2.x with TypeScript, this is the change that will bite. The migration guide states it directly: clasp no longer transpiles TypeScript code. The reason given is that removing the built-in step allows better support for TypeScript features along with ESM modules and npm packages, because a real bundler does that job properly.

The consequence is that pushing a .ts file is no longer something clasp handles for you. The guide tells TypeScript users to transform code with a bundler such as Rollup before pushing, and links several template projects that demonstrate the setup. That is a real increase in project scaffolding for anyone whose 2.x workflow relied on clasp doing the compile.

The same guide lists command renames between 2.x and 3.x. Several 2.x commands were restructured: open became open-script, open --web became open-web-app, open --addon became open-container, and logs --open became open-logs. The login credential form changed from login --creds <file> to login -u <name> --creds <file>. The guide notes that common use cases should not be affected, but any shell script or CI job calling the old names needs updating. It also marks logs --setup as having no 3.x equivalent.

## Running clasp as an MCP server inside an AI coding agent

The README documents two ways to hand clasp's commands to an agent rather than typing them yourself. For Gemini CLI there is an extension install:

```bash
gemini extensions install https://github.com/google/clasp
```

The README says this makes clasp available as an MCP server in Gemini CLI, and that you still need the Apps Script API enabled and a completed clasp login before using it. For Claude Code there are two routes. The recommended one is a plugin install from inside Claude Code:

```bash
/plugin install @google/clasp
```

The manual route registers clasp as an MCP server directly, and the repository includes a claude-mcp.json configuration file for the JSON form:

```bash
claude mcp add clasp -- npx -y @google/clasp mcp
```

The presence of @modelcontextprotocol/sdk in the dependency list confirms the MCP server is part of the published package rather than a separate download. Treat the agent integration as a convenience wrapper over the same authenticated API calls: the login and API-enablement prerequisites are unchanged, and an agent driving deploys inherits whatever permissions your clasp login holds.

## Where clasp is the wrong tool

The clearest boundary is TypeScript. If your workflow depends on writing .ts files and having them run, clasp 3.x will not compile them, and the migration guide points you at a bundler instead. Choosing clasp without adding that bundler means either shipping untranspiled code or maintaining a build step by hand.

A second boundary is the advanced command set. The README marks tail-logs, setup-logs, list-apis, enable-api, disable-api and run-function as requiring you to add a Project ID. If you are on a default Apps Script project without an associated Google Cloud project, those commands are out of reach until you create that association. The tail-logs command in particular is the one people reach for when debugging, and it sits behind this requirement.

Third, the README's own disclaimer that this is not an officially supported Google product matters for procurement. You get an Apache-2.0 codebase and a public issue tracker, not a support contract. Teams that need a vendor to escalate to should weigh that before making clasp the only path to production for a business-critical script.

## clasp against editing in the browser, and against Google's own aside

The alternative most people actually weigh is simply not using clasp: editing directly at script.google.com. That approach has zero setup, no Node requirement, no API toggle, and no credential handling. It also has no git history, no local linting, and no scriptable deploy. The trade is roughly setup cost against workflow cost, and it flips depending on whether more than one person touches the code.

Among local toolchains, the README's migration guide links google/aside as one of several template projects for transforming TypeScript into Apps Script. The difference in approach is that aside is a starting template with a build pipeline already configured, while clasp is the transport CLI that such a template calls underneath. Picking aside means adopting someone else's directory layout and build choices; picking clasp means assembling those yourself from the bundler templates the guide lists. Neither is wrong, but they answer different questions. clasp answers "how do my files get to Google", and aside answers "what does my project look like".

## Licence, versioning and the cost of keeping up

clasp is published under Apache-2.0, and the repository carries a LICENSE file at the top level. Apache-2.0 permits commercial use and modification and includes a patent grant, but it also requires that you preserve notices and state significant changes. If you fork clasp or vendor it into an internal tool, those obligations travel with the code. That is a description of the licence text, not legal advice; have counsel review anything you redistribute.

The upgrade cost is visible in the release history. Version 3.3.0 landed in March 2026, and 3.4.0 and 3.4.1 both arrived in August 2026, with the last push to the repository on 2026-08-28. Three minor releases inside roughly six months, plus a documented 2.x to 3.x migration with renamed commands and a removed feature, tells you the project does move. Budget for reading the migration guide on major bumps, and pin the version in CI rather than tracking latest, because a rename like open to open-script breaks a pipeline silently at the point it runs. The package.json build script runs a compile step followed by an install, which is worth knowing if you build from source rather than installing the published package.

## Conclusion

Adopt clasp if your Apps Script project has outgrown the browser editor and you want it in git with a deploy step you can script. Skip it if you need TypeScript transpiled for you, since 3.x dropped that and expects a bundler such as Rollup instead. Before committing, verify that the Apps Script API is enabled at script.google.com/home/usersettings, that your Node version satisfies the >=20.0.0 engine requirement, and that any 2.x commands in your scripts have been renamed to their 3.x equivalents.

## FAQ

### How do I install clasp?

Install it globally from npm with npm install -g @google/clasp, then enable the Google Apps Script API at script.google.com/home/usersettings. The package declares a Node engine requirement of >=20.0.0.

### How do I use clasp to develop an Apps Script project?

The README says most commands require you to run clasp login and then clasp create or clasp clone first. After that you edit files locally and use clasp push to upload them and clasp pull to download changes.

### Does clasp still compile TypeScript?

No. The 2.x to 3.x migration guide states that clasp no longer transpiles TypeScript code and tells TypeScript users to transform code with a bundler such as Rollup before pushing.

### Why do clasp tail-logs and the API commands not work for me?

The README marks tail-logs, setup-logs, list-apis, enable-api, disable-api and run-function as advanced commands that require you to add your Project ID. Without an associated Google Cloud project those commands are unavailable.

### What licence is clasp released under?

clasp is published under Apache-2.0 and the repository includes a LICENSE file. Apache-2.0 permits commercial use and modification and includes a patent grant, with notice-preservation obligations attached.

## Sources

- [google/clasp on GitHub](https://github.com/google/clasp)
- [License: Apache-2.0](https://github.com/google/clasp/blob/master/LICENSE)
- [Project website](https://developers.google.com/apps-script/guides/clasp)
- [README](https://github.com/google/clasp/blob/master/README.md)
- [Releases](https://github.com/google/clasp/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/google-clasp