Amethyst CLI

Amethyst CLI (ame) lets you run supported Amethyst operations from your terminal.

Use Amethyst CLI when you want the ame command surface for login, status checks, workspace/project lookup, and supported Search Analytics and Index Worker operations. If you want to connect an AI client to Amethyst through MCP, see Amethyst MCP.

Amethyst CLI is provided for users with an active Amethyst contract. It is not a general public package on npm, Homebrew, or another package registry.

Before you start

You need an Amethyst account and access to at least one workspace.

Prebuilt binaries are published for Linux x64/arm64, macOS x64/arm64, and Windows x64. If you use another environment, use the JS bundle archive with Node.js 20 or later.

Install the CLI

Choose the tab for your platform.

Install with the shell installer:

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

The installer downloads the matching macOS binary and installs it as ~/bin/ame.

Manual downloads:

If you install manually, place the file on your PATH as ame:

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

If your shell says ame: command not found, check that the directory you used is included in your PATH.

Install with the shell installer:

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

The installer downloads the matching Linux binary and installs it as ~/bin/ame.

Manual downloads:

If you install manually, place the file on your PATH as ame:

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

If your shell says ame: command not found, check that the directory you used is included in your PATH.

Install the Windows x64 binary with PowerShell:

New-Item -ItemType Directory -Force "$env:USERPROFILE\bin"
Invoke-WebRequest -Uri "https://storage.googleapis.com/amethyst-cli/releases/latest/ame-windows-x64.exe" -OutFile "$env:USERPROFILE\bin\ame.exe"
ame status

If Windows says ame cannot be found, add %USERPROFILE%\bin to PATH, then open a new terminal.

Manual download: Download Amethyst CLI for Windows x64

If you cannot use a prebuilt binary, use the JS bundle archive with Node.js 20 or later.

Download Amethyst CLI JS bundle

tar -xzf ame.tar.gz
node ame/dist/index.mjs status

The JS bundle archive is not a single executable. Run it with node ame/dist/index.mjs ....

Run:

ame login

The CLI opens Amethyst in your browser. Sign in, approve access, and return to the terminal after the localhost callback page appears.

Check the connection:

ame status

When sign-in succeeds, the status shows the API endpoint and saved credential location.

Supported commands

