CLI 命令

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

`mastra dev`
「mastra-dev」的直接連結

啟動伺服器，提供 Studio 以及 Agent、Tool 和 Workflow 的 REST 端點。mastra dev 執行後，你可以前往 http://localhost:4111/swagger-ui 查看所有可用端點的概覽。

你也可以設定伺服器。

旗標
「旗標」的直接連結

此命令接受通用旗標及下列其他旗標：

`--inspect`
「--inspect」的直接連結

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

`--inspect-brk`
「--inspect-brk」的直接連結

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

`--custom-args`
「--custom-args」的直接連結

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

`--request-context-presets`
「--request-context-presets」的直接連結

包含請求情境預設組態的 JSON 檔案路徑。提供此旗標時，Studio 的請求情境編輯器會顯示下拉式選單，讓你快速切換預設組態。

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

該檔案必須是 JSON 物件，其中每個鍵都是預設組態名稱，每個值都是物件：

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

設定
「設定」的直接連結

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

略過 peer 相依套件檢查
「略過 peer 相依套件檢查」的直接連結

設定 MASTRA_SKIP_PEERDEP_CHECK=1，即可略過啟動時的 peer 相依套件版本不符檢查：

MASTRA_SKIP_PEERDEP_CHECK=1 mastra dev

在 monorepo 開發期間，peer 相依套件可能已更新、但套件尚未發布時，這項設定很實用。

自訂 Provider 端點
「自訂 Provider 端點」的直接連結

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

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

以 Anthropic 為例：

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

這些設定會轉送至 Mastra 模型路由器，適用於任何選擇的 "openai/..." 或 "anthropic/..." 模型。

`mastra factory dev`
「mastra-factory-dev」的直接連結

啟動用於開發 Agent Builder 的開發伺服器。此命令使用與 mastra dev 相同的開發執行環境與旗標，並寫入相同的 .mastra/output 目錄。

npx mastra factory dev

兩個命令共用同一個開發鎖定，因此 mastra dev 與 mastra factory dev 無法在同一個專案中同時執行。若其中一個已在執行，另一個會因重複開發伺服器錯誤而結束。

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

`mastra build`
「mastra-build」的直接連結

mastra build 命令會將 Mastra 專案封裝成可用於正式環境的 Hono 伺服器。Hono 是輕量且型別安全的 Web 框架，能讓你輕鬆將 Mastra Agent 部署為支援中介軟體的 HTTP 端點。

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

.mastra 中的輸出可使用 mastra start 部署至任何雲端伺服器。

若要部署至 serverless 平台，你需要安裝正確的部署器，才能在 .mastra 中取得正確輸出。

此命令接受通用旗標。

設定
「設定」的直接連結

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

略過 peer 相依套件檢查
「略過 peer 相依套件檢查」的直接連結

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

MASTRA_SKIP_PEERDEP_CHECK=1 mastra build

限制平行處理數量
「限制平行處理數量」的直接連結

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

MASTRA_CONCURRENCY=2 mastra build

`mastra start`
「mastra-start」的直接連結

資訊

使用 mastra start 前，需要先執行 mastra build。

啟動本機伺服器，以正式模式提供已建置的 Mastra 應用程式。預設會啟用 OTEL Tracing。

旗標
「旗標」的直接連結

此命令接受通用旗標及下列其他旗標：

`--dir`
「--dir」的直接連結

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

`--custom-args`
「--custom-args-1」的直接連結

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

`mastra worker build`
「mastra-worker-build」的直接連結

封裝 Mastra 應用程式以部署 worker。產生與 mastra build 相同的輸出：獨立完整的 .mastra/output/ 目錄。

mastra worker build [options]

旗標
「旗標」的直接連結

`--output-dir`
「--output-dir」的直接連結

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

`mastra experiment build`
「mastra-experiment-build」的直接連結

建置獨立的輔助 worker，用於執行實驗而不公開 HTTP 伺服器。此 worker 會載入匯出的 Mastra 執行個體，並透過標準輸入接受有版本控制、以換行分隔的 JSON (NDJSON) 通訊協定訊息，再將通訊協定事件寫入標準輸出。

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 時會保留為項目中繼資料。

旗標
「旗標」的直接連結

`--output-dir`
「--output-dir-1」的直接連結

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

`mastra worker start`
「mastra-worker-start」的直接連結

資訊

使用 mastra worker start 前，需要先執行 mastra worker build 或 mastra build。

從先前建置的 bundle 啟動 worker 處理程序。選用的 name 引數會在衍生處理程序中設定 MASTRA_WORKERS，以控制要啟動的 worker。

mastra worker start [name] [options]

旗標
「旗標」的直接連結

`--env`
「--env」的直接連結

環境檔案的路徑。預設為 .env.production，若不存在則回退至 .env。

`mastra studio`
「mastra-studio」的直接連結

以靜態伺服器啟動 Studio。啟動後，你可以輸入 Mastra 執行個體 URL（例如 http://localhost:4111），將 Studio 連線至 Mastra 後端。此命令會在目前工作目錄中尋找 .env 與 .env.production 檔案以進行設定。

旗標
「旗標」的直接連結

此命令接受通用旗標及下列其他旗標：

`--server-host`
「--server-host」的直接連結

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

`--server-port`
「--server-port」的直接連結

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

`--server-protocol`
「--server-protocol」的直接連結

要連線的 Mastra API 伺服器通訊協定。預設為 http。

`--server-api-prefix`
「--server-api-prefix」的直接連結

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

`--request-context-presets`
「--request-context-presets-1」的直接連結

包含請求情境預設組態的 JSON 檔案路徑。運作方式與 mastra dev 旗標相同。

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

