Use the command-line interface with clasp

  • Clasp is an open-source tool that allows you to develop and manage Apps Script projects from your terminal instead of the Apps Script editor.

  • With clasp, you can develop locally, manage deployment versions, and structure your code using directories.

  • To use clasp, you need Node.js version 4.7.4 or later installed, and you can install clasp globally using npm.

  • Common clasp operations include logging in and out, creating or cloning projects, downloading or uploading projects, managing versions and deployments, and opening the project in the Apps Script editor.

  • You can contribute to the clasp open-source project on GitHub.

To develop and manage Google Apps Script projects from your terminal rather than the Apps Script editor, use the open-source tool clasp.

The clasp codelab provides an overview of all clasp features.

Features

clasp includes the following features:

Develop locally

clasp lets you develop your Apps Script projects locally. Write code on your own computer and upload it to Apps Script when finished. You can also download existing Apps Script projects to edit them offline. Use your favorite development tools like git when building Apps Script projects.

Manage deployment versions

Create, update, and view multiple deployments of your project.

Structure code

clasp lets you organize your code into directories, which are preserved when you upload them to script.google.com. For example:

# On script.google.com:
├── tests/slides.gs
└── tests/sheets.gs

# Locally:
├── tests/
│   ├─ slides.gs
│   └─ sheets.gs

Project types

You can use clasp to manage both standalone and container-bound script projects.

Standalone projects

A standalone project appears as a separate file in your Google Drive. You can create a new standalone script using the clasp create command.

Container-bound projects

A container-bound project is attached to a Google Docs, Sheets, Slides, or Google Forms file. You can create a new container-bound script attached to a new file using the clasp create command. You can also attach a new script to an existing file using the --parentId flag.

Other project types

clasp also supports creating scripts for web apps and APIs.

Requirements

clasp is written in Node.js and distributed using the npm tool. Prior to using clasp, you must have Node.js version 20.0.0 or later installed. Installing Node.js requires administrative privileges.

Installation

Once you've installed Node.js, use the following npm command to install clasp:

npm install @google/clasp -g

After installation, use the clasp command from any directory on your computer.

Use clasp

Use clasp to handle a variety of tasks from the command line. This section describes common operations to use when developing with clasp.

Login

This command logs in and authorizes management of your Google Account's Apps Script projects. Once it is run, you are asked to sign into a Google Account where your Apps Script projects are stored.

clasp login

Logout

This command logs out of the command-line tool. Re-login using clasp login to re-authenticate with Google before continuing to use clasp.

clasp logout

Create a new Apps Script project

This command creates a new script in the current directory with an optional script title.

clasp create [scriptTitle] [--type <projectType>] [--parentId <parentId>]

This command uses the following optional parameters:

  • scriptTitle: The title of the script project.
  • --type <projectType>: The type of project to create. Allowed values are standalone, docs, sheets, slides, forms, webapp, and api.
  • --parentId <parentId>: The ID of the existing Google Drive file (Docs, Sheets, Slides, or Forms) to which the new script project should be bound.

This command also creates two files in the current directory:

  • A .clasp.json file storing the script ID.
  • An appsscript.json project manifest file containing project metadata.

Clone an existing project

This command clones an existing project in the current directory. The script must be created or shared with your Google account. You specify the script project to clone by providing its script ID. You can clone both standalone and container-bound projects.

To find the Script ID of the project:

  1. Open the Apps Script project.
  2. At the left, click Project Settings .

  3. Under IDs, copy the Script ID.

    clasp clone

Download a script project

This command downloads the Apps Script project from Google Drive to your computer's file system.

clasp pull

Upload a script project

This command uploads all of a script project's files from your computer to Drive.

clasp push

List project versions

This command lists the number and description of each of a script project's versions.

clasp versions

Deploy a published project

Deploy script projects as web apps, Google Workspace add-ons, or executables. Create deployments in the script editor, in the project manifest, or using clasp.

To deploy a project with clasp, first create an immutable version of the Apps Script project. A version is a "snapshot" of a script project and is similar to a read-only branched release.

clasp version [description]

This command displays the newly created version number. Use that number to deploy and undeploy instances of your project:

clasp deploy [version] [description]
clasp undeploy <deploymentId>

This command updates an existing deployment with a new version and description:

clasp redeploy <deploymentId> <version> <description>

List deployments

This command lists the script project's deployment IDs, versions, and their descriptions.

clasp deployments

Open the project in the Apps Script editor

This command opens a script project in the Apps Script editor. The editor launches as a new tab in your default web browser.

clasp open-script

Contribute to the clasp open-source project

Contribute to clasp on GitHub.