はじめに

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 で引っかかった点があれば、コメントで教えてもらえると助かります。追記します。