`mastra deploy`
「mastra-deploy」的直接連結

將專案建置並部署至 --env 所選的 Mastra 平台環境。建議所有新的部署都使用此命令；它取代了 mastra studio deploy 與 mastra server deploy。後兩者仍可使用，但新設定不應再採用。

此命令需要透過 mastra auth login 或 MASTRA_API_TOKEN 環境變數進行驗證。

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 後，只要一個非互動式命令即可建立並部署所有內容：

mastra deploy --env staging --yes

設定 --env <name> 且未設定 --env-file 時，如果專案目錄中有 .env.<name>（例如 .env.staging），CLI 會自動選用。將 <name> 插入檔案路徑前，系統會先根據嚴格的允許清單進行驗證。

引數
「引數」的直接連結

`[dir]`
「dir」的直接連結

旗標
「旗標」的直接連結

`--env`
「--env-1」的直接連結

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

`--org`
「--org」的直接連結

組織 ID。也可以透過 MASTRA_ORG_ID 環境變數設定。

`--project`
「--project」的直接連結

專案 ID、slug 或名稱。也可以透過 MASTRA_PROJECT_ID 環境變數設定。如果沒有相符的專案，該值會作為部署時要建立的新專案名稱。

`-y, --yes`
「-y---yes」的直接連結

自動接受預設值，不顯示確認提示，包括建立專案與環境。

`-c, --config`
「-c---config」的直接連結

專案設定檔的路徑。預設為 .mastra-project.json。

`--env-file`
「--env-file」的直接連結

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

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

`--region`
「--region」的直接連結

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

`--skip-build`
「--skip-build」的直接連結

略過建置步驟，部署現有的 .mastra/output 目錄。如果現有建置內容相對於目前原始碼已過期，CLI 會顯示警告。

`--skip-preflight`
「--skip-preflight」的直接連結

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

`--debug`
「--debug-2」的直接連結

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

CI/CD 用法
「CI/CD 用法」的直接連結

若要進行無介面部署，請將 MASTRA_API_TOKEN、MASTRA_ORG_ID 與 MASTRA_PROJECT_ID 設為環境變數。設定 MASTRA_API_TOKEN 後，會自動略過互動式提示。搭配 --yes 可自動接受建立環境。

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

`mastra env`
「mastra-env」的直接連結

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

每個子命令都會依固定順序解析專案。它會先檢查 MASTRA_PROJECT_ID 環境變數與 --project <name|slug|id> 旗標，接著讀取目前目錄中由 mastra deploy 寫入的 .mastra-project.json 檔案。只要從專案目錄執行，就不需要指定專案。

`mastra env list`
「mastra-env-list」的直接連結

列出專案的環境。每個環境都會顯示最新部署（正在提供流量時會標示 (active)），以及附加資料庫等受管理資源所注入的環境變數名稱。

mastra env list

`--json`
「--json」的直接連結

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

`mastra env create`
「mastra-env-create」的直接連結

為專案建立新環境。

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

`-t, --type`
「-t---type」的直接連結

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

`-r, --region`
「-r---region」的直接連結

環境的區域（例如 eu）。

`--json`
「--json-1」的直接連結

輸出機器可讀的 JSON。與 mastra env list 相同，會省略敏感欄位。

`mastra env delete`
「mastra-env-delete」的直接連結

刪除環境。

mastra env delete <env>

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

`-y, --yes`
「-y---yes-1」的直接連結

略過確認提示。

`mastra env restart`
「mastra-env-restart」的直接連結

重新啟動環境中正在執行的服務，讓儲存的環境變數（包括附加資料庫提供的受管理變數）立即生效，不需要重新部署。

mastra env restart <env>

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

`mastra env vars pull`
「mastra-env-vars-pull」的直接連結

將環境的環境變數提取至本機環境檔案（預設為 .env）。該檔案包含部署使用的合併後變數組合，會結合環境中儲存的變數（例如在儀表板的環境編輯器中新增的變數）與專案層級變數。發生衝突時，以專案值為準。附加資料庫所注入的受管理變數會以註解列出（僅列名稱），因為其值是由平台管理的祕密。

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

<env> 可以是環境名稱、slug 或 ID；當專案恰好只有一個環境時，也可以省略。檔案會以 0600 權限寫入。如果輸出檔案已存在，命令會停止。傳入 --force 可取代該檔案。

`-o, --output`
「-o---output」的直接連結

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

`-f, --force`
「-f---force」的直接連結

取代現有輸出檔案。

`mastra env db`
「mastra-env-db」的直接連結

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

資料庫可以是環境範圍（其環境變數只提供給一個環境）或共用（專案範圍：其環境變數提供給所有環境）。mastra env db create 預設使用環境範圍：傳入環境引數，或讓 CLI 選擇或提示你選擇。建立時傳入 --shared，即可改為附加共用資料庫。使用其他子命令（list、delete、keys）時，傳入環境引數以操作環境範圍資料庫；省略則操作共用資料庫。

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

`mastra env db list`
「mastra-env-db-list」的直接連結

列出附加至專案的資料庫，包括 Provider、佈建狀態、範圍（各資料庫提供給哪個環境），以及各資料庫注入的環境變數名稱。傳入環境即可只顯示提供給該環境的資料庫（環境範圍及共用資料庫）。

mastra env db list
mastra env db list <env>

`--json`
「--json-2」的直接連結

輸出機器可讀的 JSON。

`mastra env db create`
「mastra-env-db-create」的直接連結

佈建並附加受管理的資料庫，接著輪詢直到資料庫就緒。佈建錯誤會連同 Provider 的錯誤詳細資訊一起輸出。

