clasp - The Apps Script CLI

1. Introduction {:#introduction}

The Apps Script CLI, or clasp, is a tool that lets you create, edit, and deploy Apps Script projects locally. It lets you create and publish web apps and add-ons for products like Sheets, Docs, Forms, and Slides from the command line. There are two ways you can develop Apps Script, using script.google.com or locally on your computer. We'll be learning how to use clasp, the command line tool for Apps Script.

Features {:#features}

• Develop Locally. clasp lets you write code on your own computer and upload it to Apps Script when you're done. You can also download existing Apps Script projects and then edit them locally. Once the code is local, you can use your favorite development tools like git to work on Apps Script projects.
• Manage Deployment Versions. Create, update, and view multiple deployments of your project.
• Structure Code. clasp automatically converts your flat project on script.google.com into folders. For example:

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

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

What you'll learn {:#what-youll-learn}

This codelab will show you how to do 3 key activities with clasp:

• How to create new Apps Script projects
• How to clone, pull, and push existing projects
• How to manage deployments of your scripts

2. Getting Started {:#getting-started}

Download the CLI {:#download-cli}

The Apps Script CLI (clasp) requires Node.js to be installed. Install Node.js.

Note: clasp uses requires Node.js >= v20.0.0. Update Node.js with these commands:

sudo npm install n -g

sudo n latest

Once you have Node, install the CLI globally (alias clasp):

npm i @google/clasp -g

3. Enable the Apps Script API {:#enable-api}

Before you can use Clasp, you must enable the Apps Script API in the Apps Script IDE.

4. Sign in {:#login}

Sign in {:#sign-in}

Try out clasp! The only command you should remember is clasp.

clasp

We've installed clasp globally on our computer, so the command should work everywhere in your file system.

Before we start using the command line tool, we must sign in. Run this command:

clasp login

or if using SSH:

clasp login --no-localhost

At this point, you are prompted to sign in to Google. Any projects you create with the CLI are associated with this Google Account.

5. Create a New Project {:#create-project}

Create a standalone project {:#create-standalone}

Start out by creating a standalone Google Apps Script project with the following command:

mkdir clasp_codelab;
cd clasp_codelab;
clasp create --title "Clasp Codelab" --type standalone;

You just created an Apps Script Project in the folder "clasp_codelab"!

Note: The clasp create command created a standalone script. This means the project is not connected to a Google Sheet, Doc, Form, or Presentation. However, we'll cover how to create a bound script in the next section.

(Optional alternative) Clone an existing project {:#clone-project}

Try creating a container-bound script for a Google Slides Add-on.

To do this, go to slides.google.com and create a new presentation. Change the presentation name to "clasp Codelab Test". In the Slides Menu bar, in the Extensions menu, choose "Apps Script.

This will open your Apps Script project at script.google.com.

Make a new directory for your project, and cd to it.

mkdir clasp_codelab_test
cd clasp_codelab_test

To clone a project, we need the Script ID. You can find this ID in the Apps Script project URL after /projects/. Copy the value and paste it in the following command:

clasp clone <scriptID>

The output should look like this...

Now you have downloaded the project in your current directory. Use your favorite editor to view the contents of Code.gs (an empty function).

6. Pull and push files {:#pull-push}

Edit code on script.google.com {:#edit-online}

Now that you're able to clone a project, you can learn how to pull and push files. This section walks through the steps to edit on the cloud using script.google.com and pull locally to your computer. Open the script in the cloud:

clasp open-script

Now that we're on the online editor, we'll edit some code online that we'll later fetch using clasp.

To create a new Apps Script file, at the left of the editor next to Files, click Add a file > Script. Enter the name utils/strings. In the newly created file, utils/strings.gs, replace the code with the following:

var world = "世界";

In Code.gs, replace the existing code with the following:

function hello() {
  Logger.log("Hello, " + world);
}

At the top, click Save .

To run the function, at the top of the editor, select hello from the function drop-down list and click Run.

The greeting appears at the bottom in the execution log.

Edit code locally {:#edit-locally}

Now go back to the command line where we last cloned the project. Our code may be out of sync with the online editor. To fix that, pull the code from our online project.

clasp pull

Now go back to the code. You should notice there's a folder for our utils. The clasp CLI automatically converts the slash character / to folders on the local file system.

In your favorite text editor, navigate to util/strings.gs and replace the variable name world with mondo. Also, update the Code.gs by replacing world with mondo. To update the updated code on script.google.com, push your edited code.

clasp push

And that's it! Your code is now updated on script.google.com.

clasp push replaces code that is on script.google.com and clasp pull replaces all files locally. For this reason, follow these guidelines:

• Don't concurrently edit code locally and on script.google.com.
• Use a version control system, like git.

7. Version and deploy {:#version-deploy}

clasp lets you manage versions and deployments. First, some vocabulary:

• Version: A "snapshot" of a script project. A version can be considered a read-only branch used for deployments.
• Deployment: A published release of a script project (often as an add-on or web app). Requires a version number.

Try creating a version of our script:

clasp create-version "First version"

Using the logged version string we created in place of [version], we can deploy the script:

clasp create-deployment 1 "First deployment"

The clasp deploy command looks at your manifest and creates a new versioned deployment. Your code is now deployed as an executable. Learn more about this in the deployments guide.

8. That's it! {:#conclusion}

We hope the Apps Script CLI is a tool to help you manage Apps Script projects.

What we've covered {:#covered}

• How to create new Apps Script projects
• How to clone, push, and pull existing projects
• How to manage deployments of your scripts

Clasp is available on GitHub and is welcome to new features and patches.

We can't wait to see what you build!