Command	What it does
`ame login`	Sign in to Amethyst in your browser.
`ame logout`	Sign out and remove saved credentials.
`ame status`	Check the API connection and saved sign-in state.
`ame ws list`	List workspaces available to the signed-in user.
`ame ws use <workspace-id-or-index>`	Set the default workspace. After setting it, workspace commands can omit `--workspace`.
`ame ws current`	Show the default workspace.
`ame ws clear`	Clear the default workspace.
`ame projects list [--workspace <workspace-id-or-index>]`	List projects in a workspace. After setting a default workspace, you can omit `--workspace`. You can also pass a workspace candidate index, such as `--workspace 0`, after running `ame ws list`.
`ame projects create [--workspace <workspace-id-or-index>] --kind <project-kind> --name <name>`	Create a project. Set `--kind` to `iw`, `sa`, or `ua`. For SA/UA projects, also pass `--bigquery <bigquery-id>`.
`ame projects edit <project-id-or-index> --name <name>`	Update a project's name, description, or color.
`ame projects duplicate <project-id-or-index>`	Duplicate a project.
`ame projects delete <project-id-or-index>`	Delete a project.
`ame sa views list --project <project-id-or-index>`	List Search Analytics views in a project. You can pass a project candidate index, such as `--project 1`, after running `ame projects list`.
`ame sa views create --project <project-id-or-index> --name <name>`	Create a Search Analytics view in a project. You can pass a project candidate index, such as `--project 1`, after running `ame projects list`.
`ame sa views edit <view-id-or-index> --name <name>`	Update a Search Analytics view. Query, URL, device, and country filters are also supported.
`ame sa views delete <view-id-or-index>`	Delete a Search Analytics view.
`ame sa data aggregated --project <project-id-or-index> --from <date> --to <date>`	Get aggregated Search Analytics data. Use options such as `--metrics clicks,impressions`, `--group-by query-group`, and `--time-group-by week` to choose the output shape.
`ame sa data aggregated --view <view-id-or-index> --from <date> --to <date>`	Get aggregated Search Analytics data using a view's saved conditions. You can pass a view candidate index, such as `--view 0`, after running `ame sa views list`.
`ame sa data raw --project <project-id-or-index> --from <date> --to <date>`	Get Search Analytics raw rows. Use options such as `--group-by query,url,date`, `--metrics clicks,ctr`, and `--limit 100`.
`ame sa data raw --view <view-id-or-index> --from <date> --to <date>`	Get Search Analytics raw rows using a view's saved conditions.
`ame ua views list --project <project-id-or-index>`	List User Analytics views in a project.
`ame ua views create --project <project-id-or-index> --name <name>`	Create a User Analytics view.
`ame ua views edit <view-id-or-index> --name <name>`	Update a User Analytics view.
`ame ua views delete <view-id-or-index>`	Delete a User Analytics view.
`ame ua data aggregated --project <project-id-or-index> --from <date> --to <date>`	Get aggregated User Analytics data. Use options such as `--group-by source-medium`, `--time-group-by week`, and `--limit 100`.
`ame ua data raw --project <project-id-or-index> --from <date> --to <date>`	Get User Analytics raw rows. Use options such as `--group-by date,source-medium`, `--metrics session-count,conversion-rate`, and `--limit 100`.
`ame ua data raw --view <view-id-or-index> --from <date> --to <date>`	Get User Analytics raw rows using a view's saved conditions.
`ame ua key-events --project <project-id-or-index>`	Show User Analytics key events and event names.
`ame ua sessions list --project <project-id-or-index> --from <date> --to <date>`	List User Analytics sessions.
`ame ua sessions detail --project <project-id-or-index> --ga-session-id <number> --user-pseudo-id <id>`	Show User Analytics session detail.
`ame dashboards list [--workspace <workspace-id-or-index>]`	List dashboards in a workspace. After setting a default workspace, you can omit `--workspace`.
`ame dashboards create [--workspace <workspace-id-or-index>] --name <name>`	Create a dashboard.
`ame dashboards edit <dashboard-id> --name <name>`	Update a dashboard.
`ame dashboards delete <dashboard-id>`	Delete a dashboard.
`ame dashboards items create --dashboard <dashboard-id> --type <type> --feature <feature-id>`	Add a dashboard item.
`ame dashboards items edit <dashboard-item-id> --name <name>`	Update a dashboard item.
`ame dashboards items delete <dashboard-item-id>`	Delete a dashboard item.
`ame sa groups query list --project <project-id-or-index>`	List Search Analytics query groups.
`ame sa groups query create --project <project-id-or-index> --name <name> --patterns <patterns>`	Create a Search Analytics query group. Use patterns like `contains:brand,regex:^foo`.
`ame sa groups query edit <query-group-id> --name <name>`	Update a Search Analytics query group.
`ame sa groups query order --project <project-id-or-index> --ids <ids>`	Update Search Analytics query group order.
`ame sa groups query delete <query-group-id>`	Delete a Search Analytics query group.
`ame groups url list --project <project-id-or-index>`	List URL groups in a Search Analytics or User Analytics project.
`ame sa groups url create --project <project-id-or-index> --name <name> --patterns <patterns>`	Create a Search Analytics URL group.
`ame sa groups url edit <url-group-id> --name <name>`	Update a Search Analytics URL group.
`ame sa groups url order --project <project-id-or-index> --ids <ids>`	Update Search Analytics URL group order.
`ame sa groups url delete <url-group-id>`	Delete a Search Analytics URL group.
`ame ua groups url create --project <project-id-or-index> --name <name> --patterns <patterns>`	Create a User Analytics URL group.
`ame ua groups url edit <url-group-id> --name <name>`	Update a User Analytics URL group.
`ame ua groups url order --project <project-id-or-index> --ids <ids>`	Update User Analytics URL group order.
`ame ua groups url delete <url-group-id>`	Delete a User Analytics URL group.
`ame connections bigquery list [--workspace <workspace-id-or-index>]`	List BigQuery connections. After setting a default workspace, you can omit `--workspace`.
`ame connections service-accounts list [--workspace <workspace-id-or-index>]`	List service accounts. After setting a default workspace, you can omit `--workspace`.
`ame connections service-accounts register [--workspace <workspace-id-or-index>]`	Show the settings page where you upload a Service Account JSON key.
`ame connections service-accounts delete <service-account-id>`	Delete a service account.
`ame connections search-console add [--workspace <workspace-id-or-index>] --property <property>`	Register a Search Console property.
`ame connections search-console delete <property-id>`	Delete a Search Console property.
`ame notifications list --workspace <workspace-id-or-index>`	List notifications.
`ame iw list --project <project-id-or-index>`	List Index Workers in an Index Worker project. You can pass a project candidate index, such as `--project 2`, after running `ame projects list`.
`ame iw create --project <project-id-or-index> --name <name> --property <property-id> --url-type <url-type> --url <url>`	Create an Index Worker. Set `--url-type` to `sitemap`, `rss`, or `manual`.
`ame iw edit <index-worker-id-or-index> --name <name>`	Update an Index Worker.
`ame iw duplicate <index-worker-id-or-index>`	Duplicate an Index Worker.
`ame iw move <index-worker-id-or-index> --project <project-id-or-index>`	Move an Index Worker to another Index Worker project.
`ame iw delete <index-worker-id-or-index>`	Delete an Index Worker.
`ame iw status --project <project-id-or-index>`	Show the latest indexing status for each worker in a project, including request/success/failure counts, crawl/index counts, and crawl/index rates.
`ame iw jobs <index-worker-id-or-index>`	Show recent jobs for an Index Worker. You can pass an Index Worker candidate index, such as `0`, after running `ame iw list`.
`ame iw jobs list --worker <index-worker-id-or-index>`	Show recent jobs for an Index Worker. If `--worker` is omitted in an interactive terminal, the CLI asks you to choose from the latest `ame iw list` candidates.
`ame iw export <index-worker-id-or-index>`	Show Index Worker export request data.
`ame iw rerun <index-worker-id-or-index>`	Trigger a one-time rerun for an Index Worker.