資料庫預設只屬於單一環境範圍：傳入環境引數以選擇環境，或省略引數讓 CLI 代為選擇。專案只有一個環境時，會使用該環境。專案有多個環境時，CLI 會透過互動方式提示你選擇；在非互動式情境（CI、--json）中則必須提供環境引數。傳入 --shared 可改為附加由所有環境共用的專案範圍資料庫。

環境範圍資料庫會繼承環境的 Provider 區域。共用資料庫可接受 --region。

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`
「--kind」的直接連結

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

`--name`
「--name」的直接連結

資料庫名稱。預設為衍生自專案 slug 的名稱（例如 my-app-db）。

`--region`
「--region-1」的直接連結

共用資料庫的 Provider 區域 ID。環境範圍資料庫會忽略此旗標。

`--shared`
「--shared」的直接連結

附加為由所有環境共用的專案範圍資料庫。不能與環境引數同時使用。

`--no-wait`
「--no-wait」的直接連結

附加操作排入佇列後會立即回傳，不會輪詢至資料庫就緒。稍後可使用 mastra env db show 查看進度。

`--json`
「--json-3」的直接連結

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

`mastra env db show`
「mastra-env-db-show」的直接連結

顯示資料庫詳細資訊；資料庫就緒後，也會顯示其連線環境變數。祕密值預設會遮蔽。

mastra env db show <database>

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

`--show-secrets`
「--show-secrets」的直接連結

輸出祕密連線值，而不是將其遮蔽。

`--json`
「--json-4」的直接連結

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

`mastra env db delete`
「mastra-env-db-delete」的直接連結

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

mastra env db delete <database>

`-y, --yes`
「-y---yes-2」的直接連結

略過確認提示。

`mastra env deploys`
「mastra-env-deploys」的直接連結

列出專案的部署，最新部署會顯示在最前面。正在提供流量的部署會標示 (active)。

mastra env deploys [environment]

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

`--json`
「--json-5」的直接連結

輸出機器可讀的 JSON。

`mastra studio deploy`
「mastra-studio-deploy」的直接連結

資訊

mastra studio deploy 仍可使用，但已由 mastra deploy 取代。後者可在單一專案上支援多個環境（--env staging、--env production）。新設定應使用 mastra deploy。

將專案建置並部署至 Mastra 平台。此命令需要透過 mastra auth login 或 MASTRA_API_TOKEN 環境變數進行驗證。

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 後，只要一個非互動式命令即可建立並部署新專案：

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

引數
「引數」的直接連結

`[dir]`
「dir-1」的直接連結

旗標
「旗標」的直接連結

`--org`
「--org-1」的直接連結

組織 ID。也可以透過 MASTRA_ORG_ID 環境變數設定。

`--project`
「--project-1」的直接連結

專案 ID 或 slug。也可以透過 MASTRA_PROJECT_ID 環境變數設定。如果沒有相符的專案，該值會作為部署時要建立的新專案名稱。

`-y, --yes`
「-y---yes-3」的直接連結

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

`-c, --config`
「-c---config-1」的直接連結

專案設定檔的路徑。預設為 .mastra-project.json。

`--env-file`
「--env-file-1」的直接連結

要與部署一併封裝的環境檔案路徑（相對於專案目錄）。如要使用不同環境檔案（例如 .env.staging、.env.production）將同一專案部署至多個環境，請使用此旗標。

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

`--skip-build`
「--skip-build-1」的直接連結

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

`--debug`
「--debug-3」的直接連結

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

CI/CD 用法
「CI/CD 用法」的直接連結

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

`mastra studio deploy list`
「mastra-studio-deploy-list」的直接連結

列出所有專案及其最新部署狀態與 URL。

`mastra studio deploy status`
「mastra-studio-deploy-status」的直接連結

顯示特定部署的狀態。

mastra studio deploy status <deploy-id>

`--watch, -w`
「--watch--w」的直接連結

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

`mastra studio deploy logs`
「mastra-studio-deploy-logs」的直接連結

顯示特定部署的記錄。

mastra studio deploy logs <deploy-id>

`--follow, -f`
「--follow--f」的直接連結

即時串流記錄。

`--tail`
「--tail」的直接連結

要顯示的最近記錄行數。

`mastra studio deploy suggestions`
「mastra-studio-deploy-suggestions」的直接連結

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

mastra studio deploy suggestions [deploy-id]

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

`mastra studio projects`
「mastra-studio-projects」的直接連結

列出目前組織中的所有專案。

`mastra studio projects create`
「mastra-studio-projects-create」的直接連結

透過互動式提示建立新專案。此命令不接受 --name 旗標；若要以非互動方式建立專案，請改用 mastra studio deploy --project <name> --yes，它會在單一步驟中建立並部署專案。

`mastra server deploy`
「mastra-server-deploy」的直接連結

資訊

mastra server deploy 仍可使用，但已由 mastra deploy 取代。後者會將單一專案部署至多個環境，而不是使用各自獨立的 Studio 與伺服器命令。新設定應使用 mastra deploy。

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

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

mastra server deploy [dir]

`mastra server deploy suggestions`
「mastra-server-deploy-suggestions」的直接連結

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

mastra server deploy suggestions [deploy-id]

`mastra server pause`
「mastra-server-pause」的直接連結

暫停已連結專案中正在執行的伺服器執行個體。組織與專案的解析方式和 mastra server deploy 相同。

mastra server pause

旗標
「旗標」的直接連結

`--org`
「--org-2」的直接連結

組織 ID。也可以透過 MASTRA_ORG_ID 環境變數設定。

`--project`
「--project-2」的直接連結

未設定 MASTRA_PROJECT_ID 時使用的專案 ID 或 slug。Slug 會與目前組織中的專案進行比對解析。

`-c, --config`
「-c---config-2」的直接連結

專案設定檔的路徑。預設為 .mastra-project.json。

如果執行個體未在執行，命令會失敗。

`mastra server restart`
「mastra-server-restart」的直接連結

重新啟動已連結專案中暫停或停止的伺服器執行個體。平台接受重新啟動後，CLI 會解析部署 ID（從 API 回應取得；若回應省略 ID，則輪詢專案與部署中繼資料），接著以與 mastra server deploy 相同的方式串流建置與部署記錄，直到部署進入終止狀態。

旗標
「旗標」的直接連結

與 mastra server pause 相同：--org、--project 及 -c / --config，預設值與行為也相同。

mastra server restart

如果此專案仍有作用中的部署（執行中、建置中、部署中等），命令會失敗。這是平台限制，可避免你在其他部署進行期間重新啟動。

`mastra server env`
「mastra-server-env」的直接連結

管理已連結伺服器部署的環境變數。組織與專案的解析方式和 mastra server deploy 相同。

每個子命令都接受 -c / --config，用於指定專案設定檔路徑（預設為 .mastra-project.json）。

`mastra server env list`
「mastra-server-env-list」的直接連結

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

`mastra server env set`
「mastra-server-env-set」的直接連結

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

mastra server env set <key> <value>

`mastra server env unset`
「mastra-server-env-unset」的直接連結

移除環境變數。

mastra server env unset <key>

`mastra server env import`
「mastra-server-env-import」的直接連結

從檔案（例如 .env 檔案）匯入變數，並合併至現有的對應表。新值會覆寫伺服器上已存在的鍵。

mastra server env import <file>

`mastra server env pull`
「mastra-server-env-pull」的直接連結

從已連結專案下載環境變數，並寫入本機檔案。這是 mastra server env import 的反向操作。

mastra server env pull [file]

未提供引數時，檔案預設為 .env。所有值都會以雙引號括住並逸出，以便安全地載入 shell。不是有效 shell 識別碼的鍵會略過。由於輸出檔案包含祕密，因此會以限制嚴格的權限 (0600) 建立。

`--project`
「--project-3」的直接連結

專案 ID 或 slug。未設定 MASTRA_PROJECT_ID 時，會覆寫已連結的專案。

CI 用法
「CI 用法」的直接連結

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

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

`mastra auth`
「mastra-auth」的直接連結

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

`mastra auth login`
「mastra-auth-login」的直接連結

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

`mastra auth logout`
「mastra-auth-logout」的直接連結

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

`mastra auth whoami`
「mastra-auth-whoami」的直接連結

顯示目前使用者的電子郵件、使用者 ID 與作用中組織。

`mastra auth orgs`
「mastra-auth-orgs」的直接連結

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

`mastra auth orgs switch`
「mastra-auth-orgs-switch」的直接連結

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

`mastra auth tokens`
「mastra-auth-tokens」的直接連結

列出所有 API token 及其上次使用日期。

`mastra auth tokens create`
「mastra-auth-tokens-create」的直接連結

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

mastra auth tokens create <name>

`mastra auth tokens revoke`
「mastra-auth-tokens-revoke」的直接連結

撤銷 API token。

mastra auth tokens revoke <token-id>

`mastra lint`
「mastra-lint」的直接連結

mastra lint 命令會驗證 Mastra 專案的結構與程式碼。

mastra lint 預設會針對原始碼檔案與設定執行專案檢查。使用 --preflight 可在部署前一併針對 .mastra/output 執行 bundle 檢查。

mastra lint --preflight

此命令接受通用旗標。

旗標
「旗標」的直接連結

`--preflight`
「--preflight」的直接連結

針對已建置的 Mastra 輸出執行部署前檢查。除非同時傳入 --skip-build，否則會先建置專案再進行檢查。

`--skip-build`
「--skip-build-2」的直接連結

略過建置步驟，重複使用現有的 .mastra/output 目錄。只有設定 --preflight 時，此旗標才適用。

`--env-file <file>`
「--env-file-file」的直接連結

使用指定的環境檔案進行部署前驗證。只有設定 --preflight 時，此旗標才適用。

`--strict`
「--strict」的直接連結

將警告視為錯誤。

`--json`
「--json-6」的直接連結

輸出機器可讀的 JSON。

`--debug`
「--debug-4」的直接連結

啟用偵錯記錄。

`mastra scorers`
「mastra-scorers」的直接連結

mastra scorers 命令提供評估用評分器的管理功能；這些評分器會測量 AI 產生輸出的品質、準確度與效能。

請閱讀評分器概覽以深入瞭解。

`add`
「add」的直接連結

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

mastra scorers add

或直接提供評分器名稱：

mastra scorers add answer-relevancy

使用 list 命令取得正確的 ID。

`list`
「list」的直接連結

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

`mastra create`
「mastra-create」的直接連結

使用與 create-mastra 相同的專案建立流程，建立獨立的 Mastra 專案。

npm
pnpm
Yarn
Bun

npx mastra@latest create

pnpm dlx mastra@latest create

yarn dlx mastra@latest create

bun x mastra@latest create

同時提供專案名稱與 --llm，即可略過互動式設定提示。使用 --template [template] 可指定任意模板，或使用 --empty 建立最小化且不含 Provider 的骨架。

此命令會為偵測到的程式設計助理安裝 Mastra Skill，並在適當情況下初始化 Git。使用 --no-skills 或 --no-git 可選擇退出。

如需各模式的行為、衝突、驗證與完整旗標說明，請參閱 create-mastra 參考文件。

`mastra init`
「mastra-init」的直接連結

mastra init 命令會在現有專案中初始化 Mastra。使用此命令可建立必要的資料夾與設定，不必從頭產生新專案。

旗標
「旗標」的直接連結

此命令接受下列其他旗標：

`--default`
「--default」的直接連結

使用 OpenAI 在 src 中建立檔案，也會在 src/mastra 資料夾中填入範例程式碼。

`--dir`
「--dir-4」的直接連結

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

`--components`
「--components」的直接連結

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

`--llm`
「--llm」的直接連結

`--llm-api-key`
「--llm-api-key」的直接連結

所選模型 Provider 的 API 金鑰。此值會寫入環境變數檔案 (.env)。

`--example`
「--example」的直接連結

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

`--no-example`
「--no-example」的直接連結

不包含範例程式碼。使用 --default 旗標時很實用。

`--mcp`
「--mcp」的直接連結

使用 Mastra 的 MCP 伺服器設定程式碼編輯器。可選擇："cursor" | "cursor-global" | "windsurf" | "vscode"。

`--observability`
「--observability」的直接連結

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

`--no-observability`
「--no-observability」的直接連結

略過 Mastra 可觀測性提示。

`--observability-project`
「--observability-project」的直接連結

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

`mastra migrate`
「mastra-migrate」的直接連結

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

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

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

mastra migrate

如需瞭解何時需要遷移，請參閱儲存空間遷移指南。

此命令接受通用旗標。

`mastra api`
「mastra-api」的直接連結

使用 JSON 輸入與 JSON 輸出呼叫 Mastra 執行環境伺服器。你可以將其用於本機開發伺服器、已部署的 Mastra 平台專案、自行代管的 Mastra 伺服器，或代管的 Mastra 平台可觀測性 API。

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。單一資源命令會傳回：

{ "data": {} }

清單命令會傳回 data 陣列與分頁中繼資料：

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

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

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

目標解析
「目標解析」的直接連結

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

使用 --url <url> 明確指定遠端或自行代管的伺服器。
本機 mastra dev 伺服器的 http://localhost:4111。
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 為目標。兩者都會依下列順序解析憑證：

使用 --header 傳入的明確 Authorization 與 X-Mastra-Project-Id 標頭。
環境中的 MASTRA_PLATFORM_ACCESS_TOKEN 與 MASTRA_PROJECT_ID。
.mastra-project.json 中的專案 ID 中繼資料。
Mastra CLI 登入 token，作為驗證的回退選項。

Learning 命令也會傳送 X-Mastra-Organization-Id。此值會依序從明確的 --header、環境中的 MASTRA_ORGANIZATION_ID 或 .mastra-project.json 解析。

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

旗標
「旗標」的直接連結

`--url <url>`
「--url-url」的直接連結

將特定 Mastra 伺服器 URL 設為目標。

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

`--server-api-prefix <prefix>`
「--server-api-prefix-prefix」的直接連結

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

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

`--header <"Key: Value">`
「--header-key-value」的直接連結

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

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

`--timeout <ms>`
「--timeout-ms」的直接連結

設定請求逾時，單位為毫秒。預設為 30000。Workflow 執行的啟動與恢復命令預設為 120000。

`--pretty`
「--pretty」的直接連結

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

`--schema`
「--schema」的直接連結

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

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

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

輸入模型
「輸入模型」的直接連結

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

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

穩定的 ID 請使用位置引數，篩選條件或 payload 請使用 JSON。對於同時需要查詢參數與請求 body 的路由，請傳入一個 JSON 物件。CLI 會根據伺服器路由 schema 拆分輸入。

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

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

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

支援篩選條件的路由會在相同的 JSON 輸入中接受篩選條件。例如，可觀測性 Trace 清單支援分頁及路由支援的篩選條件：

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

取得命令專用說明
「取得命令專用說明」的直接連結

每個 mastra api 末端命令的說明輸出都包含該命令專用的範例。對要呼叫的確切命令使用 --help：

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

在接受 JSON 輸入的命令上使用 --schema，即可檢查目標伺服器傳回的請求形式：

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`
「mastra-api-agent-list」的直接連結

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

