# Amethyst CLI (`ame`)

`cli/` は Amethyst を terminal から操作するための人間向け CLI package です。

## Install / Use

最重要ポイント:

- 現在の `amethyst-cli` は npm registry に publish していません
- `pnpm add -g` / `npm install -g` で install する package ではありません
- 使い方は `repo から build して実行` するか、`package した binary/archive を配布して使う` のどちらかです

通常は single binary を配布して使うのが最も分かりやすいです。

### 1. Local repo から使う

開発中に最も簡単な使い方です。

```bash
cd /path/to/amethyst
pnpm install
pnpm --filter amethyst-cli build
node cli/dist/index.mjs status
```

login も同様です。

```bash
node cli/dist/index.mjs login
```

### 2. Single binary として install する

配布向けの推奨パスです。

build:

```bash
cd /path/to/amethyst
pnpm install
pnpm --filter amethyst-cli package:binary
```

生成物:

- `cli/release/ame-<platform>-<arch>`
- `cli/release/ame-<platform>-<arch>-<short-sha>.tar.gz`

macOS / Linux では、生成された binary を `ame` という名前で `PATH` の通った場所へ置くと、そのまま `ame ...` で使えます。

```bash
cp cli/release/ame-<platform>-<arch> ~/bin/ame
chmod +x ~/bin/ame
ame status
```

### 3. JS bundle archive を展開して使う

Node.js が入っている環境向けです。

build:

```bash
cd /path/to/amethyst
pnpm install
pnpm --filter amethyst-cli package
```

生成物:

- `cli/release/ame-<short-sha>.tar.gz`

install / run:

```bash
tar -xzf cli/release/ame-<short-sha>.tar.gz
node ame/dist/index.mjs status
```

この archive は `single executable` ではなく、`dist/index.mjs` を含む JS bundle です。
そのため展開後は `node ame/dist/index.mjs ...` で実行します。

### 4. まだできない install 形式

今の PR 時点では次は未対応です。

- Homebrew install
- `pnpm add -g amethyst-cli`
- `npm install -g amethyst-cli`
- registry からの versioned publish/install

必要なら別 PR で `bin` 定義、publish 方針、release 導線を追加します。

ここには次を置きます。

- OAuth login / logout / status
- 人間向け command surface
- GraphQL API 経由の curated command 実行
- 配布用 archive / single binary packaging

MCP server/runtime と MCP client 向けの配布は `mcp/` package が持ちます。このCLIはMCP serverをserveせず、MCP tool名の直接実行も提供しません。

## Setup

repo から直接使う開発者向けの最小 setup です。

```bash
cd /path/to/amethyst
pnpm install
pnpm --filter amethyst-cli typecheck
pnpm --filter amethyst-cli test
pnpm --filter amethyst-cli build
```

## Local Development

contributor 向けに、CLI は packaging 前でも `dev` script から直接実行できます。

```bash
cd /path/to/amethyst
pnpm --filter amethyst-cli dev status
pnpm --filter amethyst-cli dev ws list
pnpm --filter amethyst-cli dev ws use <workspace-id-or-index>
pnpm --filter amethyst-cli dev projects list
pnpm --filter amethyst-cli dev sa views create --project <project-id-or-index> --name "Brand search overview"
pnpm --filter amethyst-cli dev sa data aggregated --project <project-id-or-index> --from 2026-06-01 --to 2026-06-30 --json
pnpm --filter amethyst-cli dev sa data raw --project <project-id-or-index> --from 2026-06-01 --to 2026-06-30 --group-by query,url,date --json
pnpm --filter amethyst-cli dev ua data raw --project <project-id-or-index> --from 2026-06-01 --to 2026-06-30 --group-by date,source-medium --json
pnpm --filter amethyst-cli dev ua event-params --project <project-id-or-index>
pnpm --filter amethyst-cli dev connections bigquery event-params set <bigquery-id> --keys page_type,campaign_id
pnpm --filter amethyst-cli dev iw list --project <project-id-or-index>
pnpm --filter amethyst-cli dev iw status --project <project-id-or-index>
pnpm --filter amethyst-cli dev iw jobs <index-worker-id-or-index>
pnpm --filter amethyst-cli dev iw rerun <index-worker-id-or-index>
```

## Commands

command surface 自体は local development / built CLI / packaged binary で共通です。
single binary を install 済みの場合は `ame ...`、repo root から local build を直接試す場合は `node cli/dist/index.mjs ...` で同じ command surface を使えます。

local development:

```bash
pnpm --filter amethyst-cli dev login
pnpm --filter amethyst-cli dev ws use <workspace-id-or-index>
pnpm --filter amethyst-cli dev projects list
pnpm --filter amethyst-cli dev sa views create --project <project-id-or-index> --name "Brand search overview"
pnpm --filter amethyst-cli dev sa data aggregated --project <project-id-or-index> --from 2026-06-01 --to 2026-06-30 --metrics clicks,impressions --json
pnpm --filter amethyst-cli dev sa data raw --project <project-id-or-index> --from 2026-06-01 --to 2026-06-30 --group-by query,url,date --limit 100 --json
pnpm --filter amethyst-cli dev ua data raw --project <project-id-or-index> --from 2026-06-01 --to 2026-06-30 --group-by date,source-medium --limit 100 --json
pnpm --filter amethyst-cli dev ua data aggregated --project <project-id-or-index> --from 2026-06-01 --to 2026-06-30 --event-params page_type:EQUALS:pricing --json
```

built CLI:

```bash
node cli/dist/index.mjs login
node cli/dist/index.mjs ws use <workspace-id-or-index>
node cli/dist/index.mjs projects list
```

packaged CLI:

```bash
ame login
ame status
ame ws list
ame ws use <workspace-id-or-index>
ame projects list
ame sa views create --project <project-id-or-index> --name "Brand search overview"
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 --group-by query,url,date --json
ame ua data aggregated --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 --group-by date,source-medium --json
ame ua key-events --project <project-id-or-index>
ame ua key-events set --project <project-id-or-index> --events purchase,sign_up
ame ua event-params --project <project-id-or-index>
ame connections bigquery event-params set <bigquery-id> --keys page_type,campaign_id
ame connections bigquery event-params set <bigquery-id> --keys clear
ame ua sessions list --project <project-id-or-index> --from 2026-06-01 --to 2026-06-30 --json
ame dashboards list
ame dashboards create --name "Executive"
ame dashboards edit <dashboard-id> --name "Executive"
ame dashboards delete <dashboard-id>
ame dashboards items create --dashboard <dashboard-id> --type sa-click --feature <feature-id>
ame dashboards items edit <dashboard-item-id> --name "Clicks"
ame dashboards items delete <dashboard-item-id>
ame sa groups query list --project <project-id-or-index>
ame sa groups query create --project <project-id-or-index> --name "Brand" --patterns contains:brand
ame sa groups query edit <query-group-id> --name "Brand"
ame sa groups query order --project <project-id-or-index> --ids <query-group-id>,<query-group-id>
ame sa groups query delete <query-group-id>
ame groups url list --project <project-id-or-index>
ame sa groups url create --project <project-id-or-index> --name "Docs" --patterns contains:/docs
ame ua groups url create --project <project-id-or-index> --name "Docs" --patterns contains:/docs
ame connections bigquery list
ame connections service-accounts list
ame connections service-accounts register
ame connections search-console add --property https://example.com/
ame notifications list --workspace <workspace-id-or-index>
ame iw list --project <project-id-or-index>
ame iw create --project <project-id-or-index> --name "Worker" --property <property-id> --url-type sitemap --url https://example.com/sitemap.xml
ame iw edit <index-worker-id-or-index> --name "Worker"
ame iw duplicate <index-worker-id-or-index>
ame iw move <index-worker-id-or-index> --project <project-id-or-index>
ame iw delete <index-worker-id-or-index>
ame iw status --project <project-id-or-index>
ame iw jobs <index-worker-id-or-index>
ame iw export <index-worker-id-or-index>
ame iw rerun <index-worker-id-or-index>
```

補足:

- CLI command がユーザー向けの正規インターフェースです。`list_workspaces` などの operation 名は実装内部の識別子として扱います。
- `ws use <workspace-id-or-index>` は default workspace を設定する
- default workspace 設定後は `projects list`、`dashboards list`、`connections bigquery list` などの `--workspace` を省略できる
- `sa data aggregated --view <view-id-or-index> --from <date> --to <date>` / `sa data raw --view <view-id-or-index> --from <date> --to <date>` は Search Analytics view の保存条件を使う
- `ua data raw --view <view-id-or-index> --from <date> --to <date>` は User Analytics view の保存条件を使う
- `ua data raw|aggregated` と `ua sessions list` は `--event-params page_type:EQUALS:pricing` のような event parameter filter を渡せる。`page_type:pricing` と `page_type=pricing` は `EQUALS` として扱う
- `ua event-params --project <project-id-or-index>` は利用可能な event parameter keys と BigQuery 側の `selectedEventParamKeys` / backfill 状態を確認する
- `connections bigquery event-params set <bigquery-id> --keys <keys>` は User Analytics BigQuery の選択 event parameter keys を置き換える。clear するときは `--keys clear`
- workspace/project/name のように意味が曖昧になりやすい required input は named option で渡す
- raw MCP tool名の直接実行やJSON inputはCLIでは提供しない
- `node cli/dist/index.mjs ...` は built CLI の確認用で、packaged command surface と同じ挙動を狙う