When a list command prints human-readable output, each item includes a candidate index like [0]. The next command can use that index instead of copying the full ID. --json output stays machine-readable and does not add candidate labels.

If a command is missing a required value and the terminal is interactive, the CLI asks for the missing value. Commands that change Amethyst ask for confirmation before applying the change. Use --yes only when you intentionally want to apply the change without an interactive confirmation prompt.

Examples

List workspaces:

ame ws list

List projects in a workspace:

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

List Search Analytics views in a project:

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

Create a Search Analytics view for a project:

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

Get aggregated Search Analytics data:

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

Get Search Analytics raw rows:

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

Get Search Analytics raw rows using the first view from the latest ame sa views list output:

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

Get User Analytics raw rows:

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

Get User Analytics raw rows using the first view from the latest ame ua views list output:

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

List Index Workers in a project:

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

Show Index Worker indexing status:

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

Show recent jobs for an Index Worker:

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

Rerun the first Index Worker from the latest ame iw list output:

ame iw rerun 0

Skip confirmation for a command that changes Amethyst:

ame iw rerun 0 --yes

Use JSON output

Use --json when you need machine-readable output for scripts.

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

Sign out or reset authorization

Sign out:

ame logout

If you need to remove the saved credential manually, delete the credential file.

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

The next ame login starts OAuth authorization again.

Troubleshooting

If the download link cannot be opened, contact Amethyst support.
If ame cannot be found, check that the binary is named ame and that its directory is in PATH.
If the browser does not open during ame login, check the terminal output for an authorization URL and open it manually.
If ame status says the saved sign-in is expired, run ame login again.
If a command returns 401 or 403, sign out with ame logout, run ame login, and make sure you selected the workspace you need.