mastra api agent list [input]

`mastra api agent get`
「mastra-api-agent-get」的直接連結

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

mastra api agent get <agentId>

`mastra api agent run`
「mastra-api-agent-run」的直接連結

使用 JSON 輸入執行 Agent。請使用命令說明查看文字提示、聊天訊息與記憶體 thread 選項的範例。

mastra api agent run <agentId> <input>

`mastra api workflow list`
「mastra-api-workflow-list」的直接連結

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

mastra api workflow list [input]

`mastra api workflow get`
「mastra-api-workflow-get」的直接連結

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

mastra api workflow get <workflowId>

`mastra api workflow run start`
「mastra-api-workflow-run-start」的直接連結

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

mastra api workflow run start <workflowId> <input>

`mastra api workflow run list`
「mastra-api-workflow-run-list」的直接連結

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

mastra api workflow run list <workflowId> [input]

`mastra api workflow run get`
「mastra-api-workflow-run-get」的直接連結

依 ID 取得一個 Workflow 執行。

mastra api workflow run get <workflowId> <runId>

`mastra api workflow run resume`
「mastra-api-workflow-run-resume」的直接連結

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

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

`mastra api workflow run cancel`
「mastra-api-workflow-run-cancel」的直接連結

取消 Workflow 執行。

mastra api workflow run cancel <workflowId> <runId>

