> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/llms.txt

# CLI 指令

你可以使用 Mastra 提供的命令列介面（CLI）開發、建置及啟動 Mastra 項目。

## `mastra dev`

啟動一個公開 [Studio](https://mastra.zisheng.pro/zh-HK/docs/studio/overview)，以及供 Agent、Tool 和 Workflow 使用的 REST 端點的伺服器。`mastra dev` 執行後，你可以前往 <http://localhost:4111/swagger-ui> 查看所有可用端點的概覽。

你亦可以[設定伺服器](https://mastra.zisheng.pro/zh-HK/reference/configuration)。

### 旗標

此指令接受[常用旗標](#common-flags)及下列額外旗標：

#### `--https`

啟用本機 HTTPS 支援。[了解更多](https://mastra.zisheng.pro/zh-HK/reference/configuration)。

#### `--inspect`

以偵錯模式啟動開發伺服器，方便進行除錯。你可選擇指定自訂主機及連接埠（例如 Docker 可使用 `--inspect=0.0.0.0:9229`）。此旗標不可與 `--inspect-brk` 同時使用。

#### `--inspect-brk`

以偵錯模式啟動開發伺服器，並在指令碼開頭中斷。你可選擇指定自訂主機及連接埠（例如 `--inspect-brk=0.0.0.0:9229`）。此旗標不可與 `--inspect` 同時使用。

#### `--custom-args`

要傳遞至 Node.js 程序的自訂引數清單，以逗號分隔，例如 `--require=newrelic` 或 `--experimental-transform-types`。

#### `--request-context-presets`

包含[請求內容](https://mastra.zisheng.pro/zh-HK/docs/server/request-context)預設設定的 JSON 檔案路徑。提供後，Studio 的請求內容編輯器會顯示下拉式選單，讓你快速切換預設設定。

```bash
mastra dev --request-context-presets ./presets.json
```

該檔案必須是 JSON 物件，每個鍵都是預設設定名稱，而每個值都是物件：

```json
{
  "development": { "userId": "dev-user", "env": "development" },
  "production": { "userId": "prod-user", "env": "production" }
}
```

### 設定

你可設定環境變數，以修改 `mastra dev` 的行為。

#### 略過 peer 依賴套件檢查

設定 `MASTRA_SKIP_PEERDEP_CHECK=1`，在啟動時略過 peer 依賴套件版本不相符檢查：

```bash
MASTRA_SKIP_PEERDEP_CHECK=1 mastra dev
```

在 monorepo 開發期間，peer 依賴套件可能已升級但套件尚未發佈，此設定便十分實用。

#### 停用建置快取

設定 `MASTRA_DEV_NO_CACHE=1` 以強制完整重新建置，而不使用 `.mastra/` 下的快取資產：

```bash
MASTRA_DEV_NO_CACHE=1 mastra dev
```

當你正在為 bundler 外掛程式除錯，或懷疑輸出已過時時，此設定會有所幫助。

#### 限制平行處理數量

`MASTRA_CONCURRENCY` 會限制可平行執行的高成本操作數目（主要是建置及評估步驟）。例如：

```bash
MASTRA_CONCURRENCY=4 mastra dev
```

如不設定，CLI 會根據電腦選擇合適的預設值。

#### 自訂 Provider 端點

使用 Vercel AI SDK 支援的 Provider 時，你可以設定基礎 URL，透過代理或內部閘道重新導向請求。以 OpenAI 為例：

```bash
OPENAI_API_KEY=<your-api-key> \
OPENAI_BASE_URL=https://openrouter.example/v1 \
mastra dev
```

以 Anthropic 為例：

```bash
ANTHROPIC_API_KEY=<your-api-key> \
ANTHROPIC_BASE_URL=https://anthropic.internal \
mastra dev
```

這些設定會轉發至 Mastra 模型路由器，並適用於任何 `"openai/..."` 或 `"anthropic/..."` 模型選項。

## `mastra factory dev`

啟動用於開發 [Agent Builder](https://agent-builder.mastra.ai/) 的開發伺服器。它使用與 [`mastra dev`](#mastra-dev) 相同的開發執行環境及旗標，並寫入相同的 `.mastra/output` 目錄。

```bash
npx mastra factory dev
```

兩個指令共用同一個開發鎖，因此 `mastra dev` 和 `mastra factory dev` 無法在同一項目中同時執行。如果其中一個已在執行，另一個會因重複開發伺服器錯誤而結束。

開發 Agent Builder 功能時，請使用 `mastra factory dev`。它接受與 [`mastra dev`](#mastra-dev) 相同的旗標，包括 `--https`、`--inspect`、`--inspect-brk`、`--custom-args` 及 `--request-context-presets`。

## `mastra build`

`mastra build` 指令會將 Mastra 項目封裝成可供生產環境使用的 Hono 伺服器。[Hono](https://hono.dev/) 是輕量、型別安全的網頁框架，讓你能輕鬆將 Mastra Agent 部署為支援中介軟件的 HTTP 端點。

在底層，Mastra 的 Rollup 伺服器會找出 Mastra 進入點檔案，並將其封裝成可供生產環境使用的 Hono 伺服器。封裝期間，它會對程式碼進行 tree shaking，並產生供除錯使用的來源對應。

你可以使用 [`mastra start`](#mastra-start)，將 `.mastra` 中的輸出部署至任何雲端伺服器。

如果要部署至[無伺服器平台](https://mastra.zisheng.pro/zh-HK/docs/deployment/cloud-providers)，你需要安裝正確的 deployer，才能在 `.mastra` 中取得正確輸出。

此指令接受[常用旗標](#common-flags)。

### 旗標

#### `--studio`

將 Studio UI 與建置結果一併封裝。

### 設定

你可設定環境變數，以修改 `mastra build` 的行為。

#### 略過 peer 依賴套件檢查

設定 `MASTRA_SKIP_PEERDEP_CHECK=1`，略過 peer 依賴套件版本不相符檢查：

```bash
MASTRA_SKIP_PEERDEP_CHECK=1 mastra build
```

#### 限制平行處理數量

在 CI 或資源受限的環境中執行時，你可以設定 `MASTRA_CONCURRENCY`，限制可同時執行的高成本工作數目。

```bash
MASTRA_CONCURRENCY=2 mastra build
```

## `mastra start`

> **資訊:** 你需要先執行 `mastra build`，然後才可使用 `mastra start`。

啟動本機伺服器，以生產模式提供已建置的 Mastra 應用程式。預設會啟用 [OTEL Tracing](https://mastra.zisheng.pro/zh-HK/docs/observability/tracing/overview)。

### 旗標

此指令接受[常用旗標](#common-flags)及下列額外旗標：

#### `--dir`

已建置 Mastra 輸出目錄的路徑。預設為 `.mastra/output`。

#### `--custom-args`

要傳遞至 Node.js 程序的自訂引數清單，以逗號分隔，例如 `--require=newrelic` 或 `--experimental-transform-types`。

## `mastra worker build`

封裝 Mastra 應用程式以部署 worker。產生與 `mastra build` 相同的輸出：自包含的 `.mastra/output/` 目錄。

```bash
mastra worker build [options]
```

### 旗標

#### `--dir`

Mastra 來源目錄的路徑。預設為 `src/mastra`。

#### `--root`

項目根目錄。預設為目前目錄。

#### `--tools`

要包含在封裝檔案中的 Tool 路徑，以逗號分隔。

#### `--output-dir`

自訂輸出目錄。預設為 `.mastra/output`。

#### `--debug`

在建置期間啟用除錯記錄。

## `mastra experiment build`

建置獨立的配套 worker，無需公開 HTTP 伺服器即可執行實驗。worker 會載入你匯出的 `Mastra` 實例，並從標準輸入接收帶版本的換行分隔 JSON（NDJSON）協定訊息，再將協定事件寫入標準輸出。

```bash
mastra experiment build [options]
```

指令預設會將 worker 寫入 `.mastra/experiment-worker`。該目錄包含可執行進入點、生產環境依賴套件及 `experiment-worker-manifest.json`。請將標準輸出視為只供協定使用的輸出。worker 診斷資料會寫入標準錯誤。

### 成品合約

`experiment-worker-manifest.json` 將成品識別為版本 `1` 的 `mastra-experiment-worker`，並提供：

- 嵌入可執行檔案中的 CLI 版本、建立時間及唯一建置 ID。
- 支援的協定及資料集正規化版本。
- 啟動 worker 所需的可執行檔案、引數及工作目錄。
- 依賴套件資訊清單及產生的鎖定檔案路徑。
- 每個成品檔案經排序的 SHA-256 摘要。
- 從這些檔案路徑及摘要衍生的 SHA-256 內容摘要。

內容摘要不包括 `experiment-worker-manifest.json`，以免產生自我參照摘要。請將資訊清單與目錄其餘部分一併封裝。如須證明資訊清單本身，請使用外層套件摘要。

### 協定合約

worker 實作固定的實驗配套 worker 協定版本 `1`。它從標準輸入讀取嚴格的 UTF-8 NDJSON frame，並要求每個 frame（包括最後一個）均以換行符結尾。大於 1 MiB、格式錯誤或被截斷的 frame、不支援的協定或正規化版本，以及與作用中實驗關聯不符的訊息，都會因協定失敗而被拒絕。

執行請求必須符合成品內嵌的建置 ID，並包括有序資料集項目數目及 SHA-256 證明。worker 會發出從 `0` 開始的連續序號、由計時器驅動的心跳、已等待的實驗生命週期事件，以及且僅有一個終止事件。取消操作必須符合使用中的協定版本、實驗 ID、工作 ID、嘗試次數及冪等鍵。

協定結束代碼如下：

| 代碼   | 意義        |
| ---- | --------- |
| `0`  | 已完成       |
| `10` | 已完成，但項目出錯 |
| `20` | 嚴重失敗      |
| `21` | 可重試的失敗    |
| `30` | 已取消       |
| `31` | 已逾時       |
| `70` | 協定失敗      |

### 封包欄位處理

worker 會將目標身分、有序內嵌資料集項目、Scorer ID、並行數、逾時、實驗中繼資料、請求內容、Tool mock 及取消操作傳遞至 `runExperiment`。Scorer 版本及成品來源會保留為實驗中繼資料。Scorer 程式碼來源由成品准入機制強制執行，而非在執行階段查找 Scorer。

版本 `1` 會確定地拒絕未宣告的 Tool。非空白的網絡允許清單及秘密參照會因政策失敗而被拒絕，因為網絡強制執行及秘密具體化屬於程序 Sandbox 的職責。傳遞至 `runExperiment` 時，資料集項目來源及預期軌跡欄位會保留為項目中繼資料。

### 旗標

#### `--dir`

your Mastra source directory的路徑。預設為 `src/mastra`。

#### `--root`

項目根目錄。預設為目前目錄。

#### `--output-dir`

自訂成品目錄。相對路徑會從項目根目錄解析。預設為 `.mastra/experiment-worker`。

#### `--debug`

啟用debug logging during the build。

## `mastra worker start`

> **資訊:** 你需要先執行 `mastra worker build` 或 `mastra build`，然後才可使用 `mastra worker start`。

從先前建置的封裝檔案啟動 worker 程序。選用的 `name` 引數會在衍生程序中設定 `MASTRA_WORKERS`，以控制要啟動的 worker。

```bash
mastra worker start [name] [options]
```

### 旗標

#### `--dir`

建置輸出目錄的路徑。預設為 `.mastra/output`。

#### `--env`

環境檔案的路徑。預設為 `.env.production`，如不存在則改用 `.env`。

### 範例

```bash
# Start only the orchestration worker
mastra worker start orchestration

# Start only the scheduler
mastra worker start scheduler

# Start from a custom build directory
mastra worker start orchestration --dir ./dist
```

請參閱 [Worker](https://mastra.zisheng.pro/zh-HK/docs/deployment/workers)，了解部署拓撲及設定。

## `mastra studio`

以靜態伺服器形式啟動 [Studio](https://mastra.zisheng.pro/zh-HK/docs/studio/overview)。啟動後，你可以輸入 Mastra 實例 URL（例如 `http://localhost:4111`），將 Studio 連接至 Mastra 後端。此指令會在目前工作目錄中尋找 `.env` 及 `.env.production` 檔案作設定用途。

### 旗標

此指令接受[常用旗標](#common-flags)及下列額外旗標：

#### `--port`

Studio 執行時使用的連接埠。預設為 `3000`。

#### `--server-host`

要連接的 Mastra API 伺服器主機。預設為 `localhost`。

#### `--server-port`

要連接的 Mastra API 伺服器連接埠。預設為 `4111`。

#### `--server-protocol`

要連接的 Mastra API 伺服器協定。預設為 `http`。

#### `--server-api-prefix`

Mastra API 伺服器的 API 路由前綴。預設為 `/api`。

#### `--request-context-presets`

包含[請求內容](https://mastra.zisheng.pro/zh-HK/docs/server/request-context)預設設定的 JSON 檔案路徑。其運作方式與 [`mastra dev` 旗標](#--request-context-presets)相同。

```bash
mastra studio --request-context-presets ./presets.json
```

## `mastra deploy`

建置項目並將其部署至由 `--env` 選取的 Mastra 平台環境。建議所有新部署均使用此指令。此指令取代 [`mastra studio deploy`](#mastra-studio-deploy) 及 [`mastra server deploy`](#mastra-server-deploy)；後兩者仍可運作，但不應再用於新的設定。

你必須透過 [`mastra auth login`](#mastra-auth-login) 或 `MASTRA_API_TOKEN` 環境變數進行驗證。

```bash
mastra deploy
mastra deploy --env staging
mastra deploy --env production --region eu
```

此指令會執行 `mastra build`，將輸出壓縮後上載至所選環境。然後，指令會輪詢部署狀態並串流建置記錄，直至部署進入最終狀態。

組織、項目及環境會依以下次序解析：環境變數（`MASTRA_ORG_ID`、`MASTRA_PROJECT_ID`）、CLI 旗標（`--org`、`--project`、`--env`）、`.mastra-project.json` 設定檔、憑證中的目前組織，最後是互動式提示。首次部署時，CLI 會將解析所得的組織及項目 ID 儲存至 `.mastra-project.json`，讓後續部署可略過提示。

如果項目尚不存在，CLI 會在確認後使用 `package.json` 的 `name` 欄位建立項目。如果目標環境不存在，CLI 會在確認後建立該環境（除 `production` 外，其他環境預設為 `type: staging`）。配合 `--yes` 使用，即可透過單一非互動式指令建立並部署所有項目：

```bash
mastra deploy --env staging --yes
```

設定 `--env <name>` 而未設定 `--env-file` 時，如果項目目錄中有 `.env.<name>`（例如 `.env.staging`），CLI 便會自動選取該檔案。將 `<name>` 值插入檔案路徑前，系統會根據嚴格的允許清單驗證該值。

### 引數

#### `[dir]`

項目目錄。預設為目前目錄。

### 旗標

#### `--env`

目標環境名稱。預設為 `production`。未設定 `--env-file` 時，會自動從項目目錄選取 `.env.<name>`。如果環境不存在，CLI 會在確認後建立環境。

#### `--org`

組織 ID。亦可透過 `MASTRA_ORG_ID` 環境變數設定。

#### `--project`

項目 ID、slug 或名稱。亦可透過 `MASTRA_PROJECT_ID` 環境變數設定。如果沒有相符的項目，部署時會使用此值作為新項目的名稱並建立項目。

#### `-y, --yes`

自動接受預設值而不顯示確認提示，包括建立項目及環境。

#### `-c, --config`

項目設定檔的路徑。預設為 `.mastra-project.json`。

#### `--env-file`

要與部署一併封裝的環境檔案路徑（相對於項目目錄）。設定後，會停用根據 `--env` 自動選取 `.env.<name>` 的功能。

```bash
mastra deploy --env staging --env-file .env.staging.local
```

#### `--region`

新建環境的區域（例如 `eu`）。只在 CLI 建立環境時套用。

#### `--skip-build`

略過建置步驟，並部署現有的 `.mastra/output` 目錄。如果現有建置相對於目前原始碼已過時，CLI 會發出警告。

#### `--skip-preflight`

略過上載前對建置輸出的驗證。

#### `--debug`

在建置步驟期間啟用偵錯記錄。

### CI/CD 用法

如要進行無介面部署，請將 `MASTRA_API_TOKEN`、`MASTRA_ORG_ID` 及 `MASTRA_PROJECT_ID` 設為環境變數。設定 `MASTRA_API_TOKEN` 後，系統會自動略過互動式提示。配合 `--yes` 使用，可自動接受建立環境。

```bash
export MASTRA_API_TOKEN="..."
export MASTRA_ORG_ID="..."
export MASTRA_PROJECT_ID="..."
mastra deploy --env staging --yes
```

## `mastra env`

管理 Mastra 平台上的環境。環境是屬於某個項目的部署目標（例如 `production`、`staging`、`preview-42`）。目前組織會從已儲存的憑證解析。

每個子指令均按固定次序解析其項目。首先檢查 `MASTRA_PROJECT_ID` 環境變數及 `--project <name|slug|id>` 旗標，然後讀取目前目錄中由 [`mastra deploy`](#mastra-deploy) 寫入的 `.mastra-project.json` 檔案。只要從項目目錄執行指令，便毋須指定項目名稱。

### `mastra env list`

列出項目的環境。每個環境均會顯示其最新部署（正在處理流量時會標示 `(active)`），以及由附加資料庫等受管理資源注入的環境變數名稱。

```bash
mastra env list
```

#### `--json`

輸出機器可讀的 JSON。當中只包含非敏感的中繼資料（ID、名稱、slug、類型、區域、分支、URL、受管理的環境變數名稱及最新部署狀態），因此可安全記錄於 CI。

### `mastra env create`

為項目建立新環境。

```bash
mastra env create staging --type staging --region eu
```

#### `-t, --type`

環境類型。可選 `production`、`staging` 或 `preview`。預設為 `staging`。

#### `-r, --region`

環境所在區域（例如 `eu`）。

#### `--json`

輸出機器可讀的 JSON。與 [`mastra env list`](#mastra-env-list) 一樣，敏感欄位會被省略。

### `mastra env delete`

刪除環境。

```bash
mastra env delete <env>
```

`<env>` 可以是環境名稱、slug 或 ID。除非傳入 `--yes`，否則 CLI 會提示確認。

#### `-y, --yes`

略過確認提示。

### `mastra env restart`

重新啟動環境中正在執行的服務，讓已儲存的環境變數（包括來自附加資料庫的受管理變數）立即生效，而毋須重新部署。

```bash
mastra env restart <env>
```

`<env>` 可以是環境名稱、slug 或 ID。如果該環境從未部署，指令會因衝突錯誤而失敗。

### `mastra env vars pull`

將環境的環境變數拉取至本機環境檔案（預設為 `.env`）。此檔案包含部署所使用的合併變數集，結合儲存在環境中的變數（例如在控制台的環境編輯器中加入的變數）及項目層級變數。如有衝突，會採用項目值。由附加資料庫注入的受管理變數，其值屬平台管理的機密資料，因此只會以註解列出名稱。

```bash
mastra env vars pull
mastra env vars pull <env> --output .env.staging
```

`<env>` 可以是環境名稱、slug 或 ID；如果項目只有一個環境，則可省略。檔案會以 `0600` 權限寫入。如果輸出檔案已存在，指令便會停止。傳入 `--force` 可取代該檔案。

#### `-o, --output`

要寫入的檔案。預設為 `.env`。

#### `-f, --force`

取代現有的輸出檔案。

### `mastra env db`

管理附加至 Mastra 平台項目的資料庫。資料庫由受管理的 Provider（例如 Turso 或 Neon）佈建，並會自動將其連線環境變數注入部署。

資料庫可以是**環境範圍**（其環境變數只會傳送至一個環境），亦可以是**共享**（項目範圍：其環境變數會傳送至所有環境）。`mastra env db create` 預設採用環境範圍：傳入環境引數，或讓 CLI 選取或提示你選擇環境。建立時傳入 `--shared`，則會改為附加共享資料庫。至於其他子指令（`list`、`delete`、`keys`），如要處理環境範圍的資料庫，請傳入環境引數；如要處理共享資料庫，則省略該引數。

建立及刪除資料庫需要組織中的 `admin` 角色。

### `mastra env db list`

列出附加至項目的資料庫，包括 Provider、佈建狀態、範圍（每個資料庫向哪個環境提供資料），以及各資料庫注入的環境變數名稱。傳入環境後，只會顯示向該環境提供資料的資料庫（包括環境範圍及共享資料庫）。

```bash
mastra env db list
mastra env db list <env>
```

#### `--json`

輸出機器可讀的 JSON。

### `mastra env db create`

佈建並附加受管理的資料庫，然後輪詢直至資料庫準備就緒。佈建錯誤會連同 Provider 的詳細錯誤資料一併顯示。

資料庫預設限定於單一環境：傳入環境引數以選取環境，或省略引數讓 CLI 代為選取。如果項目只有一個環境，便會使用該環境。如果項目有多個環境，CLI 會透過互動式提示要求你選擇；在非互動式情境（CI、`--json`）中，則必須提供環境引數。你亦可傳入 `--shared`，改為附加由所有環境共享的項目範圍資料庫。

環境範圍資料庫會從環境繼承其 Provider 區域。共享資料庫接受 `--region`。

```bash
mastra env db create --kind turso                                    # picks or prompts for an environment
mastra env db create staging --kind turso                            # scoped to the "staging" environment
mastra env db create --kind turso --shared                           # shared by all environments
mastra env db create --kind neon --name my-app-db --region aws-us-east-1 --shared
```

#### `--kind`

資料庫 Provider（必填）。可選 `turso` 或 `neon`。

#### `--name`

資料庫名稱。預設使用從項目 slug 衍生的名稱（例如 `my-app-db`）。

#### `--region`

共享資料庫的 Provider 區域 ID。環境範圍資料庫會忽略此選項。

#### `--shared`

附加為由所有環境共享的項目範圍資料庫。不可與環境引數同時使用。

#### `--no-wait`

附加工作排入佇列後立即返回，而不輪詢至資料庫準備就緒。稍後可使用 `mastra env db show` 查看進度。

#### `--json`

輸出機器可讀的 JSON。在此模式下，如果項目有多個環境，便必須提供環境引數或 `--shared`（不會顯示互動式提示）。

### `mastra env db show`

顯示資料庫詳細資料；資料庫準備就緒後，亦會顯示其連線環境變數。機密值預設會被遮蔽。

```bash
mastra env db show <database>
```

`<database>` 可以是資料庫 ID 或名稱。

#### `--show-secrets`

顯示機密連線值，而非將其遮蔽。

#### `--json`

輸出機器可讀的 JSON。除非傳入 `--show-secrets`，否則機密值會被遮蔽。

### `mastra env db delete`

從 Provider 永久刪除資料庫，包括其中所有資料。此操作無法復原。除非傳入 `--yes`，否則 CLI 會提示確認。刪除後，部署不再接收該資料庫的環境變數。

```bash
mastra env db delete <database>
```

#### `-y, --yes`

略過確認提示。

### `mastra env deploys`

列出項目的部署，最新部署會排在最前。正在處理流量的部署會標示為 `(active)`。

```bash
mastra env deploys [environment]
```

省略 `[environment]` 可顯示所有環境的部署；傳入環境名稱、slug 或 ID 則可篩選特定環境。

#### `--json`

輸出機器可讀的 JSON。

## `mastra studio deploy`

> **資訊:** `mastra studio deploy` 仍然可用，但已由 [`mastra deploy`](#mastra-deploy) 取代。後者支援在單一項目中使用環境（`--env staging`、`--env production`）。新設定應使用 `mastra deploy`。

建置項目並部署至 Mastra 平台。你必須透過 [`mastra auth login`](#mastra-auth-login) 或 `MASTRA_API_TOKEN` 環境變數進行驗證。

```bash
mastra studio deploy
```

此指令會執行 `mastra build` 並將輸出壓縮成 zip 檔案。在把所有內容上載至平台前，它會從項目目錄讀取環境檔案。上載後，它會輪詢部署狀態並串流建置日誌，直至部署進入終止狀態。

部署指令會自動載入項目的 `.env` 檔案。如果 `MASTRA_PROJECT_ID` 指向一個為 Observability 佈建的項目，部署會連結至該項目，而不會建立新項目。將 Studio 部署至只供 Observability 使用的項目，會在平台端把它轉換為 Studio 項目。

CLI 要求項目目錄中至少有一個 `.env` 或 `.env.*` 檔案（不包括 `.env.example`）；如果沒有，便會失敗並顯示 `Error: No env file found for deploy.`。如果有多個環境檔案，CLI 會提示你選擇一個（預設為 `.env.production`）。傳入 `--env-file` 可明確指定檔案。如果同時使用 `--yes` 且有多個環境檔案，你必須傳入 `--env-file`，否則部署會發生錯誤。

組織和項目會依以下順序解析：環境變數旗標、`.mastra-project.json` 設定檔、憑證中的目前組織，最後是互動式提示。首次部署時，CLI 會將解析所得的 ID 儲存至 `.mastra-project.json`，讓後續部署略過提示。

如果 `--project <value>` 未能透過 ID 或 slug 配對現有項目，CLI 會把 `<value>` 視為新項目名稱，並在確認後建立項目。配合 `--yes` 使用時，便可透過一條非互動式指令建立並部署新項目：

```bash
mastra studio deploy --project "my-new-project" --yes
```

### 引數

#### `[dir]`

項目目錄。預設為目前目錄。

### 旗標

#### `--org`

組織 ID。亦可透過 `MASTRA_ORG_ID` 環境變數設定。

#### `--project`

項目 ID 或 slug。亦可透過 `MASTRA_PROJECT_ID` 環境變數設定。如果沒有相符的項目，部署時會使用此值作為要建立的新項目名稱。

#### `-y, --yes`

自動接受預設值，不顯示確認提示。

#### `-c, --config`

項目設定檔的路徑。預設為 `.mastra-project.json`。

#### `--env-file`

要與部署一併封裝的環境檔案路徑（相對於項目目錄）。你可以透過指向不同的環境檔案（例如 `.env.staging`、`.env.production`），把同一個項目部署至多個環境。

```bash
mastra studio deploy --env-file .env.staging --yes
```

#### `--skip-build`

略過建置步驟，並部署現有的 `.mastra/output` 目錄。

#### `--debug`

在建置步驟期間啟用偵錯日誌。

### CI/CD 用法

如要進行無介面部署，請將 `MASTRA_API_TOKEN`、`MASTRA_ORG_ID` 和 `MASTRA_PROJECT_ID` 設為環境變數。設定 `MASTRA_API_TOKEN` 後，互動式提示會自動略過。

### `mastra studio deploy list`

列出所有項目及其最新部署狀態和 URL。

### `mastra studio deploy status`

顯示指定部署的狀態。

```bash
mastra studio deploy status <deploy-id>
```

#### `--watch, -w`

輪詢狀態變更，直至部署進入終止狀態。

### `mastra studio deploy logs`

顯示指定部署的日誌。

```bash
mastra studio deploy logs <deploy-id>
```

#### `--follow, -f`

即時串流日誌。

#### `--tail`

要顯示的最近日誌行數。

### `mastra studio deploy suggestions`

顯示失敗 Studio 部署的診斷結果及建議修正方法。

```bash
mastra studio deploy suggestions [deploy-id]
```

如果省略 `deploy-id`，此指令會使用已連結項目的最新部署。如果診斷尚未存在，此指令會啟動診斷並輪詢，直至結果準備就緒。只有診斷發現問題時，才會顯示建議。

### `mastra studio projects`

列出目前組織中的所有項目。

### `mastra studio projects create`

透過互動式提示建立新項目。此指令不接受 `--name` 旗標；如要以非互動方式建立項目，請改用 [`mastra studio deploy --project <name> --yes`](#mastra-studio-deploy)，它會在一個步驟中建立項目並部署至該項目。

## `mastra server deploy`

> **資訊:** `mastra server deploy` 仍然可用，但已由 [`mastra deploy`](#mastra-deploy) 取代。後者可把單一項目部署至多個環境，毋須分別使用 Studio 和 Server 指令。新設定應使用 `mastra deploy`。

建置項目並部署至 Mastra 平台上的 Server。其運作方式與 [`mastra studio deploy`](#mastra-studio-deploy) 相同，並使用相同的旗標、引數和解析邏輯。

部署指令會自動載入項目的 `.env` 檔案。如果 `MASTRA_PROJECT_ID` 指向一個為 Observability 佈建的項目，部署會連結至該項目，而不會建立新項目。將 Server 部署至只供 Observability 使用的項目，會在平台端把它轉換為 Server 項目。

```bash
mastra server deploy [dir]
```

### `mastra server deploy suggestions`

顯示失敗 Server 部署的診斷結果及建議修正方法。

```bash
mastra server deploy suggestions [deploy-id]
```

如果省略 `deploy-id`，此指令會使用已連結項目的最新部署。如果診斷尚未存在，此指令會啟動診斷並輪詢，直至結果準備就緒。只有診斷發現問題時，才會顯示建議。

## `mastra server pause`

暫停已連結項目中正在執行的 Server 執行個體。組織和項目的解析方式與 [`mastra server deploy`](#mastra-server-deploy) 相同。

```bash
mastra server pause
```

### 旗標

#### `--org`

組織 ID。亦可透過 `MASTRA_ORG_ID` 環境變數設定。

#### `--project`

未設定 `MASTRA_PROJECT_ID` 時使用的項目 ID 或 slug。系統會根據目前組織中的項目解析 slug。

#### `-c, --config`

項目設定檔的路徑。預設為 `.mastra-project.json`。

如果執行個體並非正在執行，此指令便會失敗。

## `mastra server restart`

重新啟動已連結項目中已暫停或停止的 Server 執行個體。平台接受重新啟動後，CLI 會解析部署 ID（從 API 回應取得；如果回應省略 ID，則透過輪詢項目和部署中繼資料取得），然後以與 [`mastra server deploy`](#mastra-server-deploy) 相同的方式串流建置和部署日誌，直至部署進入終止狀態。

### 旗標

使用與 [`mastra server pause`](#mastra-server-pause) 相同的旗標：**`--org`**、**`--project`** 和 **`-c` / `--config`**，其預設值和行為亦相同。

```bash
mastra server restart
```

如果此項目仍有進行中的部署（正在執行、建置或部署等），此指令便會失敗。這是平台限制，因此無法在另一個部署進行期間重新啟動。

## `mastra server env`

管理已連結 Server 部署的環境變數。組織和項目的解析方式與 [`mastra server deploy`](#mastra-server-deploy) 相同。

每個子指令均接受 `-c` / `--config` 作為項目設定檔路徑（預設為 `.mastra-project.json`）。

### `mastra server env list`

列出已連結項目的所有環境變數。輸出中的值會部分遮蔽。

### `mastra server env set`

設定環境變數。CLI 會讀取目前的對應、套用變更，然後上載結果。

```bash
mastra server env set <key> <value>
```

### `mastra server env unset`

移除環境變數。

```bash
mastra server env unset <key>
```

### `mastra server env import`

從檔案（例如 `.env` 檔案）匯入變數，並將其合併至現有的對應。新值會覆寫 Server 上已有的鍵。

```bash
mastra server env import <file>
```

### `mastra server env pull`

從已連結項目下載環境變數，並將其寫入本機檔案。這是 [`mastra server env import`](#mastra-server-env-import) 的反向操作。

```bash
mastra server env pull [file]
```

如果未提供引數，檔案預設為 `.env`。所有值都會以雙引號括起並進行逸出，以便安全地在 shell 中載入。不是有效 shell 識別符的鍵會被略過。由於輸出檔案包含機密資料，建立時會使用嚴格權限（`0600`）。

#### `--project`

項目 ID 或 slug。未設定 `MASTRA_PROJECT_ID` 時，會覆寫已連結的項目。

#### CI 用法

在持續整合管線中，請使用 `MASTRA_API_TOKEN` 進行驗證，並在執行應用程式前拉取環境：

```bash
export MASTRA_API_TOKEN="..."
mastra server env pull .env.production --project my-project
```

## `mastra auth`

管理 Mastra 平台的驗證。憑證會儲存在 `~/.mastra/credentials.json`。你亦可以設定 `MASTRA_API_TOKEN` 環境變數，作為互動式登入的替代方式。

### `mastra auth login`

開啟瀏覽器登入，並在本機儲存憑證。

### `mastra auth logout`

移除已儲存的憑證。如果環境中仍設定了 `MASTRA_API_TOKEN`，CLI 會警告仍會繼續使用該變數。

### `mastra auth whoami`

顯示目前使用者的電郵地址、使用者 ID 和作用中組織。

### `mastra auth orgs`

列出所有組織及你在各組織中的角色。目前的組織會加上標記。

#### `mastra auth orgs switch`

透過互動式提示切換作用中組織。設定了 `MASTRA_API_TOKEN` 或 `MASTRA_ORG_ID` 環境變數時無法使用。

### `mastra auth tokens`

列出所有 API token 及其最近使用日期。

#### `mastra auth tokens create`

建立新的 API token。機密值只會顯示一次，之後無法再次擷取。

```bash
mastra auth tokens create <name>
```

#### `mastra auth tokens revoke`

撤銷 API token。

```bash
mastra auth tokens revoke <token-id>
```

## `mastra lint`

`mastra lint` 指令會驗證 Mastra 項目的結構和程式碼。

`mastra lint` 預設會檢查項目的原始檔案和設定。使用 `--preflight`，亦可在部署前檢查 `.mastra/output` 中的套件組合。

```bash
mastra lint --preflight
```

此指令接受[常用旗標](#common-flags)。

### 旗標

#### `--preflight`

對建置完成的 Mastra 輸出執行部署預檢。除非同時傳入 `--skip-build`，否則會先建置項目再進行檢查。

#### `--skip-build`

略過建置步驟，並重用現有的 `.mastra/output` 目錄。此旗標僅在設定了 `--preflight` 時適用。

#### `--env-file <file>`

使用指定的環境檔案進行預檢驗證。此旗標僅在設定了 `--preflight` 時適用。

#### `--strict`

將警告視為錯誤。

#### `--json`

輸出機器可讀的 JSON。

#### `--debug`

啟用偵錯日誌。

## `mastra scorers`

`mastra scorers` 指令提供評估 Scorer 管理功能，用於衡量 AI 產生輸出的質素、準確度和效能。

詳情請參閱 [Scorer 概覽](https://mastra.zisheng.pro/zh-HK/docs/evals/overview)。

### `add`

將新的 Scorer 加入項目。你可以使用互動式提示：

```bash
mastra scorers add
```

或直接提供 Scorer 名稱：

```bash
mastra scorers add answer-relevancy
```

使用 [`list`](#list) 指令取得正確的 ID。

### `list`

列出所有可用的 Scorer 範本。請在 `add` 指令中使用其 ID。

## `mastra create`

使用與 [`create-mastra`](https://mastra.zisheng.pro/zh-HK/reference/cli/create-mastra) 相同的項目建立流程，建立獨立 Mastra 項目。

**npm**:

```bash
npx mastra@latest create
```

**pnpm**:

```bash
pnpm dlx mastra@latest create
```

**Yarn**:

```bash
yarn dlx mastra@latest create
```

**Bun**:

```bash
bun x mastra@latest create
```

同時提供項目名稱和 `--llm`，即可略過互動式設定提示。使用 `--template [template]` 可指定任意範本；使用 `--empty` 則可建立不含 Provider 的最精簡基礎結構。

此指令會為偵測到的程式編寫助理安裝 Mastra Skill，並在適當情況下初始化 Git。使用 `--no-skills` 或 `--no-git` 可選擇不執行相應操作。

有關模式行為、衝突、驗證和完整旗標說明，請參閱 [`create-mastra` 參考資料](https://mastra.zisheng.pro/zh-HK/reference/cli/create-mastra)。

## `mastra init`

`mastra init` 指令會在現有項目中初始化 Mastra。使用此指令可建立所需資料夾和設定的基礎結構，而毋須從頭產生新項目。

### 旗標

此指令接受以下額外旗標：

#### `--default`

使用 OpenAI 在 `src` 內建立檔案，並在 `src/mastra` 資料夾中加入範例程式碼。

#### `--dir`

儲存 Mastra 檔案的目錄。預設為 `src`。

#### `--components`

要加入的元件清單，以逗號分隔。每個元件都會建立一個新資料夾。可選值：`"agents" | "tools" | "workflows" | "scorers"`。預設為 `['agents', 'tools', 'workflows']`。

#### `--llm`

預設模型 Provider。可選值：`"openai" | "anthropic" | "groq" | "google" | "cerebras" | "mistral"`。

#### `--llm-api-key`

所選模型 Provider 的 API 金鑰。此金鑰會寫入環境變數檔案（`.env`）。

#### `--example`

啟用後，會為清單中的元件寫入範例程式碼（例如 Agent 範例程式碼）。

#### `--no-example`

不包括範例程式碼。使用 `--default` 旗標時很有用。

#### `--mcp`

為程式碼編輯器設定 Mastra 的 MCP Server。可選值：`"cursor" | "cursor-global" | "windsurf" | "vscode"`。

#### `--observability`

在 Mastra 平台啟用 Observability。CLI 會提示你選擇現有平台項目或建立新項目，然後寫入所需環境變數並設定 Observability exporter。

#### `--no-observability`

略過 Mastra Observability 提示。

#### `--observability-project`

設定啟用 Mastra Observability 時使用的平台項目名稱。

## `mastra migrate`

執行資料庫遷移以更新儲存結構描述。升級至包含儲存結構描述變更的 Mastra 版本時，此指令很有用。

此指令會封裝項目並連接至已設定的儲存後端，然後執行所有待處理的遷移。目前支援：

- **重複 span 遷移**：移除重複的 `(traceId, spanId)` 項目，並加入唯一約束以確保資料完整性。
- **ClickHouse 舊版至 vNext span 遷移**：將歷史 span 從舊版 `mastra_ai_spans` 資料表複製到 vNext `mastra_span_events` 結構描述。此操作會分批執行，以免超出記憶體限制。詳情請參閱 [ClickHouse 儲存參考資料](https://mastra.zisheng.pro/zh-HK/reference/storage/clickhouse)。

```bash
mastra migrate
```

有關何時需要遷移的詳情，請參閱[儲存遷移指南](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/storage)。

此指令接受[常用旗標](#common-flags)。

## `mastra api`

以 JSON 輸入及輸出呼叫 Mastra runtime 伺服器。可用於本機開發伺服器、已部署的 Mastra 平台項目、自行託管的 Mastra 伺服器，或託管的 Mastra Platform Observability API。

```bash
mastra api agent list
mastra api agent run weather-agent '{"messages":"What is the weather in London?"}'
mastra api tool execute get-weather '{"location":"San Francisco"}'
mastra api trace list '{"page":0,"perPage":20}'
```

使用 `mastra api <resource> <action> --help` 查看指令範例。

### 輸出

成功的回應會以 JSON 寫入 `stdout`。單一資源指令會傳回：

```json
{ "data": {} }
```

清單指令會傳回 `data` 陣列及分頁中繼資料：

```json
{ "data": [], "page": { "total": 0, "page": 0, "perPage": 0, "hasMore": false } }
```

錯誤會以 JSON 寫入 `stderr`，並傳回非零結束代碼：

```json
{
  "error": {
    "code": "SERVER_UNREACHABLE",
    "message": "Could not connect to target server",
    "details": {}
  }
}
```

### 目標解析

對於 runtime 指令，指令會按以下次序解析目標伺服器：

1. `--url <url>`：明確指定的遠端或自行託管伺服器。
2. `http://localhost:4111`：本機 `mastra dev` 伺服器。
3. `.mastra-project.json`：Mastra 平台項目。

只有當 CLI 從 `.mastra-project.json` 解析 Mastra 平台目標時，才會使用自動平台驗證。本機目標及以 `--url` 明確指定的目標不會取得自動憑證。透過 `--header` 傳入的標頭會傳送至任何目標，包括本機。

對於可觀測性指令（`trace`、`log`、`score` 及 `metric`），CLI 預設以 `https://observability.mastra.ai` 為目標，而非項目部署 URL。Trace Intelligence 指令（`learning`）的運作方式相同，但以 `https://output.signals.mastra.ai` 為目標。兩者均按以下次序解析憑證：

1. 透過 `--header` 明確傳入的 `Authorization` 及 `X-Mastra-Project-Id` 標頭。
2. 環境中的 `MASTRA_PLATFORM_ACCESS_TOKEN` 及 `MASTRA_PROJECT_ID`。
3. `.mastra-project.json` 中用於項目 ID 的項目中繼資料。
4. 以你的 Mastra CLI 登入 token 作為驗證後備方案。

Learning 指令亦會傳送 `X-Mastra-Organization-Id`，並依次從明確指定的 `--header`、環境中的 `MASTRA_ORGANIZATION_ID` 或 `.mastra-project.json` 解析其值。

如需覆寫預設的託管可觀測性目標或憑證，請使用 `--url` 及 `--header`。

### 旗標

#### `--url <url>`

指定特定的 Mastra 伺服器 URL。

```bash
mastra api --url https://example.com agent list
```

#### `--server-api-prefix <prefix>`

設定目標伺服器的 API 路由前綴。預設為 `/api`。當伺服器掛載於自訂前綴下時使用此選項（例如 `@mastra/fastify` `MastraServer` 使用 `prefix: "/api/mastra-studio"`），用法與 `mastra studio` 接受 `--server-api-prefix` 相同。你亦可設定 `MASTRA_API_PREFIX` 環境變數，而不傳入此旗標。

```bash
mastra api --url https://example.com --server-api-prefix /api/mastra-studio agent list
```

#### `--header <"Key: Value">`

傳送自訂 HTTP 標頭。重複使用此旗標即可傳送多個標頭。

```bash
mastra api --url https://example.com --header "Authorization: Bearer $TOKEN" agent list
```

#### `--timeout <ms>`

設定請求逾時時間（毫秒）。預設為 `30000`。Workflow run 的 start 及 resume 指令預設為 `120000`。

#### `--pretty`

以美化格式輸出 JSON。預設為 `false`。

#### `--schema`

列印接受 JSON 輸入之指令的 CLI 專用請求 schema。此 schema 來自目標伺服器的路由合約，包含指令結構、位置引數、範例、請求 schema 及回應結構。

接受 JSON 輸入的葉節點指令可使用 `--schema`。此旗標不能作為頂層 `mastra api` 旗標使用。

```bash
mastra api agent run --schema
mastra api tool execute --schema
```

### 輸入模型

接受輸入的指令會接收一個 inline JSON 引數。請勿傳入檔案路徑或 stdin。

```bash
mastra api workflow run start data-pipeline '{"inputData":{"source":"s3://bucket/data.csv"}}'
```

穩定 ID 應使用位置引數，而篩選條件或 payload 則使用 JSON。若路由同時需要查詢參數及請求 body，請傳入一個 JSON 物件。CLI 會按照伺服器路由 schema 拆分輸入。

```bash
mastra api thread create '{"agentId":"weather-agent","resourceId":"user_123","threadId":"thread_abc123","title":"Support conversation"}'
```

當目標路由支援分頁時，清單指令會接受 JSON 輸入中的 `page` 及 `perPage`：

```bash
mastra api score list '{"page":0,"perPage":50}'
mastra api trace list '{"page":0,"perPage":20}'
```

支援篩選條件的路由會在同一個 JSON 輸入中接收這些條件。例如，可觀測性 trace 清單支援分頁及路由所支援的篩選條件：

```bash
mastra api trace list '{"page":0,"perPage":20,"filters":{"spanType":"agent"}}'
```

### 取得指令專屬說明

每個 `mastra api` 葉節點指令的說明輸出都包含該指令專屬的範例。請在你要呼叫的確切指令上使用 `--help`：

```bash
mastra api agent run --help
mastra api tool execute --help
mastra api memory current update --help
mastra api workflow run resume --help
```

在接受 JSON 輸入的指令上使用 `--schema`，以查看目標伺服器傳回的請求結構：

```bash
mastra api agent run --schema
mastra api thread create --schema
mastra api score create --schema
```

部分指令有重要的 runtime 要求。例如，`mastra api memory current update` 要求 memory instance 已啟用 working memory，而 `mastra api workflow run resume` 只適用於已暫停的 workflow run。

### 指令

#### `mastra api agent list`

列出目標伺服器上已註冊的 Agent。可傳入選用的 JSON 輸入，以使用路由支援的篩選條件。

```bash
mastra api agent list [input]
```

#### `mastra api agent get`

取得一個已註冊 Agent 的中繼資料。

```bash
mastra api agent get <agentId>
```

#### `mastra api agent run`

使用 JSON 輸入執行 Agent。請參閱指令說明，查看文字 prompt、聊天訊息及 memory thread 選項的範例。

```bash
mastra api agent run <agentId> <input>
```

#### `mastra api workflow list`

列出目標伺服器上已註冊的 Workflow。可傳入選用的 JSON 輸入，以使用路由支援的篩選條件。

```bash
mastra api workflow list [input]
```

#### `mastra api workflow get`

取得一個已註冊 Workflow 的中繼資料。

```bash
mastra api workflow get <workflowId>
```

#### `mastra api workflow run start`

使用 JSON 輸入啟動 workflow run。由於 run 可能需要較長時間才能完成，Workflow start 指令使用比大多數指令更長的預設逾時時間。

```bash
mastra api workflow run start <workflowId> <input>
```

#### `mastra api workflow run list`

列出某個 Workflow 的 run。可傳入選用的 JSON 輸入，以使用路由支援的篩選條件或分頁。

```bash
mastra api workflow run list <workflowId> [input]
```

#### `mastra api workflow run get`

按 ID 取得一個 workflow run。

```bash
mastra api workflow run get <workflowId> <runId>
```

#### `mastra api workflow run resume`

使用 JSON 輸入恢復已暫停的 workflow run。該 run 必須處於暫停狀態。

```bash
mastra api workflow run resume <workflowId> <runId> <input>
```

#### `mastra api workflow run cancel`

取消 workflow run。

```bash
mastra api workflow run cancel <workflowId> <runId>
```

#### `mastra api tool list`

列出目標伺服器上已註冊的 Tool。可傳入選用的 JSON 輸入，以使用路由支援的篩選條件。

```bash
mastra api tool list [input]
```

#### `mastra api tool get`

取得一個 Tool 的中繼資料及 schema。

```bash
mastra api tool get <toolId>
```

#### `mastra api tool execute`

使用 JSON 輸入執行 Tool。除非你傳入明確的 `data` 物件，否則原始 Tool 輸入會包裝為路由的 `data` 欄位。

```bash
mastra api tool execute <toolId> <input>
```

#### `mastra api mcp list`

列出目標伺服器上已註冊的 Model Context Protocol (MCP) 伺服器。可傳入選用的 JSON 輸入，以使用路由支援的篩選條件。

```bash
mastra api mcp list [input]
```

#### `mastra api mcp get`

取得一個 MCP 伺服器的中繼資料。

```bash
mastra api mcp get <id>
```

#### `mastra api mcp tool list`

列出 MCP 伺服器公開的 Tool。可傳入選用的 JSON 輸入，以使用路由支援的篩選條件。

```bash
mastra api mcp tool list <serverId> [input]
```

#### `mastra api mcp tool get`

取得一個 MCP Tool 的中繼資料及 schema。

```bash
mastra api mcp tool get <serverId> <toolId>
```

#### `mastra api mcp tool execute`

使用 JSON 輸入執行 MCP Tool。除非你傳入明確的 `data` 物件，否則原始 Tool 輸入會包裝為路由的 `data` 欄位。

```bash
mastra api mcp tool execute <serverId> <toolId> <input>
```

#### `mastra api thread list`

列出 memory thread。可傳入選用的 JSON 輸入，以使用路由支援的篩選條件。

```bash
mastra api thread list [input]
```

#### `mastra api thread get`

按 ID 取得一個 memory thread。

```bash
mastra api thread get <threadId>
```

#### `mastra api thread create`

建立 memory thread。傳入一個 JSON 輸入物件；當伺服器路由有此要求時，CLI 會將 `agentId` 等欄位拆分為查詢參數。

```bash
mastra api thread create <input>
```

#### `mastra api thread update`

更新 memory thread。傳入一個 JSON 輸入物件，其中可包含 `agentId`、`resourceId`、`title` 或 `metadata` 等欄位。

```bash
mastra api thread update <threadId> <input>
```

#### `mastra api thread delete`

刪除 memory thread。請以 JSON 輸入傳入路由所需的查詢參數，例如 `agentId` 及 `resourceId`。

```bash
mastra api thread delete <threadId> <input>
```

#### `mastra api thread messages`

列出 memory thread 的訊息。可傳入選用的 JSON 輸入，以使用路由支援的篩選條件或分頁。

```bash
mastra api thread messages <threadId> [input]
```

#### `mastra api memory search`

搜尋 long-term memory。使用 `--help` 或 `--schema` 查看 `agentId`、`resourceId` 及 `searchQuery` 等必填欄位。

```bash
mastra api memory search <input>
```

#### `mastra api memory current get`

讀取 thread 目前的 working memory。

```bash
mastra api memory current get <input>
```

#### `mastra api memory current update`

更新 thread 目前的 working memory。該 memory instance 必須已啟用 working memory。

```bash
mastra api memory current update <input>
```

#### `mastra api memory status`

取得 Agent 的 memory 狀態，以及選用的 thread 或資源 context。

```bash
mastra api memory status <input>
```

#### `mastra api trace list`

列出可觀測性 trace。可傳入選用的 JSON 輸入，以使用路由支援的篩選條件或分頁。

```bash
mastra api trace list [input]
mastra api trace list '{"page":0,"perPage":20}'
mastra api trace list '{"page":0,"perPage":20}' --verbose
```

`trace list` 預設傳回輕量的 root span 記錄，讓你無需擷取大型輸入、輸出、屬性或中繼資料 payload，即可逐頁瀏覽 trace。傳入 `--verbose` 以擷取完整的 root span 記錄。

#### `mastra api trace get`

取得一個可觀測性 trace 的輕量時間軸，而不擷取完整的 span 輸入、輸出、屬性或中繼資料 payload。傳入 `--verbose` 以擷取完整的 trace payload。

```bash
mastra api trace get <traceId>
mastra api trace get <traceId> --verbose
```

#### `mastra api trace span`

從可觀測性 trace 取得一個完整 span。當你在使用 `trace get` 後確定要檢查哪個 span 時，請使用此指令。

```bash
mastra api trace span <traceId> <spanId>
```

#### `mastra api log list`

列出可觀測性記錄。可傳入選用的 JSON 輸入，以使用路由支援的篩選條件或分頁。

```bash
mastra api log list [input]
```

#### `mastra api metric aggregate`

取得單一彙總 metric 值。

```bash
mastra api metric aggregate '{"name":["latency_ms"],"aggregation":"avg"}'
```

#### `mastra api metric breakdown`

取得按標籤或欄位分組的 metric 值。

```bash
mastra api metric breakdown '{"name":["latency_ms"],"aggregation":"avg","groupBy":["model"],"limit":10}'
```

#### `mastra api metric timeseries`

取得一段時間內的 metric 值。

```bash
mastra api metric timeseries '{"name":["latency_ms"],"aggregation":"avg","interval":"1h"}'
```

#### `mastra api metric percentiles`

取得一段時間內的 metric 百分位值。百分位值使用介乎 `0` 至 `1` 的小數。

```bash
mastra api metric percentiles '{"name":"latency_ms","percentiles":[0.5,0.95,0.99],"interval":"1h"}'
```

#### `mastra api metric names`

列出已發現的 metric 名稱。可傳入選用的 JSON 輸入，以進行前綴搜尋及設定數量上限。

```bash
mastra api metric names '{"prefix":"lat","limit":10}'
```

#### `mastra api metric label-keys`

列出 metric 的標籤 key。

```bash
mastra api metric label-keys '{"metricName":"latency_ms"}'
```

#### `mastra api metric label-values`

列出 metric 標籤 key 的標籤值。可傳入選用的前綴及數量上限值，以收窄結果。

```bash
mastra api metric label-values '{"metricName":"latency_ms","labelKey":"model","prefix":"g","limit":10}'
```

#### 使用 `curl` 存取可觀測性功能

你可以使用平台 access token 及項目 ID，直接呼叫託管的可觀測性 API：

```bash
curl -sS "https://observability.mastra.ai/api/observability/traces?page=0&perPage=20" \
  -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \
  -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" | jq
```

取得輕量的 trace 時間軸：

```bash
curl -sS "https://observability.mastra.ai/api/observability/traces/<trace-id>/light" \
  -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \
  -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" | jq
```

取得特定 span：

```bash
curl -sS "https://observability.mastra.ai/api/observability/traces/<trace-id>/spans/<span-id>" \
  -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \
  -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" | jq
```

#### `mastra api score create`

建立可觀測性 score。輸入使用伺服器的 score body 結構。使用 `--schema` 查看其結構。

```bash
mastra api score create <input>
```

#### `mastra api score list`

列出可觀測性 score。可傳入選用的 JSON 輸入，以按 run ID 等條件篩選或進行分頁。

```bash
mastra api score list [input]
```

#### `mastra api score get`

按 ID 取得一個可觀測性 score。

```bash
mastra api score get <scoreId>
```

#### `mastra api dataset list`

列出 dataset。可傳入選用的 JSON 輸入，以使用路由支援的篩選條件或分頁。

```bash
mastra api dataset list [input]
```

#### `mastra api dataset get`

按 ID 取得一個 dataset。

```bash
mastra api dataset get <datasetId>
```

#### `mastra api dataset create`

使用 JSON 輸入建立 dataset。

```bash
mastra api dataset create <input>
```

#### `mastra api dataset items`

列出 dataset 中的項目。可傳入選用的 JSON 輸入，以使用路由支援的篩選條件或分頁。

```bash
mastra api dataset items <datasetId> [input]
```

#### `mastra api experiment list`

列出 dataset 的實驗。可傳入選用的 JSON 輸入，以使用路由支援的篩選條件或分頁。

```bash
mastra api experiment list <datasetId> [input]
```

#### `mastra api experiment get`

按 ID 取得一個實驗。

```bash
mastra api experiment get <datasetId> <experimentId>
```

#### `mastra api experiment run`

使用 JSON 輸入為 dataset 啟動實驗。

```bash
mastra api experiment run <datasetId> <input>
```

#### `mastra api experiment results`

列出實驗結果。可傳入選用的 JSON 輸入，以使用路由支援的篩選條件或分頁。

```bash
mastra api experiment results <datasetId> <experimentId> [input]
```

#### `mastra api learning entities`

列出具有 Trace Intelligence 輸出的實體（Agent），包括每個實體可用的 trace signal。必須已加入 Trace Intelligence 私人測試版。

```bash
mastra api learning entities '{"entityType":"agent"}'
```

#### `mastra api learning snapshots`

列出實體的分析 snapshot，以及按次序排列、以逗號分隔的 trace signal 清單。後續指令需要使用此清單中的 `snapshotId`。

```bash
mastra api learning snapshots <entityId> '{"entityType":"agent","signalNames":"goal,outcome,behavior,sentiment","limit":10}'
```

#### `mastra api learning flow`

取得一個 snapshot 的跨 signal 主題流程：用於 Sankey 樣式檢視的階段及連結，其中計數代表不同的 trace。

```bash
mastra api learning flow <entityId> '{"entityType":"agent","signalNames":"goal,outcome","snapshotId":"<snapshotId>"}'
```

#### `mastra api learning paths`

取得一個 snapshot 中各個 trace 在依序排列的 trace signal 之間的主題指派。使用 `limit` 及 `offset` 分頁。

```bash
mastra api learning paths <entityId> '{"entityType":"agent","signalNames":"goal,outcome","snapshotId":"<snapshotId>","limit":100}'
```

#### `mastra api learning theme list`

列出一個 snapshot 中某個 trace signal 的主題。

```bash
mastra api learning theme list <entityId> '{"entityType":"agent","signalName":"goal","snapshotId":"<snapshotId>"}'
```

#### `mastra api learning theme get`

按數字主題 ID 取得一個 snapshot 中的主題。

```bash
mastra api learning theme get <entityId> <themeId> '{"entityType":"agent","signalName":"goal","snapshotId":"<snapshotId>"}'
```

#### `mastra api learning theme examples`

列出一個 snapshot 中某個主題的 trace 範例。使用 `limit` 及 `offset` 分頁。

```bash
mastra api learning theme examples <entityId> <themeId> '{"entityType":"agent","signalName":"goal","snapshotId":"<snapshotId>","limit":10}'
```

#### `mastra api learning theme history`

取得一個持久主題跨 snapshot 的生命週期記錄，包括拆分及合併關係。不接受 `snapshotId`。

```bash
mastra api learning theme history <entityId> <themeId> '{"entityType":"agent","signalName":"goal"}'
```

#### `mastra api learning noise get`

取得一個 snapshot 中某個 trace signal 的未分群（noise）bucket。

```bash
mastra api learning noise get <entityId> '{"entityType":"agent","signalName":"goal","snapshotId":"<snapshotId>"}'
```

#### `mastra api learning noise examples`

列出一個 snapshot 中 noise bucket 的 trace 範例。使用 `limit` 及 `offset` 分頁。

```bash
mastra api learning noise examples <entityId> '{"entityType":"agent","signalName":"goal","snapshotId":"<snapshotId>","limit":10}'
```

## 常用旗標

### `--dir`

**適用於：** `dev`、`build`、`lint`、`migrate`

Mastra 資料夾的路徑。預設為 `src/mastra`。

### `--debug`

**適用於：** `dev`、`build`、`migrate`

為 Mastra 內部運作啟用詳細記錄。預設為 `false`。

### `--env`

**適用於：** `dev`、`start`、`studio`、`migrate`

要包含的自訂環境變數檔案。預設包含 `.env.development`、`.env.local` 和 `.env`。

### `--root`

**適用於：** `dev`、`build`、`lint`、`migrate`

根資料夾的路徑。預設為 `process.cwd()`。

### `--tools`

**適用於：** `dev`、`build`、`lint`

要包含的 Tool 路徑清單，以逗號分隔。預設為 `src/mastra/tools`。

## 全域旗標

使用這些旗標取得 `mastra` CLI 的資訊。

### `--version`

顯示 Mastra CLI 版本並結束。

### `--help`

顯示說明訊息並結束。

## 遙測

Mastra 預設會收集項目的匿名資訊，例如作業系統、Mastra 版本或 Node.js 版本。你可以閱讀[原始碼](https://github.com/mastra-ai/mastra/blob/main/packages/cli/src/analytics/index.ts)，查看所收集的資訊。

如果透過 `mastra dev` 或 `mastra start` 啟動的伺服器已啟用可觀測性指標，Mastra 亦會在啟動時傳送匿名的彙總模型用量：各個 Provider 和模型的輸入與輸出 token 數量，以及所用指令（`dev` 或 `start`）和 `NODE_ENV`。系統絕不會傳送 prompt、回應或任何其他訊息內容。你可以閱讀[原始碼](https://github.com/mastra-ai/mastra/blob/main/packages/core/src/telemetry/usage-telemetry.ts)，查看所收集的資訊。

伺服器啟動時，Mastra 亦會傳送匿名的項目組成快照：已註冊 Agent、Agent controller、Workflow、Tool、processor、vector store、scorer、Workspace、MCP server、gateway 和 channel 的數量，以及是否使用 memory、voice、editor 和 observability 的布林值，還有概略的儲存後端類別。快照不會傳送名稱或識別符。你可以閱讀[原始碼](https://github.com/mastra-ai/mastra/blob/main/packages/core/src/telemetry/feature-telemetry.ts)，查看所收集的資訊。

你可以設定環境變數，停用所有 CLI 和用量分析：

```bash
MASTRA_TELEMETRY_DISABLED=1
```

你亦可以在使用其他 `mastra` 指令時設定此變數：

```bash
MASTRA_TELEMETRY_DISABLED=1 mastra dev
```