search

google / clasp

🔗 Command Line Apps Script Projects
https://developers.google.com/apps-script/guides/clasp
Apache License 2.0
4.52k stars 422 forks source link
apps-script cli javascript typescript

readme

Clasp

build status Coverage Status npm Version npm Downloads

Develop Apps Script projects locally using clasp (Command Line Apps Script Projects).

clasp

To get started, try out the codelab!

You can also try clasp in Gitpod, a one-click online IDE for GitHub:

Open in Gitpod

Features

🗺️ Develop Locally: clasp allows you to develop your Apps Script projects locally. That means you can check-in your code into source control, collaborate with other developers, and use your favorite tools to develop Apps Script.

🔢 Manage Deployment Versions: Create, update, and view your multiple deployments of your project.

📁 Structure Code: clasp automatically converts your flat project on script.google.com into folders. For example:

🔷 Write Apps Script in TypeScript: Write your Apps Script projects using TypeScript features:

➡️ Run Apps Script: Execute your Apps Script from the command line. Features:

- V8 support take advantage of the performance boost of Chrome JavaScript engine:

Install

First download clasp:

npm install -g @google/clasp

Then enable the Google Apps Script API: https://script.google.com/home/usersettings

Enable Apps Script API

Commands

The following command provide basic Apps Script project management.

Note: Most of them require you to clasp login and clasp create/clone before using the rest of the commands.

clasp

Advanced Commands

NOTE: These commands require you to add your Project ID.

Clasp Run

NOTE: This command requires you to bring your own Google API credentials.

Reference

Login

Logs the user in. Saves the client credentials to a .clasprc.json file.

Options

Examples

Logout

Logs out the user by deleting client credentials.

Examples

Create

Creates a new script project. Prompts the user for the script type if not specified.

Options

Examples

These options can be combined like so:

Clone

Clones the script project from script.google.com.

Options

Examples

Pull

Fetches a project from either a provided or saved script ID. Updates local files with Apps Script project.

Options

Examples

Push

Force writes all local files to script.google.com.

Warning: Google scripts APIs do not currently support atomic nor per file operations. Thus the push command always replaces the whole content of the online project with the files being pushed.

Ignores files:

Options

Examples

Status

Lists files that will be written to the server on push.

Ignores files:

Options

Examples

Open

Opens the current directory's clasp project on script.google.com. Provide a scriptId to open a different script. Can also open web apps.

Options

Examples

Deployments

List deployments of a script.

Examples

Deploy

Creates a version and deploys a script. The response gives the deployment ID and the version of the deployment.

For web apps, each deployment has a unique URL. To update/redeploy an existing deployment, provide the deployment ID.

Options

Examples

Undeploy

Undeploys a deployment of a script.

Options

Examples

Version

Creates an immutable version of the script.

Options

Examples

Versions

List versions of a script.

Examples

List

Lists your most recent Apps Script projects.

Examples

Advanced Commands

NOTE: These commands require Project ID/credentials setup (see below).

Logs

Prints out most recent the StackDriver logs. These are logs from console.log, not Logger.log.

Options

Examples

clasp logs
ERROR Sat Apr 07 2019 10:58:31 GMT-0700 (PDT) myFunction      my log error
INFO  Sat Apr 07 2019 10:58:31 GMT-0700 (PDT) myFunction      info message

Run

Remotely executes an Apps Script function.

The complete step-by-step information on how to use clasp run is available here: Run
Below is a short summary:

  1. Log in with your credentials (clasp login --creds creds.json), see: Run - Prerequisites
  2. Deploy the Script as an API executable (Easiest done via GUI at the moment).
  3. Enable any APIs that are used by the script, see: Run - Function with Scopes
  4. Have the following in your appsscript.json. Be sure it's pushed:
"executionApi": {
  "access": "ANYONE"
}

Options

Examples

List/Enable/Disable Google APIs

List available APIs. Enables and disables Google APIs.

List APIs

Lists Google APIs that can be enabled as Advanced Services.