`mastra api tool list`
「mastra-api-tool-list」的直接連結

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

mastra api tool list [input]

`mastra api tool get`
「mastra-api-tool-get」的直接連結

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

mastra api tool get <toolId>

`mastra api tool execute`
「mastra-api-tool-execute」的直接連結

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

mastra api tool execute <toolId> <input>

`mastra api mcp list`
「mastra-api-mcp-list」的直接連結

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

mastra api mcp list [input]

`mastra api mcp get`
「mastra-api-mcp-get」的直接連結

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

mastra api mcp get <id>

`mastra api mcp tool list`
「mastra-api-mcp-tool-list」的直接連結

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

mastra api mcp tool list <serverId> [input]

`mastra api mcp tool get`
「mastra-api-mcp-tool-get」的直接連結

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

mastra api mcp tool get <serverId> <toolId>

`mastra api mcp tool execute`
「mastra-api-mcp-tool-execute」的直接連結

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

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

`mastra api thread list`
「mastra-api-thread-list」的直接連結

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

mastra api thread list [input]

`mastra api thread get`
「mastra-api-thread-get」的直接連結

依 ID 取得一個記憶體 thread。

mastra api thread get <threadId>

`mastra api thread create`
「mastra-api-thread-create」的直接連結

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

mastra api thread create <input>