## Migration notes

このブランチでは raw MCP tool 実行を CLI surface から外したため、旧 tool catalog から直接は呼べなくなった機能があります。この節は開発者向けの再実装メモです。ユーザー向け CLI には未対応機能の一覧表示を出しません。

現時点で CLI command として実装済み:

- workspace/project: `list_workspaces`, `list_projects`
- Search Analytics: `list_search_analytics_views`, `create_search_analytics_view`, `update_search_analytics_view`, `delete_search_analytics_view`, `update_search_analytics_daily_export_setting`, `get_search_analytics_aggregated_data`, `get_search_analytics_raw_data`
- User Analytics: `list_user_analytics_views`, `create_user_analytics_view`, `update_user_analytics_view`, `delete_user_analytics_view`, `get_user_analytics_aggregated_data`, `get_user_analytics_raw_data`, `get_user_analytics_key_events`, `get_user_analytics_event_param_keys`, `set_user_analytics_key_events`, `list_sessions`, `get_session_detail`
- Dashboards: `list_dashboards`, `create_dashboard`, `edit_dashboard`, `delete_dashboard`, `create_dashboard_item`, `edit_dashboard_item`, `delete_dashboard_item`
- Groups and connections: `list_query_groups`, `create_search_analytics_query_group`, `update_query_group`, `update_query_group_order`, `delete_search_analytics_query_group`, `list_url_groups`, `create_search_analytics_url_group`, `update_search_analytics_url_group`, `update_url_group_order`, `delete_search_analytics_url_group`, `create_user_analytics_url_group`, `update_user_analytics_url_group`, `delete_user_analytics_url_group`, `list_bigquery`, `update_user_analytics_bigquery_event_param_keys`, `list_service_accounts`, `register_service_account`, `delete_service_account`, `add_search_console_property`, `delete_search_console_property`
- Notifications: `list_notifications`
- Index Worker: `list_index_workers`, `create_index_worker`, `edit_index_worker`, `delete_index_worker`, `duplicate_index_worker`, `move_index_worker_project`, `get_index_worker_status`, `get_indexing_job_details`, `get_index_worker_export_data`, `rerun_index_worker_job`
- Project management: `create_project`, `edit_project`, `delete_project`, `duplicate_project`

## OAuth

CLI は OAuth 前提です。`AMETHYST_TOKEN` override はサポートしません。
接続先を明示しない場合は production (`https://api.amethy.st/query`) に接続します。

```bash
export AMETHYST_FRONTEND_URL=https://app.amethy.st
ame login
```

staging に接続したい場合だけ、endpoint を明示します。

```bash
export AMETHYST_GRAPHQL_ENDPOINT=https://stg.api.amethy.st/query
ame login
```

期待する挙動:

- browser で Amethyst login / consent が開く
- localhost callback 完了後に terminal へ戻る
- 以後の command は保存済み OAuth credential を使う

credential の保存先:

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

## Config files

CLI profile config は `~/.config/amethyst-cli/config.json` を使います。
既存の `~/.config/amethyst-mcp/config.json` は deprecated migration fallback です。CLI 専用 config が無い間だけ read-only fallback として読みます。

## Packaging

install 用の見方を先に書くと:

- `package:binary`: そのまま `ame` として配りやすい single binary を作る
- `package`: `node ame/dist/index.mjs` で実行する JS bundle archive を作る
- `package:all`: 両方作る

archive:

```bash
cd /path/to/amethyst
pnpm --filter amethyst-cli package
```

この command は JS bundle archive だけを作ります。

single binary:

```bash
cd /path/to/amethyst
pnpm --filter amethyst-cli package:binary
```

両方まとめて作る場合:

```bash
cd /path/to/amethyst
pnpm --filter amethyst-cli package:all
```

生成物:

- `cli/release/ame-<short-sha>.tar.gz` (JS bundle archive)
- `cli/release/ame-<platform>-<arch>`
- `cli/release/ame-<platform>-<arch>-<short-sha>.tar.gz`

ローカルの `package:binary` は実行中のOS/arch向けbinaryを作ります。CI の package job では Ubuntu runner 上でNode.jsの各OS向け配布binaryへSEA blobをinjectし、JS bundle archive、`install.sh`、`ame-linux-x64`、`ame-linux-arm64`、`ame-darwin-x64`、`ame-darwin-arm64`、`ame-windows-x64.exe` とそれぞれの tar archive をActions artifactとGCSへ配布します。
