コンテンツにスキップ
Amethyst Amethyst クイックスタートガイド

Amethyst CLI

Amethyst CLI（ame）は、ターミナルから対応済みのAmethyst操作を実行するためのコマンドラインツールです。

ame コマンドでログイン、接続状態の確認、ワークスペース/プロジェクト確認、対応済みのSearch AnalyticsやIndex Worker操作を扱いたい場合に使います。AIクライアントからMCP経由でAmethystに接続したい場合は、Amethyst MCP を参照してください。

Amethyst CLIは、Amethystを契約しているユーザー向けに提供しています。npm、Homebrew、その他のpackage registryで一般公開しているpackageではありません。

事前準備

Section titled “事前準備”

Amethystアカウントと、少なくとも1つのワークスペースへのアクセス権が必要です。

prebuilt binaryはLinux x64/arm64、macOS x64/arm64、Windows x64向けに公開しています。別の環境で使う場合は、Node.js 20以降でJS bundle archiveを使ってください。

CLIをインストールする

Section titled “CLIをインストールする”

利用しているplatformのタブを選んでください。

shell installerでインストールします。

Terminal window
curl -fsSL https://storage.googleapis.com/amethyst-cli/releases/latest/install.sh | bash

installerは利用環境に合うmacOS binaryをダウンロードし、~/bin/ame としてインストールします。

手動ダウンロード:

手動でインストールする場合は、PATH が通ったディレクトリに ame という名前で配置します。

Terminal window
mkdir -p ~/bin
curl -L -o ~/bin/ame https://storage.googleapis.com/amethyst-cli/releases/latest/ame-darwin-arm64
chmod +x ~/bin/ame
ame status

shellで ame: command not found と表示される場合は、配置したディレクトリが PATH に含まれているか確認してください。

サインインする

Section titled “サインインする”

次のコマンドを実行します。

Terminal window
ame login

CLIがブラウザでAmethystを開きます。Amethystにサインインし、アクセスを承認したあと、localhost callbackページが表示されたらターミナルに戻ります。

接続状態を確認します。

Terminal window
ame status

サインインに成功している場合、接続先API endpointと保存済みcredentialの場所が表示されます。

対応しているコマンド