`mastra api thread update`
「mastra-api-thread-update」的直接連結

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

mastra api thread update <threadId> <input>

`mastra api thread delete`
「mastra-api-thread-delete」的直接連結

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

mastra api thread delete <threadId> <input>

`mastra api thread messages`
「mastra-api-thread-messages」的直接連結

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

mastra api thread messages <threadId> [input]

`mastra api memory search`
「mastra-api-memory-search」的直接連結

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

mastra api memory search <input>

`mastra api memory current get`
「mastra-api-memory-current-get」的直接連結

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

mastra api memory current get <input>

`mastra api memory current update`
「mastra-api-memory-current-update」的直接連結

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

mastra api memory current update <input>

`mastra api memory status`
「mastra-api-memory-status」的直接連結

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

mastra api memory status <input>

`mastra api trace list`
「mastra-api-trace-list」的直接連結

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

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`
「mastra-api-trace-get」的直接連結

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

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

`mastra api trace span`
「mastra-api-trace-span」的直接連結

從可觀測性 Trace 取得一個完整 span。使用 trace get 確認要檢查的 span 後，再使用此命令。

mastra api trace span <traceId> <spanId>

`mastra api log list`
「mastra-api-log-list」的直接連結

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

mastra api log list [input]

`mastra api metric aggregate`
「mastra-api-metric-aggregate」的直接連結

取得單一彙總指標值。

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

`mastra api metric breakdown`
「mastra-api-metric-breakdown」的直接連結

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

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

`mastra api metric timeseries`
「mastra-api-metric-timeseries」的直接連結

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

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

`mastra api metric percentiles`
「mastra-api-metric-percentiles」的直接連結

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

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

`mastra api metric names`
「mastra-api-metric-names」的直接連結

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

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

`mastra api metric label-keys`
「mastra-api-metric-label-keys」的直接連結

列出指標的標籤鍵。

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

`mastra api metric label-values`
「mastra-api-metric-label-values」的直接連結

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

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

以 `curl` 使用可觀測性
「observability-with-curl」的直接連結

你可以使用平台存取 token 與專案 ID，直接呼叫代管的可觀測性 API：

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 時間軸：

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：

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`
「mastra-api-score-create」的直接連結

建立可觀測性分數。輸入使用伺服器的 score body 形式。使用 --schema 檢查此形式。

mastra api score create <input>

`mastra api score list`
「mastra-api-score-list」的直接連結

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

mastra api score list [input]

`mastra api score get`
「mastra-api-score-get」的直接連結

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

mastra api score get <scoreId>

`mastra api dataset list`
「mastra-api-dataset-list」的直接連結

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

mastra api dataset list [input]

`mastra api dataset get`
「mastra-api-dataset-get」的直接連結

依 ID 取得一個資料集。

mastra api dataset get <datasetId>

`mastra api dataset create`
「mastra-api-dataset-create」的直接連結

使用 JSON 輸入建立資料集。

mastra api dataset create <input>

`mastra api dataset items`
「mastra-api-dataset-items」的直接連結

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

mastra api dataset items <datasetId> [input]

`mastra api experiment list`
「mastra-api-experiment-list」的直接連結

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

mastra api experiment list <datasetId> [input]

`mastra api experiment get`
「mastra-api-experiment-get」的直接連結

依 ID 取得一個實驗。

mastra api experiment get <datasetId> <experimentId>

`mastra api experiment run`
「mastra-api-experiment-run」的直接連結

使用 JSON 輸入啟動資料集的實驗。

mastra api experiment run <datasetId> <input>

`mastra api experiment results`
「mastra-api-experiment-results」的直接連結

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

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

`mastra api learning entities`
「mastra-api-learning-entities」的直接連結

列出包含 Trace Intelligence 輸出的實體 (Agent)，包括每個實體可使用哪些 Trace signal。需要加入 Trace Intelligence 私人測試版。

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

`mastra api learning snapshots`
「mastra-api-learning-snapshots」的直接連結

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

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

`mastra api learning flow`
「mastra-api-learning-flow」的直接連結

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

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

`mastra api learning paths`
「mastra-api-learning-paths」的直接連結

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

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

`mastra api learning theme list`
「mastra-api-learning-theme-list」的直接連結

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

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

`mastra api learning theme get`
「mastra-api-learning-theme-get」的直接連結

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

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

`mastra api learning theme examples`
「mastra-api-learning-theme-examples」的直接連結

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

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