Enable/Disable APIs

Enables or disables APIs with the Google Cloud project. These APIs are used via services like GmailApp and Advanced Services like BigQuery.

The API name can be found using clasp apis list.

Open APIs Console

Open the Google Cloud Console where you can view and manage API access.

Help

Displays the help function.

Examples

Setting

Update .clasp.json settings file.

If settingKey is omitted it prints the current settings. If newValue is omitted it returns the current setting value.

Options

Examples

Guides

Ignore File (.claspignore)

Like .gitignore, .claspignore allows you to ignore files that you do not wish to not upload on clasp push. Steps:

  1. Create a file called .claspignore in your project's root directory.
  2. Add patterns to be excluded from clasp push. Note: The .claspignore patterns are applied by multimatch, which is different from .gitignore, especially for directories. To ignore a directory, use syntax like **/node_modules/**.

A sample .claspignore ignoring everything except the manifest and build/main.js:

**/**
!build/main.js
!appsscript.json

Note: The .claspignore patterns are applied relative from the rootDir.

If no .claspignore is specified, a default set of patterns is applied. This default set will only consider the appsscript.json manifest and any JavaScript, TypeScript and .html source files within the rootDir folder. Child folders other than .git and node_modules are processed.

# ignore all files…
**/**

# except the extensions…
!appsscript.json
!**/*.gs
!**/*.js
!**/*.ts
!**/*.html

# ignore even valid files if in…
.git/**
node_modules/**

Project Settings File (.clasp.json)

When running clone or create, a file named .clasp.json is created in the current directory to describe clasp's configuration for the current project. Example .clasp.json:

{
  "scriptId": "",
  "rootDir": "build/",
  "projectId": "project-id-xxxxxxxxxxxxxxxxxxx",
  "fileExtension": "ts",
  "filePushOrder": ["file1.ts", "file2.ts"]
}

The following configuration values can be used:

scriptId (required)

Specifies the id of the Google Script project that clasp will target.

  1. Open script url.
  2. File > Project properties > Script ID

rootDir (optional)

Specifies the local directory in which clasp will store your project files. If not specified, clasp will default to the current directory.

projectId (optional)

Specifies the id of the Google Cloud Platform project that clasp will target. You must associate Google Script project with Google Cloud Platform beforehand.

  1. Run clasp open.
  2. Click Resources > Cloud Platform project....
  3. Specify the project ID project-id-xxxxxxxxxxxxxxxxxxx.

Even if you do not set this manually, clasp will ask this via a prompt to you at the required time.

fileExtension (optional)

Specifies the file extension for local script files in your Apps Script project.

filePushOrder (optional)

Specifies the files that should be pushed first, useful for scripts that rely on order of execution. All other files are pushed after this list of files.

Troubleshooting

NodeJS Version

The library requires NodeJS version >= 12.20.0.

You can check your version of NodeJS with this command.

node -v

You can use these commands to upgrade NodeJS if necessary (not on Windows):

npm install -g npm # Update npm and npx
npx n latest # use the n package to update node

Using a Proxy

Clasp supports proxies via the Google APIs Node Module. See "Using a Proxy" and this discussion for details on how to use the proxy. This requires using the environment variables HTTP_PROXY / HTTPS_PROXY.

README Badge

Using clasp for your project? Add a README badge to show it off: clasp

[![clasp](https://img.shields.io/badge/built%20with-clasp-4285f4.svg)](https://github.com/google/clasp)

Develop clasp

See the develop guide for instructions on how to build clasp. It's not that hard!

Contributing

The main purpose of this tool is to enable local Apps Script development. If you have a core feature or use-case you'd like to see, find a GitHub issue or create a detailed proposal of the use-case. PRs are very welcome! See the issues (especially good first issue and help wanted).

How to Submit a Pull Request

  1. Look over the test cases in test/test.ts, try cases that the PR may affect.
  2. Run gts linter: npm run lint.
  3. Submit a pull request after testing your feature to make sure it works.

⚡ Powered by the Apps Script API.