Section titled “対応しているコマンド”
コマンド内容
ame loginブラウザでAmethystにサインインします。
ame logoutサインアウトし、保存済みcredentialを削除します。
ame statusAPI接続と保存済みサインイン状態を確認します。
ame ws listサインイン中のユーザーが利用できるワークスペースを一覧します。
ame ws use <workspace-id-or-index>default workspaceを設定します。設定後は --workspace を省略できます。
ame ws currentdefault workspaceを確認します。
ame ws cleardefault workspaceを解除します。
ame projects list [--workspace <workspace-id-or-index>]ワークスペース内のプロジェクトを一覧します。default workspace設定後は --workspace を省略できます。ame ws list のあとであれば、--workspace 0 のように候補indexも指定できます。
ame projects create [--workspace <workspace-id-or-index>] --kind <project-kind> --name <name>プロジェクトを作成します。--kind には iw、sa、ua のいずれかを指定します。SA/UAプロジェクトでは --bigquery <bigquery-id> も指定します。
ame projects edit <project-id-or-index> --name <name>プロジェクト名、説明、色を更新します。
ame projects duplicate <project-id-or-index>プロジェクトを複製します。
ame projects delete <project-id-or-index>プロジェクトを削除します。
ame sa views list --project <project-id-or-index>プロジェクト内のSearch Analytics viewを一覧します。ame projects list のあとであれば、--project 1 のように候補indexも指定できます。
ame sa views create --project <project-id-or-index> --name <name>プロジェクトにSearch Analytics viewを作成します。ame projects list のあとであれば、--project 1 のように候補indexも指定できます。
ame sa views edit <view-id-or-index> --name <name>Search Analytics viewを更新します。query/url/device/countryなどの条件も指定できます。
ame sa views delete <view-id-or-index>Search Analytics viewを削除します。
ame sa data aggregated --project <project-id-or-index> --from <date> --to <date>Search Analyticsの集計済みデータを取得します。--metrics clicks,impressions、--group-by query-group、--time-group-by week などで必要な粒度に絞れます。
ame sa data aggregated --view <view-id-or-index> --from <date> --to <date>Search Analytics viewの保存条件で集計済みデータを取得します。ame sa views list のあとであれば、--view 0 のように候補indexも指定できます。
ame sa data raw --project <project-id-or-index> --from <date> --to <date>Search Analyticsのraw rowsを取得します。--group-by query,url,date、--metrics clicks,ctr、--limit 100 などを指定できます。
ame sa data raw --view <view-id-or-index> --from <date> --to <date>Search Analytics viewの保存条件でraw rowsを取得します。
ame ua views list --project <project-id-or-index>プロジェクト内のUser Analytics viewを一覧します。
ame ua views create --project <project-id-or-index> --name <name>User Analytics viewを作成します。
ame ua views edit <view-id-or-index> --name <name>User Analytics viewを更新します。
ame ua views delete <view-id-or-index>User Analytics viewを削除します。
ame ua data aggregated --project <project-id-or-index> --from <date> --to <date>User Analyticsの集計済みデータを取得します。--group-by source-medium、--time-group-by week、--limit 100 などを指定できます。
ame ua data raw --project <project-id-or-index> --from <date> --to <date>User Analyticsのraw rowsを取得します。--group-by date,source-medium、--metrics session-count,conversion-rate、--limit 100 などを指定できます。
ame ua data raw --view <view-id-or-index> --from <date> --to <date>User Analytics viewの保存条件でraw rowsを取得します。
ame ua key-events --project <project-id-or-index>User Analyticsのkey eventsとevent namesを確認します。
ame ua sessions list --project <project-id-or-index> --from <date> --to <date>User Analyticsのsessionsを一覧します。
ame ua sessions detail --project <project-id-or-index> --ga-session-id <number> --user-pseudo-id <id>User Analyticsのsession detailを確認します。
ame dashboards list [--workspace <workspace-id-or-index>]ワークスペース内のdashboardsを一覧します。default workspace設定後は --workspace を省略できます。
ame dashboards create [--workspace <workspace-id-or-index>] --name <name>Dashboardを作成します。
ame dashboards edit <dashboard-id> --name <name>Dashboardを更新します。
ame dashboards delete <dashboard-id>Dashboardを削除します。
ame dashboards items create --dashboard <dashboard-id> --type <type> --feature <feature-id>Dashboard itemを追加します。
ame dashboards items edit <dashboard-item-id> --name <name>Dashboard itemを更新します。
ame dashboards items delete <dashboard-item-id>Dashboard itemを削除します。
ame sa groups query list --project <project-id-or-index>Search Analyticsのquery groupsを一覧します。
ame sa groups query create --project <project-id-or-index> --name <name> --patterns <patterns>Search Analytics query groupを作成します。--patterns contains:brand,regex:^foo のように指定します。
ame sa groups query edit <query-group-id> --name <name>Search Analytics query groupを更新します。
ame sa groups query order --project <project-id-or-index> --ids <ids>Search Analytics query groupの並び順を更新します。
ame sa groups query delete <query-group-id>Search Analytics query groupを削除します。
ame groups url list --project <project-id-or-index>Search AnalyticsまたはUser AnalyticsのURL groupsを一覧します。
ame sa groups url create --project <project-id-or-index> --name <name> --patterns <patterns>Search Analytics URL groupを作成します。
ame sa groups url edit <url-group-id> --name <name>Search Analytics URL groupを更新します。
ame sa groups url order --project <project-id-or-index> --ids <ids>Search Analytics URL groupの並び順を更新します。
ame sa groups url delete <url-group-id>Search Analytics URL groupを削除します。
ame ua groups url create --project <project-id-or-index> --name <name> --patterns <patterns>User Analytics URL groupを作成します。
ame ua groups url edit <url-group-id> --name <name>User Analytics URL groupを更新します。
ame ua groups url order --project <project-id-or-index> --ids <ids>User Analytics URL groupの並び順を更新します。
ame ua groups url delete <url-group-id>User Analytics URL groupを削除します。
ame connections bigquery list [--workspace <workspace-id-or-index>]BigQuery connectionsを一覧します。default workspace設定後は --workspace を省略できます。
ame connections service-accounts list [--workspace <workspace-id-or-index>]Service accountsを一覧します。default workspace設定後は --workspace を省略できます。
ame connections service-accounts register [--workspace <workspace-id-or-index>]Service Account JSON keyをアップロードする設定画面を案内します。
ame connections service-accounts delete <service-account-id>Service Accountを削除します。
ame connections search-console add [--workspace <workspace-id-or-index>] --property <property>Search Console propertyを登録します。
ame connections search-console delete <property-id>Search Console propertyを削除します。
ame notifications list --workspace <workspace-id-or-index>Notificationsを一覧します。
ame iw list --project <project-id-or-index>Index Workerプロジェクト内のIndex Workerを一覧します。ame projects list のあとであれば、--project 2 のように候補indexも指定できます。
ame iw create --project <project-id-or-index> --name <name> --property <property-id> --url-type <url-type> --url <url>Index Workerを作成します。--url-type には sitemap、rss、manual のいずれかを指定します。
ame iw edit <index-worker-id-or-index> --name <name>Index Workerを更新します。
ame iw duplicate <index-worker-id-or-index>Index Workerを複製します。
ame iw move <index-worker-id-or-index> --project <project-id-or-index>Index Workerを別のIndex Workerプロジェクトへ移動します。
ame iw delete <index-worker-id-or-index>Index Workerを削除します。
ame iw status --project <project-id-or-index>Index Workerプロジェクト内の各workerについて、最新ジョブのrequest/success/failure数、crawl/index件数、crawl/index率を確認します。
ame iw jobs <index-worker-id-or-index>Index Workerの最近のジョブを確認します。ame iw list のあとであれば、0 のように候補indexも指定できます。
ame iw jobs list --worker <index-worker-id-or-index>Index Workerの最近のジョブを確認します。対話可能なterminalで --worker を省略した場合は、直前の ame iw list 候補から選べます。
ame iw export <index-worker-id-or-index>Index Worker export request dataを確認します。
ame iw rerun <index-worker-id-or-index>Index Workerを1回再実行します。