`mastra api learning theme history`
「mastra-api-learning-theme-history」的直接連結

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

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

`mastra api learning noise get`
「mastra-api-learning-noise-get」的直接連結

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

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

`mastra api learning noise examples`
「mastra-api-learning-noise-examples」的直接連結

列出一個快照中雜訊分組的 Trace 範例。使用 limit 與 offset 進行分頁。

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

通用旗標
「通用旗標」的直接連結

`--dir`
「--dir-5」的直接連結

適用於： dev、build、lint、migrate

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

`--debug`
「--debug-5」的直接連結

適用於： dev、build、migrate

啟用 Mastra 內部的詳細記錄。預設為 false。

`--env`
「--env-2」的直接連結

適用於： dev、start、studio、migrate

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

`--root`
「--root-2」的直接連結

適用於： dev、build、lint、migrate

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

`--tools`
「--tools-1」的直接連結

適用於： dev、build、lint

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

全域旗標
「全域旗標」的直接連結

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

`--version`
「--version」的直接連結

輸出 Mastra CLI 版本並結束。

`--help`
「--help」的直接連結

輸出說明訊息並結束。

遙測
「遙測」的直接連結

Mastra 預設會收集專案的匿名資訊，例如作業系統、Mastra 版本或 Node.js 版本。你可以閱讀原始碼，查看收集了哪些內容。

以 mastra dev 或 mastra start 啟動的伺服器若已啟用可觀測性指標，Mastra 還會在啟動時傳送匿名的彙總模型用量：依 Provider 和模型統計的輸入與輸出 token 數量，以及命令（dev 或 start）與 NODE_ENV。系統絕不會傳送提示詞、回應或其他訊息內容。你可以閱讀原始碼，查看收集了哪些內容。

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

你可以設定環境變數，選擇退出所有 CLI 與用量分析：

MASTRA_TELEMETRY_DISABLED=1

你也可以在使用其他 mastra 命令時設定此變數：

MASTRA_TELEMETRY_DISABLED=1 mastra dev

On this page

mastra dev
- 旗標
- 設定
mastra factory dev
mastra build
- 旗標
- 設定
mastra start
- 旗標
mastra worker build
- 旗標
mastra experiment build
- 產出物契約
- 通訊協定契約
- 封包欄位處理
- 旗標
mastra worker start
- 旗標
- 範例
mastra studio
- 旗標
mastra deploy
- 引數
- 旗標
- CI/CD 用法
mastra env
- mastra env list
- mastra env create
- mastra env delete
- mastra env restart
- mastra env vars pull
- mastra env db
- mastra env db list
- mastra env db create
- mastra env db show
- mastra env db delete
- mastra env deploys
mastra studio deploy
- 引數
- 旗標
- CI/CD 用法
- mastra studio deploy list
- mastra studio deploy status
- mastra studio deploy logs
- mastra studio deploy suggestions
- mastra studio projects
- mastra studio projects create
mastra server deploy
- mastra server deploy suggestions
mastra server pause
- 旗標
mastra server restart
- 旗標
mastra server env
- mastra server env list
- mastra server env set
- mastra server env unset
- mastra server env import
- mastra server env pull
mastra auth
- mastra auth login
- mastra auth logout
- mastra auth whoami
- mastra auth orgs
- mastra auth tokens
mastra lint
- 旗標
mastra scorers
- add
- list
mastra create
mastra init
- 旗標
mastra migrate
mastra api
- 輸出
- 目標解析
- 旗標
- 輸入模型
- 取得命令專用說明
- 命令
通用旗標
- --dir
- --debug
- --env
- --root
- --tools
全域旗標
- --version
- --help
遙測

mastra dev「mastra-dev」的直接連結

旗標「旗標」的直接連結

--https「--https」的直接連結

--inspect「--inspect」的直接連結

--inspect-brk「--inspect-brk」的直接連結

--custom-args「--custom-args」的直接連結

--request-context-presets「--request-context-presets」的直接連結

設定「設定」的直接連結

略過 peer 相依套件檢查「略過 peer 相依套件檢查」的直接連結

停用建置快取「停用建置快取」的直接連結

限制平行處理數量「限制平行處理數量」的直接連結

自訂 Provider 端點「自訂 Provider 端點」的直接連結

mastra factory dev「mastra-factory-dev」的直接連結

mastra build「mastra-build」的直接連結

旗標「旗標」的直接連結

--studio「--studio」的直接連結

設定「設定」的直接連結

略過 peer 相依套件檢查「略過 peer 相依套件檢查」的直接連結

限制平行處理數量「限制平行處理數量」的直接連結

mastra start「mastra-start」的直接連結

旗標「旗標」的直接連結

--dir「--dir」的直接連結

--custom-args「--custom-args-1」的直接連結

mastra worker build「mastra-worker-build」的直接連結

旗標「旗標」的直接連結

--dir「--dir-1」的直接連結

--root「--root」的直接連結

--tools「--tools」的直接連結

--output-dir「--output-dir」的直接連結

--debug「--debug」的直接連結

mastra experiment build「mastra-experiment-build」的直接連結

產出物契約「產出物契約」的直接連結

通訊協定契約「通訊協定契約」的直接連結

封包欄位處理「封包欄位處理」的直接連結

旗標「旗標」的直接連結

--dir「--dir-2」的直接連結

--root「--root-1」的直接連結

--output-dir「--output-dir-1」的直接連結

--debug「--debug-1」的直接連結

mastra worker start「mastra-worker-start」的直接連結

旗標「旗標」的直接連結

--dir「--dir-3」的直接連結

--env「--env」的直接連結

範例「範例」的直接連結

