CLI 指令

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

mastra dev

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

你亦可以設定伺服器。

旗標

此指令接受常用旗標及下列額外旗標：

--https

啟用本機 HTTPS 支援。了解更多。

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

包含請求內容預設設定的 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 依賴套件檢查

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

MASTRA_SKIP_PEERDEP_CHECK=1 mastra dev

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

停用建置快取

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

MASTRA_DEV_NO_CACHE=1 mastra dev

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

限制平行處理數量

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

MASTRA_CONCURRENCY=4 mastra dev

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

自訂 Provider 端點

使用 Vercel AI SDK 支援的 Provider 時，你可以設定基礎 URL，透過代理或內部閘道重新導向請求。以 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

啟動用於開發 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 項目封裝成可供生產環境使用的 Hono 伺服器。Hono 是輕量、型別安全的網頁框架，讓你能輕鬆將 Mastra Agent 部署為支援中介軟件的 HTTP 端點。

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

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

如果要部署至無伺服器平台，你需要安裝正確的 deployer，才能在 .mastra 中取得正確輸出。

此指令接受常用旗標。

旗標

--studio

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

設定

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

略過 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 build，然後才可使用 mastra start。

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

旗標

此指令接受常用旗標及下列額外旗標：

--dir

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

--custom-args

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

mastra worker build

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

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）協定訊息，再將協定事件寫入標準輸出。

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。

mastra worker start [name] [options]

旗標

--dir

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

--env

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

範例

# 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，了解部署拓撲及設定。

mastra studio

以靜態伺服器形式啟動 Studio。啟動後，你可以輸入 Mastra 實例 URL（例如 http://localhost:4111），將 Studio 連接至 Mastra 後端。此指令會在目前工作目錄中尋找 .env 及 .env.production 檔案作設定用途。

旗標

此指令接受常用旗標及下列額外旗標：

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

包含請求內容預設設定的 JSON 檔案路徑。其運作方式與 mastra dev 旗標相同。

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

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]

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

旗標

--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> 的功能。

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 使用，可自動接受建立環境。

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-project.json 檔案。只要從項目目錄執行指令，便毋須指定項目名稱。

mastra env list

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

mastra env list

--json

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

mastra env create

為項目建立新環境。

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

-t, --type

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

-r, --region

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

--json

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

mastra env delete

刪除環境。

mastra env delete <env>

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

-y, --yes

略過確認提示。

mastra env restart

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

mastra env restart <env>

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

mastra env vars pull

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

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、佈建狀態、範圍（每個資料庫向哪個環境提供資料），以及各資料庫注入的環境變數名稱。傳入環境後，只會顯示向該環境提供資料的資料庫（包括環境範圍及共享資料庫）。

mastra env db list
mastra env db list <env>

--json

輸出機器可讀的 JSON。

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

資料庫 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

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

mastra env db show <database>

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

--show-secrets

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

--json

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

mastra env db delete

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

mastra env db delete <database>

-y, --yes

略過確認提示。

mastra env deploys

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

mastra env deploys [environment]

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

--json

輸出機器可讀的 JSON。

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 並將輸出壓縮成 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 使用時，便可透過一條非互動式指令建立並部署新項目：

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），把同一個項目部署至多個環境。

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

顯示指定部署的狀態。

mastra studio deploy status <deploy-id>

--watch, -w

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

mastra studio deploy logs

顯示指定部署的日誌。

mastra studio deploy logs <deploy-id>

--follow, -f

即時串流日誌。

--tail

要顯示的最近日誌行數。

mastra studio deploy suggestions

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

mastra studio deploy suggestions [deploy-id]

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

mastra studio projects

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

mastra studio projects create

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

mastra server deploy

資訊

mastra server deploy 仍然可用，但已由 mastra deploy 取代。後者可把單一項目部署至多個環境，毋須分別使用 Studio 和 Server 指令。新設定應使用 mastra deploy。

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

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

mastra server deploy [dir]

mastra server deploy suggestions

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

mastra server deploy suggestions [deploy-id]

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

mastra server pause

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

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 pause 相同的旗標：--org、--project 和 -c / --config，其預設值和行為亦相同。

mastra server restart

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

mastra server env

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

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

mastra server env list

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

mastra server env set

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

mastra server env set <key> <value>

mastra server env unset

移除環境變數。

mastra server env unset <key>

mastra server env import

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

mastra server env import <file>

mastra server env pull

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

mastra server env pull [file]

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

--project

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

CI 用法

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

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。機密值只會顯示一次，之後無法再次擷取。

mastra auth tokens create <name>

mastra auth tokens revoke

撤銷 API token。

mastra auth tokens revoke <token-id>

mastra lint

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

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

mastra lint --preflight

此指令接受常用旗標。

旗標

--preflight

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

--skip-build

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

--env-file <file>

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

--strict

將警告視為錯誤。

--json

輸出機器可讀的 JSON。

--debug

啟用偵錯日誌。

mastra scorers

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

詳情請參閱 Scorer 概覽。

add

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

mastra scorers add

或直接提供 Scorer 名稱：

mastra scorers add answer-relevancy

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

list

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

mastra create

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

npm

npx mastra@latest create

