はじめに
Google Apps Script（GAS）を手元で書くための CLI、clasp を最近入れ直しました。日本語で検索して出てくる clasp の記事は 2.x 時代のものが多く、そのとおりに叩いたら too many arguments で止まる、というのを自分で踏んだので、3.x で何が変わったのかを破壊的変更の単位で整理します。
clasp のコマンドは昔覚えたままで通じる、と思っていませんか？ コマンド名は通ります。ただし引数の書き方と、TypeScript の扱いと、.clasp.json の置き場所が変わっています。
対象読者
- 2.x 時代に clasp を使っていて、久しぶりに触ったら挙動が違って戸惑っている人
- 古い記事を参考に clasp を入れようとしている人
clasp そのものの使い方や Claude Code との組み合わせは別の記事に書いたので、この記事は「2.x から 3.x で変わった点」だけに絞ります。
参考文献
CHANGELOG の 3.0.0 の項に BREAKING CHANGES として 3 点が明記されています。この記事はその 3 点を実際に叩きながら追ったものです。
検証環境
- macOS
- Node.js v26.0.0
- clasp 3.4.1（2026-08-28 リリース。執筆時点の最新）
CHANGELOG で破壊的変更として挙がっているのは 3 つです。それに、破壊的ではないものの 3.x を象徴する追加として MCP を足した 4 点を順に見ていきます。
変更 1. コマンド名が「動詞-対象」の形に統一された
2.x では create clone deploy のように動詞だけの短い名前でしたが、3.x では「何をするか」と「何に対してか」が分かる名前に揃えられました。
| 2.x の書き方 | 3.x の正式名 | やること |
|---|---|---|
clasp create |
clasp create-script |
新規プロジェクトを作る |
clasp clone |
clasp clone-script |
既存プロジェクトを手元に持ってくる |
clasp deploy |
clasp create-deployment |
デプロイを作る |
clasp redeploy |
clasp update-deployment |
既存のデプロイを更新する |
clasp undeploy |
clasp delete-deployment |
デプロイを消す |
clasp version |
clasp create-version |
バージョンを切る |
clasp versions |
clasp list-versions |
バージョン一覧 |
clasp deployments |
clasp list-deployments |
デプロイ一覧 |
clasp run |
clasp run-function |
関数をリモート実行 |
clasp logs |
clasp tail-logs |
ログを見る |
clasp status |
clasp show-file-status |
push 対象のファイルを見る |
旧名はエイリアスとして残っていて、clasp --help にも create-deployment|deploy のように併記されます。なので clasp deploy と打っても動きます。
ただし、通るのはコマンド名までで、引数の書き方は 2.x と互換ではありません。2.x の記事によくある「バージョン番号と説明を位置引数で渡す」書き方は、3.4.1 ではエラーになります。実際に叩いてみた結果がこれです。
clasp deploy 1 "説明"
error: too many arguments for 'create-deployment'. Expected 0 arguments but got 2.
3.x では値はすべてオプションで渡します。
clasp create-deployment --versionNumber 1 --description "説明"
古い記事のコマンドをコピペして「too many arguments」が出たら、この件です。これから書くシェルスクリプトや CLAUDE.md は、新しい名前とオプション形式で統一しておくと混乱しません。
変更 2. TypeScript を clasp が変換してくれなくなった
2.x までは、.ts ファイルを置いて clasp push すると、clasp が内部で JavaScript に変換してからアップロードしてくれました。3.x ではこの機能が無くなり、.ts をそのまま push しても Apps Script 側で動くコードにはなりません。
TypeScript で書きたい場合は、次の 2 段構えになります。
- Rollup や esbuild などのバンドラで、
.tsを Apps Script が実行できる 1 つの.jsに変換する - 変換後の
.jsが置かれたディレクトリをrootDirに指定してclasp pushする
一見面倒になったようですが、バンドラを挟むことで ESM の import や npm パッケージも 1 ファイルに畳み込めるようになります。clasp の README も、TypeScript を使うならこの構成を前提にしています。注意が必要なのは、2.x 時代の「.ts を置くだけ」の記事を見て同じ手順を踏むと、push は成功したように見えて実行時に壊れる点です。
変更 3. --rootDir を付けたときの .clasp.json の置き場所
--rootDir は「ソースファイルをどのディレクトリに置くか」を指定するオプションです。たとえば clasp create-script --rootDir ./src とすると、appsscript.json や Code.js は src/ の中に置かれます。
変わったのは、そのとき .clasp.json がどこに作られるかです。
-
2.x:
.clasp.jsonもrootDirの中（src/.clasp.json）に作られていた -
3.x:
.clasp.jsonはコマンドを実行したディレクトリ（./.clasp.json）に作られ、中に"rootDir": "src"と相対パスで記録される
3.x のディレクトリ構成を書くとこうなります。
my-gas-project/
├── .clasp.json ← ここに "rootDir": "src" と書かれる
└── src/
├── appsscript.json
└── Code.js
clasp はコマンドを実行したディレクトリの .clasp.json を探すので、3.x の配置なら my-gas-project/ で clasp push すれば動きます。2.x の記事どおり src/ に移動してから push すると Project settings not found. と言われるので、「.clasp.json のある場所で叩く」と覚えておけば大丈夫です。TypeScript の構成でビルド先を dist/ にする場合も、.clasp.json はプロジェクト直下、rootDir が dist という関係になります。
変更 4. MCP サーバーとして起動できるようになった
これは破壊的変更ではなく追加です。v3.2.0 から clasp mcp で MCP サーバーとして起動でき、Claude Code などのコーディングエージェントから push / pull / プロジェクト作成をツールとして呼べます。リポジトリには Claude Code 向けの設定ファイルも同梱されています。使い方と実際に Claude Code から push させた話は、別記事「clasp 3.x で何ができるのか全部試してみた」に書きました。
まとめ
3.x で壊れるのは「コマンド名」ではなく「引数の形式」「TypeScript の扱い」「.clasp.json の場所」の 3 点です。逆に言えば、この 3 点さえ読み替えれば 2.x 時代の記事はまだ十分に役に立ちます。
私が実際に踏んだのは引数の件だけでしたが、TypeScript の構成で 2.x の手順を踏むと「push は通るのに動かない」という一番嫌なパターンになるので、TypeScript を使っている人はそこだけ先に確認してください。ほかに 3.x で引っかかった点があれば、コメントで教えてもらえると助かります。追記します。