一覧コマンドのhuman-readable outputには、各項目に [0] のような候補indexが表示されます。次のコマンドでは、長いIDをコピーせずにそのindexを指定できます。--json 出力はmachine-readableなままにし、候補ラベルは追加しません。

必須の値が足りない状態で対話可能なterminalから実行した場合、CLIが不足している値を質問します。Amethyst上のデータを変更するコマンドでは、適用前に確認が表示されます。対話的な確認なしで適用したい場合だけ --yes を付けてください。

例

Section titled “例”

ワークスペースを一覧する:

Terminal window
ame ws list

ワークスペース内のプロジェクトを一覧する:

Terminal window
ame ws use <workspace-id-or-index>
ame projects list

プロジェクト内のSearch Analytics viewを一覧する:

Terminal window
ame sa views list --project <project-id-or-index>

プロジェクトにSearch Analytics viewを作成する:

Terminal window
ame sa views create --project <project-id-or-index> --name "Brand search overview"

Search Analyticsの集計済みデータを取得する:

Terminal window
ame sa data aggregated --project <project-id-or-index> --from 2026-06-01 --to 2026-06-30 --metrics clicks,impressions --time-group-by week --json

Search Analyticsのraw rowsを取得する:

Terminal window
ame sa data raw --project <project-id-or-index> --from 2026-06-01 --to 2026-06-30 --group-by query,url,date --metrics clicks,ctr --limit 100 --json

直前の ame sa views list に表示されたviewの保存条件でSearch Analyticsのraw rowsを取得する:

Terminal window
ame sa data raw --view 0 --from 2026-06-01 --to 2026-06-30 --json

User Analyticsのraw rowsを取得する:

Terminal window
ame ua data raw --project <project-id-or-index> --from 2026-06-01 --to 2026-06-30 --group-by date,source-medium --metrics session-count,conversion-rate --limit 100 --json

直前の ame ua views list に表示されたviewの保存条件でUser Analyticsのraw rowsを取得する:

Terminal window
ame ua data raw --view 0 --from 2026-06-01 --to 2026-06-30 --json

プロジェクト内のIndex Workerを一覧する:

Terminal window
ame iw list --project <project-id-or-index>

Index Workerのインデックス状況を確認する:

Terminal window
ame iw status --project <project-id-or-index>

Index Workerの最近のジョブを確認する:

Terminal window
ame iw jobs list --worker <index-worker-id-or-index>

直前の ame iw list に表示された最初のIndex Workerを再実行する:

Terminal window
ame iw rerun 0

Amethyst上のデータを変更するコマンドで確認を省略する:

Terminal window
ame iw rerun 0 --yes

JSON出力を使う

Section titled “JSON出力を使う”

scriptから扱う場合など、machine-readableな出力が必要なときは --json を使います。

Terminal window
ame status --json
ame ws list --json
ame projects list --json
ame sa views list --project <project-id-or-index> --json
ame sa data aggregated --project <project-id-or-index> --from 2026-06-01 --to 2026-06-30 --json
ame sa data raw --project <project-id-or-index> --from 2026-06-01 --to 2026-06-30 --json
ame ua data raw --project <project-id-or-index> --from 2026-06-01 --to 2026-06-30 --json
ame iw list --project <project-id-or-index> --json
ame iw status --project <project-id-or-index> --json

サインアウトまたは認可をリセットする

Section titled “サインアウトまたは認可をリセットする”

サインアウトします。

Terminal window
ame logout

保存済みcredentialを手動で削除する場合は、credential fileを削除します。

  • macOS / Linux: ~/.config/amethyst-cli/oauth-token.json
  • Windows: %APPDATA%\amethyst-cli\oauth-token.json

次回の ame login でOAuth認可が再度始まります。

トラブルシュート

Section titled “トラブルシュート”
  • ダウンロードリンクを開けない場合は、Amethystサポートにお問い合わせください。
  • ame が見つからない場合は、binaryの名前が ame になっているか、配置先ディレクトリが PATH に含まれているか確認してください。
  • ame login でブラウザが開かない場合は、ターミナル出力に表示される認可URLを手動で開いてください。
  • ame status で保存済みサインインが期限切れと表示される場合は、ame login をもう一度実行してください。
  • commandが 401 または 403 を返す場合は、ame logout でサインアウトしてから ame login を実行し、必要なワークスペースを選択しているか確認してください。

関連項目

Section titled “関連項目”