pnpm

pnpm dlx mastra@latest create

Yarn

yarn dlx mastra@latest create

Bun

bun x mastra@latest create

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

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

有關模式行為、衝突、驗證和完整旗標說明，請參閱 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 儲存參考資料。

mastra migrate

有關何時需要遷移的詳情，請參閱儲存遷移指南。

此指令接受常用旗標。

mastra api

以 JSON 輸入及輸出呼叫 Mastra runtime 伺服器。可用於本機開發伺服器、已部署的 Mastra 平台項目、自行託管的 Mastra 伺服器，或託管的 Mastra Platform Observability 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": {}
  }
}

目標解析

對於 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。

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 環境變數，而不傳入此旗標。

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

--header <"Key: Value">

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

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 旗標使用。

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

輸入模型

接受輸入的指令會接收一個 inline 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

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

指令

mastra api agent list

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

mastra api agent list [input]

mastra api agent get

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

mastra api agent get <agentId>

mastra api agent run

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

mastra api agent run <agentId> <input>

mastra api workflow list

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

mastra api workflow list [input]

mastra api workflow get

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

mastra api workflow get <workflowId>

mastra api workflow run start

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

mastra api workflow run start <workflowId> <input>

mastra api workflow run list

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

mastra api workflow run list <workflowId> [input]

mastra api workflow run get

按 ID 取得一個 workflow run。

mastra api workflow run get <workflowId> <runId>

mastra api workflow run resume

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

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

mastra api workflow run cancel

取消 workflow run。

mastra api workflow run cancel <workflowId> <runId>

mastra api tool list

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

mastra api tool list [input]

mastra api tool get

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

mastra api tool get <toolId>

mastra api tool execute

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

mastra api tool execute <toolId> <input>

mastra api mcp list

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

mastra api mcp list [input]

mastra api mcp get

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

mastra api mcp get <id>

mastra api mcp tool list

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

mastra api mcp tool list <serverId> [input]

mastra api mcp tool get

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

mastra api mcp tool get <serverId> <toolId>

mastra api mcp tool execute

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

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

mastra api thread list

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

mastra api thread list [input]

mastra api thread get

按 ID 取得一個 memory thread。

mastra api thread get <threadId>

mastra api thread create

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

mastra api thread create <input>

mastra api thread update

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

mastra api thread update <threadId> <input>

mastra api thread delete

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

mastra api thread delete <threadId> <input>

mastra api thread messages

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

mastra api thread messages <threadId> [input]

mastra api memory search

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

mastra api memory search <input>

mastra api memory current get

讀取 thread 目前的 working memory。

mastra api memory current get <input>

mastra api memory current update

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

mastra api memory current update <input>

mastra api memory status

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

mastra api memory status <input>

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 記錄，讓你無需擷取大型輸入、輸出、屬性或中繼資料 payload，即可逐頁瀏覽 trace。傳入 --verbose 以擷取完整的 root span 記錄。

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

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

mastra api trace span <traceId> <spanId>

mastra api log list

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

mastra api log list [input]

mastra api metric aggregate

取得單一彙總 metric 值。

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

mastra api metric breakdown

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

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

mastra api metric timeseries

取得一段時間內的 metric 值。

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

mastra api metric percentiles

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

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

mastra api metric names

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

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

mastra api metric label-keys

列出 metric 的標籤 key。

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

mastra api metric label-values

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

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

使用 curl 存取可觀測性功能

你可以使用平台 access 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

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

mastra api score create <input>

mastra api score list

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

mastra api score list [input]

mastra api score get

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

mastra api score get <scoreId>

mastra api dataset list

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

mastra api dataset list [input]

mastra api dataset get

按 ID 取得一個 dataset。

mastra api dataset get <datasetId>

mastra api dataset create

使用 JSON 輸入建立 dataset。

mastra api dataset create <input>

mastra api dataset items

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

mastra api dataset items <datasetId> [input]

mastra api experiment list

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

mastra api experiment list <datasetId> [input]

mastra api experiment get

按 ID 取得一個實驗。

mastra api experiment get <datasetId> <experimentId>

mastra api experiment run

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

mastra api experiment run <datasetId> <input>

mastra api experiment results

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

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

mastra api learning entities

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

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

mastra api learning snapshots

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

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

mastra api learning flow

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

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

mastra api learning paths

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

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

mastra api learning theme list

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

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

mastra api learning theme get

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

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

mastra api learning theme examples

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

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

mastra api learning theme history

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

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

mastra api learning noise get

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

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

mastra api learning noise examples

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

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 版本。你可以閱讀原始碼，查看所收集的資訊。

如果透過 mastra dev 或 mastra start 啟動的伺服器已啟用可觀測性指標，Mastra 亦會在啟動時傳送匿名的彙總模型用量：各個 Provider 和模型的輸入與輸出 token 數量，以及所用指令（dev 或 start）和 NODE_ENV。系統絕不會傳送 prompt、回應或任何其他訊息內容。你可以閱讀原始碼，查看所收集的資訊。

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

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

MASTRA_TELEMETRY_DISABLED=1

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

MASTRA_TELEMETRY_DISABLED=1 mastra dev