mastra studio「mastra-studio」的直接連結

旗標「旗標」的直接連結

--port「--port」的直接連結

--server-host「--server-host」的直接連結

--server-port「--server-port」的直接連結

--server-protocol「--server-protocol」的直接連結

--server-api-prefix「--server-api-prefix」的直接連結

--request-context-presets「--request-context-presets-1」的直接連結

mastra deploy「mastra-deploy」的直接連結

引數「引數」的直接連結

[dir]「dir」的直接連結

旗標「旗標」的直接連結

--env「--env-1」的直接連結

--org「--org」的直接連結

--project「--project」的直接連結

-y, --yes「-y---yes」的直接連結

-c, --config「-c---config」的直接連結

--env-file「--env-file」的直接連結

--region「--region」的直接連結

--skip-build「--skip-build」的直接連結

--skip-preflight「--skip-preflight」的直接連結

--debug「--debug-2」的直接連結

CI/CD 用法「CI/CD 用法」的直接連結

mastra env「mastra-env」的直接連結

mastra env list「mastra-env-list」的直接連結

--json「--json」的直接連結

mastra env create「mastra-env-create」的直接連結

-t, --type「-t---type」的直接連結

-r, --region「-r---region」的直接連結

--json「--json-1」的直接連結

mastra env delete「mastra-env-delete」的直接連結

-y, --yes「-y---yes-1」的直接連結

mastra env restart「mastra-env-restart」的直接連結

mastra env vars pull「mastra-env-vars-pull」的直接連結

-o, --output「-o---output」的直接連結

-f, --force「-f---force」的直接連結

`mastra dev`
「mastra-dev」的直接連結

旗標
「旗標」的直接連結

`--https`
「--https」的直接連結

`--inspect`
「--inspect」的直接連結

`--inspect-brk`
「--inspect-brk」的直接連結

`--custom-args`
「--custom-args」的直接連結

`--request-context-presets`
「--request-context-presets」的直接連結

設定
「設定」的直接連結

略過 peer 相依套件檢查
「略過 peer 相依套件檢查」的直接連結

停用建置快取
「停用建置快取」的直接連結

限制平行處理數量
「限制平行處理數量」的直接連結

自訂 Provider 端點
「自訂 Provider 端點」的直接連結

`mastra factory dev`
「mastra-factory-dev」的直接連結

`mastra build`
「mastra-build」的直接連結

旗標
「旗標」的直接連結

`--studio`
「--studio」的直接連結

設定
「設定」的直接連結

略過 peer 相依套件檢查
「略過 peer 相依套件檢查」的直接連結

限制平行處理數量
「限制平行處理數量」的直接連結

`mastra start`
「mastra-start」的直接連結

旗標
「旗標」的直接連結

`--dir`
「--dir」的直接連結

`--custom-args`
「--custom-args-1」的直接連結

`mastra worker build`
「mastra-worker-build」的直接連結

旗標
「旗標」的直接連結

`--dir`
「--dir-1」的直接連結

`--root`
「--root」的直接連結

`--tools`
「--tools」的直接連結

`--output-dir`
「--output-dir」的直接連結

`--debug`
「--debug」的直接連結

`mastra experiment build`
「mastra-experiment-build」的直接連結

產出物契約
「產出物契約」的直接連結

通訊協定契約
「通訊協定契約」的直接連結

封包欄位處理
「封包欄位處理」的直接連結

旗標
「旗標」的直接連結

`--dir`
「--dir-2」的直接連結

`--root`
「--root-1」的直接連結

`--output-dir`
「--output-dir-1」的直接連結

`--debug`
「--debug-1」的直接連結

`mastra worker start`
「mastra-worker-start」的直接連結

旗標
「旗標」的直接連結

`--dir`
「--dir-3」的直接連結

`--env`
「--env」的直接連結

範例
「範例」的直接連結

`mastra studio`
「mastra-studio」的直接連結

旗標
「旗標」的直接連結

`--port`
「--port」的直接連結

`--server-host`
「--server-host」的直接連結

`--server-port`
「--server-port」的直接連結

`--server-protocol`
「--server-protocol」的直接連結

`--server-api-prefix`
「--server-api-prefix」的直接連結

`--request-context-presets`
「--request-context-presets-1」的直接連結

`mastra deploy`
「mastra-deploy」的直接連結

引數
「引數」的直接連結

`[dir]`
「dir」的直接連結

旗標
「旗標」的直接連結

`--env`
「--env-1」的直接連結

`--org`
「--org」的直接連結

`--project`
「--project」的直接連結

`-y, --yes`
「-y---yes」的直接連結

`-c, --config`
「-c---config」的直接連結

`--env-file`
「--env-file」的直接連結

`--region`
「--region」的直接連結

`--skip-build`
「--skip-build」的直接連結

`--skip-preflight`
「--skip-preflight」的直接連結

`--debug`
「--debug-2」的直接連結

CI/CD 用法
「CI/CD 用法」的直接連結

`mastra env`
「mastra-env」的直接連結

`mastra env list`
「mastra-env-list」的直接連結

`--json`
「--json」的直接連結

`mastra env create`
「mastra-env-create」的直接連結

`-t, --type`
「-t---type」的直接連結

`-r, --region`
「-r---region」的直接連結

`--json`
「--json-1」的直接連結

`mastra env delete`
「mastra-env-delete」的直接連結

`-y, --yes`
「-y---yes-1」的直接連結

`mastra env restart`
「mastra-env-restart」的直接連結

`mastra env vars pull`
「mastra-env-vars-pull」的直接連結

`-o, --output`
「-o---output」的直接連結

`-f, --force`
「-f---force」的直接連結