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

# CLI 命令

你可以使用 Mastra 提供的命令列介面 (CLI) 來開發、建置及啟動 Mastra 專案。

## `mastra dev`

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

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

### 旗標

此命令接受[通用旗標](#common-flags)及下列其他旗標：

#### `--https`

啟用本機 HTTPS 支援。[深入瞭解](https://mastra.zisheng.pro/zh-TW/reference/configuration)。

#### `--inspect`

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

#### `--inspect-brk`

以 inspect 模式啟動開發伺服器，並在指令碼開頭中斷。你也可以指定自訂主機與連接埠（例如 `--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-TW/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，讓請求透過 Proxy 或內部閘道重新導向。以 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/) 是輕量且型別安全的 Web 框架，能讓你輕鬆將 Mastra Agent 部署為支援中介軟體的 HTTP 端點。

在底層，Mastra 的 Rollup 伺服器會找出 Mastra 進入點檔案，並將其封裝成可用於正式環境的 Hono 伺服器。封裝過程會對程式碼執行 tree-shaking，並產生用於偵錯的 source map。

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

若要部署至 [serverless 平台](https://mastra.zisheng.pro/zh-TW/docs/deployment/cloud-providers)，你需要安裝正確的部署器，才能在 `.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 start` 前，需要先執行 `mastra build`。

啟動本機伺服器，以正式模式提供已建置的 Mastra 應用程式。預設會啟用 [OTEL Tracing](https://mastra.zisheng.pro/zh-TW/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` 會將產出物識別為 `mastra-experiment-worker` 版本 `1`，並提供：

- 內嵌於可執行檔中的 CLI 版本、建立時間與唯一建置 ID。
- 支援的通訊協定與資料集正規化版本。
- 啟動 worker 所需的可執行檔、引數與工作目錄。
- 相依套件資訊清單與產生的 lockfile 路徑。
- 每個產出物檔案依序排列的 SHA-256 摘要。
- 由這些檔案路徑與摘要衍生的 SHA-256 內容摘要。

內容摘要會排除 `experiment-worker-manifest.json`，避免摘要參照自身。請將資訊清單與目錄中的其餘內容一起封裝。若必須證明資訊清單本身，請使用外層套件摘要。

### 通訊協定契約

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

執行請求必須符合產出物內嵌的建置 ID，並包含已排序的資料集項目數量與 SHA-256 證明。Worker 會發出從 `0` 開始的連續序號、由計時器驅動的 heartbeat、已等待完成的實驗生命週期事件，以及恰好一個終止事件。取消操作必須符合作用中的通訊協定版本、實驗 ID、工作 ID、嘗試次數與冪等性金鑰。

通訊協定結束程式碼如下：

| 程式碼  | 意義         |
| ---- | ---------- |
| `0`  | 已完成        |
| `10` | 已完成，但有項目錯誤 |
| `20` | 嚴重失敗       |
| `21` | 可重試失敗      |
| `30` | 已取消        |
| `31` | 已逾時        |
| `70` | 通訊協定失敗     |

### 封包欄位處理

Worker 會將目標身分、已排序的內嵌資料集項目、評分器 ID、並行處理數量、逾時、實驗中繼資料、請求情境、Tool mock 與取消操作傳給 `runExperiment`。評分器版本與產出物來源會保留為實驗中繼資料。評分器程式碼來源會透過產出物准入機制強制執行，而不是在執行階段查詢評分器。

版本 `1` 會以確定性方式拒絕未宣告的 Tool。非空白的網路允許清單與祕密參照會因政策失敗而遭拒絕，因為網路強制執行與祕密具現化屬於處理程序 Sandbox 的職責。資料集項目的來源與預期軌跡欄位，在傳給 `runExperiment` 時會保留為項目中繼資料。

### 旗標

#### `--dir`

Mastra 原始碼目錄的路徑。預設為 `src/mastra`。

#### `--root`

專案根目錄。預設為目前目錄。

#### `--output-dir`

自訂產出物目錄。相對路徑會從專案根目錄解析。預設為 `.mastra/experiment-worker`。

#### `--debug`

啟用建置期間的偵錯記錄。

## `mastra worker start`

> **資訊:** 使用 `mastra worker start` 前，需要先執行 `mastra worker build` 或 `mastra build`。

從先前建置的 bundle 啟動 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-TW/docs/deployment/workers)。

## `mastra studio`

以靜態伺服器啟動 [Studio](https://mastra.zisheng.pro/zh-TW/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-TW/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` 並壓縮輸出。上傳所有內容至平台前，它會從專案目錄讀取環境檔案。上傳後，命令會輪詢部署狀態並串流建置記錄，直到部署進入終止狀態。

部署命令會自動載入專案的 `.env` 檔案。如果 `MASTRA_PROJECT_ID` 指向為可觀測性佈建的專案，部署會連結至該專案，而不是建立新專案。將 Studio 部署至僅供可觀測性使用的專案，會在平台端將其轉換為 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 與伺服器命令。新設定應使用 `mastra deploy`。

將專案建置並部署至 Mastra 平台上的伺服器。其運作方式與 [`mastra studio deploy`](#mastra-studio-deploy) 相同，旗標、引數與解析邏輯也相同。

部署命令會自動載入專案的 `.env` 檔案。如果 `MASTRA_PROJECT_ID` 指向為可觀測性佈建的專案，部署會連結至該專案，而不是建立新專案。將伺服器部署至僅供可觀測性使用的專案，會在平台端將其轉換為伺服器專案。

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

### `mastra server deploy suggestions`

顯示失敗伺服器部署的診斷結果與建議修正方式。

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

如果省略 `deploy-id`，命令會使用已連結專案的最新部署。如果診斷尚不存在，命令會啟動診斷並輪詢至結果就緒。只有診斷發現問題時，才會顯示建議。

## `mastra server pause`

暫停已連結專案中正在執行的伺服器執行個體。組織與專案的解析方式和 [`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`

重新啟動已連結專案中暫停或停止的伺服器執行個體。平台接受重新啟動後，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`

管理已連結伺服器部署的環境變數。組織與專案的解析方式和 [`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` 檔案）匯入變數，並合併至現有的對應表。新值會覆寫伺服器上已存在的鍵。

```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` 執行 bundle 檢查。

```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` 命令提供評估用評分器的管理功能；這些評分器會測量 AI 產生輸出的品質、準確度與效能。

請閱讀[評分器概覽](https://mastra.zisheng.pro/zh-TW/docs/evals/overview)以深入瞭解。

### `add`

將新的評分器新增至專案。你可以使用互動式提示：

```bash
mastra scorers add
```

或直接提供評分器名稱：

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

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

### `list`

列出所有可用的評分器模板。請在 `add` 命令中使用其 ID。

## `mastra create`

使用與 [`create-mastra`](https://mastra.zisheng.pro/zh-TW/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-TW/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 伺服器設定程式碼編輯器。可選擇：`"cursor" | "cursor-global" | "windsurf" | "vscode"`。

#### `--observability`

在 Mastra 平台上啟用可觀測性。CLI 會提示你選擇現有平台專案或建立新專案，接著寫入必要的環境變數並設定可觀測性 exporter。

#### `--no-observability`

略過 Mastra 可觀測性提示。

#### `--observability-project`

設定啟用 Mastra 可觀測性時要使用的平台專案名稱。

## `mastra migrate`

執行資料庫遷移以更新儲存空間 schema。升級至包含儲存空間 schema 變更的 Mastra 版本時，此命令很實用。

此命令會封裝專案並連線至設定的儲存空間後端，接著執行所有待處理的遷移。目前支援：

- **重複 span 遷移**：移除重複的 `(traceId, spanId)` 項目，並新增唯一限制以確保資料完整性。
- **ClickHouse 舊版至 vNext 的 span 遷移**：將歷史 span 從舊版 `mastra_ai_spans` 資料表複製至 vNext `mastra_span_events` schema。遷移會分批執行，以維持在記憶體限制內。詳情請參閱 [ClickHouse 儲存空間參考文件](https://mastra.zisheng.pro/zh-TW/reference/storage/clickhouse)。

```bash
mastra migrate
```

如需瞭解何時需要遷移，請參閱[儲存空間遷移指南](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/storage)。

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

## `mastra api`

使用 JSON 輸入與 JSON 輸出呼叫 Mastra 執行環境伺服器。你可以將其用於本機開發伺服器、已部署的 Mastra 平台專案、自行代管的 Mastra 伺服器，或代管的 Mastra 平台可觀測性 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": {}
  }
}
```

### 目標解析

對於執行環境命令，系統會依下列順序解析目標伺服器：

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

只有當 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 執行的啟動與恢復命令預設為 `120000`。

#### `--pretty`

以易讀格式輸出 JSON。預設為 `false`。

#### `--schema`

為接受 JSON 輸入的命令輸出 CLI 專用的請求 schema。此 schema 來自目標伺服器的路由契約，包含命令形式、位置引數、範例、請求 schema 與回應形式。

`--schema` 可用於接受 JSON 輸入的末端命令，但不能作為最上層 `mastra api` 旗標使用。

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

### 輸入模型

接受輸入的命令會接收一個內嵌 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
```

某些命令有重要的執行階段需求。例如，`mastra api memory current update` 要求記憶體執行個體已啟用工作記憶體，而 `mastra api workflow run resume` 只適用於暫停的 Workflow 執行。

### 命令

#### `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。請使用命令說明查看文字提示、聊天訊息與記憶體 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 執行。由於執行可能需要較長時間才能完成，Workflow 啟動命令的預設逾時時間比大多數命令更長。

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

#### `mastra api workflow run list`

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

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

#### `mastra api workflow run get`

依 ID 取得一個 Workflow 執行。

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

#### `mastra api workflow run resume`

使用 JSON 輸入恢復暫停的 Workflow 執行。該執行必須處於暫停狀態。

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

#### `mastra api workflow run cancel`

取消 Workflow 執行。

```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`

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

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

#### `mastra api thread get`

依 ID 取得一個記憶體 thread。

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

#### `mastra api thread create`

建立記憶體 thread。傳入一個 JSON 輸入物件；伺服器路由有需要時，CLI 會將 `agentId` 等欄位拆分成查詢參數。

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

#### `mastra api thread update`

更新記憶體 thread。傳入一個 JSON 輸入物件，用於 `agentId`、`resourceId`、`title` 或 `metadata` 等欄位。

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

#### `mastra api thread delete`

刪除記憶體 thread。傳入 JSON 輸入，以提供路由要求的查詢參數，例如 `agentId` 與 `resourceId`。

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

#### `mastra api thread messages`

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

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

#### `mastra api memory search`

搜尋長期記憶體。使用 `--help` 或 `--schema` 檢查 `agentId`、`resourceId` 與 `searchQuery` 等必填欄位。

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

#### `mastra api memory current get`

讀取 thread 目前的工作記憶體。

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

#### `mastra api memory current update`

更新 thread 目前的工作記憶體。記憶體執行個體必須已啟用工作記憶體。

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

#### `mastra api memory status`

取得 Agent 的記憶體狀態，以及選用的 thread 或資源情境。

```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 記錄，因此你可以逐頁瀏覽 Trace，而不必擷取大型輸入、輸出、屬性或中繼資料 payload。傳入 `--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`

取得單一彙總指標值。

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

#### `mastra api metric breakdown`

取得依標籤或欄位分組的指標值。

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

#### `mastra api metric timeseries`

取得一段時間內的指標值。

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

#### `mastra api metric percentiles`

取得一段時間內的指標百分位數值。百分位數值使用 `0` 到 `1` 之間的小數。

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

#### `mastra api metric names`

列出找到的指標名稱。可傳入選用的 JSON 輸入，以設定前綴搜尋與數量限制。

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

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

列出指標的標籤鍵。

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

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

列出指標標籤鍵的標籤值。傳入選用的前綴與數量限制值可縮小結果範圍。

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

#### 以 `curl` 使用可觀測性

你可以使用平台存取 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 body 形式。使用 `--schema` 檢查此形式。

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

#### `mastra api score list`

列出可觀測性分數。可傳入選用的 JSON 輸入，以使用執行 ID 或分頁等篩選條件。

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

#### `mastra api score get`

依 ID 取得一個可觀測性分數。

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

#### `mastra api dataset list`

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

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

#### `mastra api dataset get`

依 ID 取得一個資料集。

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

#### `mastra api dataset create`

使用 JSON 輸入建立資料集。

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

#### `mastra api dataset items`

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

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

#### `mastra api experiment list`

列出資料集的實驗。可傳入選用的 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 輸入啟動資料集的實驗。

```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`

列出實體的分析快照，以及依序排列、以逗號分隔的 Trace signal 清單。後續命令需要使用此清單中的 `snapshotId`。

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

#### `mastra api learning flow`

取得一個快照的跨 signal 主題流程：供 Sankey 樣式檢視使用的階段與連結，其中計數代表不重複的 Trace。

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

#### `mastra api learning paths`

取得一個快照中依序排列的 Trace signal 所對應、逐 Trace 的主題指派。使用 `limit` 與 `offset` 進行分頁。

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

#### `mastra api learning theme list`

列出一個快照中某個 Trace signal 的主題。

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

#### `mastra api learning theme get`

依數字主題 ID 取得一個快照中的一個主題。

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

#### `mastra api learning theme examples`

列出一個快照中某個主題的 Trace 範例。使用 `limit` 與 `offset` 進行分頁。

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

#### `mastra api learning theme history`

取得持久主題在各快照中的生命週期歷程，包括拆分與合併關係。不接受 `snapshotId`。

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

#### `mastra api learning noise get`

取得一個快照中某個 Trace signal 未分群的（雜訊）分組。

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

#### `mastra api learning noise examples`

列出一個快照中雜訊分組的 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`。系統絕不會傳送提示詞、回應或其他訊息內容。你可以閱讀[原始碼](https://github.com/mastra-ai/mastra/blob/main/packages/core/src/telemetry/usage-telemetry.ts)，查看收集了哪些內容。

伺服器啟動時，Mastra 也會傳送匿名的專案介面快照：已註冊的 Agent、Agent controller、Workflow、Tool、processor、向量儲存空間、評分器、Workspace、MCP 伺服器、閘道與頻道數量，以及記憶體、語音、編輯器及可觀測性使用狀態的布林值，另包括概略的儲存空間後端類別。系統不會傳送名稱或識別碼。你可以閱讀[原始碼](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
```