Usar a interface de linha de comando com o clasp

Para desenvolver e gerenciar projetos do Google Apps Script no terminal em vez do editor de script do Apps Script, use a ferramenta de código aberto clasp.

O codelab clasp oferece uma visão geral de todos os recursos do clasp.

Recursos

O clasp inclui os seguintes recursos:

Desenvolver localmente

O clasp permite desenvolver projetos do Apps Script localmente. Escreva o código no computador e faça upload para o Apps Script quando ele estiver pronto. Você também pode baixar projetos do Apps Script para editar off-line. Use suas ferramentas de desenvolvimento favoritas, como git, ao criar projetos do Apps Script.

Gerenciar versões de implantação

Crie, atualize e visualize várias implantações do projeto.

Código da estrutura

O clasp permite organizar o código em diretórios, que são preservados quando você os envia para script.google.com. Por exemplo:

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

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

Tipos de projeto

É possível usar clasp para gerenciar projetos de script autônomos e vinculados a contêineres.

Projetos independentes

Um projeto independente aparece como um arquivo separado no Google Drive. É possível criar um novo script independente usando o comando clasp create.

Projetos vinculados a contêineres

Um projeto vinculado a um contêiner é anexado a um arquivo do Google Documentos, Planilhas, Apresentações ou Google Formulários. É possível criar um novo script vinculado a um contêiner anexado a um novo arquivo usando o comando clasp create. Também é possível anexar um novo script a um arquivo existente usando a flag --parentId.

Outros tipos de projetos

O clasp também permite criar scripts para apps da Web e APIs.

Requisitos

O clasp é gravado em Node.js e distribuído usando a ferramenta npm. Antes de usar clasp, instale o Node.js versão 20.0.0 ou mais recente. A instalação do Node.js exige privilégios de administrador.

Instalação

Depois de instalar o Node.js, use o seguinte comando npm para instalar clasp:

npm install @google/clasp -g

Após a instalação, use o comando clasp em qualquer diretório do computador.

Usar clasp

Use clasp para lidar com várias tarefas na linha de comando. Esta seção descreve operações comuns a serem usadas ao desenvolver com clasp.

Login

Esse comando faz login e autoriza o gerenciamento dos projetos do Apps Script da sua Conta do Google. Depois de executado, você precisa fazer login em uma Conta do Google em que seus projetos do Apps Script estão armazenados.

clasp login

Sair

Esse comando faz logout da ferramenta de linha de comando. Faça login de novo usando clasp login para se autenticar novamente com o Google antes de continuar usando clasp.

clasp logout

Criar um novo projeto do Apps Script

Esse comando cria um novo script no diretório atual com um título opcional.

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

Esse comando usa os seguintes parâmetros opcionais:

  • scriptTitle: o título do projeto de script.
  • --type <projectType>: o tipo de projeto a ser criado. Os valores permitidos são standalone, docs, sheets, slides, forms, webapp e api.
  • --parentId <parentId>: o ID do arquivo do Google Drive (Documentos, Planilhas, Apresentações ou Formulários) a que o novo projeto de script deve ser vinculado.

Esse comando também cria dois arquivos no diretório atual:

  • Um arquivo .clasp.json que armazena o ID do script.
  • Um arquivo de manifesto do projeto appsscript.json que contém metadados do projeto.

Clone um projeto

Esse comando clona um projeto no diretório atual. O script precisa ser criado ou compartilhado com sua Conta do Google. Para especificar o projeto de script a ser clonado, forneça o ID do script. É possível clonar projetos independentes e vinculados a contêineres.

Para encontrar o ID do script do projeto:

  1. Abra o projeto do Apps Script.
  2. À esquerda, clique em Configurações do projeto .

  3. Em IDs, copie o ID do script.

    clasp clone

Baixar um projeto de script

Esse comando faz o download do projeto do Apps Script do Google Drive para o sistema de arquivos do seu computador.

clasp pull

Fazer upload de um projeto de script

Esse comando faz upload de todos os arquivos de um projeto de script do seu computador para o Drive.

clasp push

Listar versões do projeto

Esse comando lista o número e a descrição de cada uma das versões de um projeto de script.

clasp versions

Implantar um projeto publicado

Implante projetos de script como apps da Web, complementos do Google Workspace ou executáveis. Crie implantações no editor de script, no manifesto do projeto ou usando clasp.

Para implantar um projeto com clasp, primeiro crie uma versão imutável do projeto do Apps Script. Uma versão é um "instantâneo" de um projeto de script e é semelhante a uma versão ramificada somente leitura.

clasp version [description]

Esse comando mostra o número da versão recém-criada. Use esse número para implantar e remover a implantação de instâncias do seu projeto:

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

Este comando atualiza uma implantação existente com uma nova versão e descrição:

clasp redeploy <deploymentId> <version> <description>

Listar implantações

Esse comando lista os IDs de implantação, as versões e as descrições do projeto de script.

clasp deployments

Abra o projeto no editor do Apps Script.

Esse comando abre um projeto de script no editor do Apps Script. O editor é aberto como uma nova guia no navegador da Web padrão.

clasp open-script

Contribuir com o projeto de código aberto clasp

Contribua com clasp no GitHub.