CLI 명령
Mastra에서 제공하는 명령줄 인터페이스(CLI)를 사용하여 Mastra 프로젝트를 개발, 빌드 및 시작할 수 있습니다.
mastra devmastra-dev에 대한 직접 링크
Agent, Tool, Workflow를 위한 Studio 및 REST 엔드포인트를 노출하는 서버를 시작합니다. mastra dev가 실행 중일 때 http://localhost:4111/swagger-ui에서 사용 가능한 모든 엔드포인트의 개요를 확인할 수 있습니다.
서버를 구성할 수도 있습니다.
플래그플래그에 대한 직접 링크
이 명령은 공통 플래그와 다음 추가 플래그를 받습니다.
--https--https에 대한 직접 링크
로컬 HTTPS 지원을 활성화합니다.Learn more.
--inspect--inspect에 대한 직접 링크
디버깅에 도움이 되는 검사 모드로 개발 서버를 시작합니다. 선택적으로 사용자 정의 호스트와 포트를 지정합니다(예: Docker의 경우 --inspect=0.0.0.0:9229). --inspect-brk와 함께 사용할 수 없습니다.
--inspect-brk--inspect-brk에 대한 직접 링크
검사 모드로 개발 서버를 시작하고 스크립트 시작 부분에서 중단합니다. 선택적으로 사용자 정의 호스트와 포트를 지정합니다(예: --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.
피어 종속성 검사 건너뛰기피어 종속성 검사 건너뛰기에 대한 직접 링크
시작 시 피어 종속성 버전 불일치 검사를 건너뛰려면 MASTRA_SKIP_PEERDEP_CHECK=1을 설정하세요.
MASTRA_SKIP_PEERDEP_CHECK=1 mastra dev
이는 피어 종속성이 충돌할 수 있지만 패키지가 아직 게시되지 않은 단일 저장소 개발 중에 유용합니다.
빌드 캐싱 비활성화빌드 캐싱 비활성화에 대한 직접 링크
.mastra/ 아래에 캐시된 자산을 사용하지 않고 전체 빌드를 강제하려면 MASTRA_DEV_NO_CACHE=1을 설정하세요.
MASTRA_DEV_NO_CACHE=1 mastra dev
이는 번들러 플러그인을 디버깅하거나 오래된 출력이 의심되는 경우에 도움이 됩니다.
병렬성 제한병렬성 제한에 대한 직접 링크
MASTRA_CONCURRENCY병렬로 실행되는 비용이 많이 드는 작업 수를 제한합니다(주로 빌드 및 평가 단계). 예를 들어:
MASTRA_CONCURRENCY=4 mastra dev
CLI가 시스템에 적합한 기본값을 선택하도록 하려면 설정하지 않은 채로 두십시오.
맞춤형 제공자 엔드포인트맞춤형 제공자 엔드포인트에 대한 직접 링크
Vercel AI SDK에서 지원하는 공급자를 사용하는 경우 기본 URL을 설정하여 프록시 또는 내부 게이트웨이를 통해 요청을 리디렉션할 수 있습니다. OpenAI의 경우:
OPENAI_API_KEY=<your-api-key> \
OPENAI_BASE_URL=https://openrouter.example/v1 \
mastra dev
인류를 위한:
ANTHROPIC_API_KEY=<your-api-key> \
ANTHROPIC_BASE_URL=https://anthropic.internal \
mastra dev
이 값은 Mastra Model 라우터에 전달되며 모든 "openai/..."
또는 "anthropic/..." Model 선택에서 작동합니다.
mastra factory devmastra-factory-dev에 대한 직접 링크
Agent Builder 개발을 위한 개발 서버를 시작합니다. mastra dev와 동일한 개발 런타임 및 플래그를 사용하며 같은 .mastra/output 디렉터리에 기록합니다.
npx mastra factory dev
두 명령은 동일한 개발 잠금을 공유하므로 같은 프로젝트에서 mastra dev와 mastra factory dev를 동시에 실행할 수 없습니다. 하나가 이미 실행 중이면 다른 하나는 중복 개발 서버 오류와 함께 종료됩니다.
Agent Builder 기능을 개발할 때 mastra factory dev를 사용하세요. --https, --inspect, --inspect-brk, --custom-args, --request-context-presets를 비롯해 mastra dev와 동일한 플래그를 받습니다.
mastra buildmastra-build에 대한 직접 링크
mastra build 명령은 Mastra 프로젝트를 프로덕션용 Hono 서버로 번들링합니다. Hono는 미들웨어를 지원하는 HTTP 엔드포인트로 Mastra Agent를 간편하게 배포할 수 있게 해주는 경량 타입 안전 웹 프레임워크입니다.
내부적으로 Mastra의 롤업 서버는 Mastra 항목 파일을 찾아 이를 프로덕션용 Hono 서버에 번들로 묶습니다. 번들링하는 동안 코드를 트리 셰이크하고 디버깅을 위한 소스 맵을 생성합니다.
.mastra의 출력은 mastra start를 사용하여 모든 클라우드 서버에 배포할 수 있습니다.
서버리스 플랫폼에 배포하는 경우 .mastra에 올바른 출력을 생성하려면 적절한 배포 도구를 설치해야 합니다.
그것은 받아들인다common flags.
플래그플래그에 대한 직접 링크
--studio--studio에 대한 직접 링크
Studio UI를 빌드와 함께 번들로 묶습니다.
구성구성에 대한 직접 링크
환경 변수를 설정하여 동작을 수정할 수 있습니다.mastra build.
피어 종속성 검사 건너뛰기피어 종속성 검사 건너뛰기에 대한 직접 링크
피어 종속성 버전 불일치 검사를 건너뛰려면 MASTRA_SKIP_PEERDEP_CHECK=1을 설정하세요.
MASTRA_SKIP_PEERDEP_CHECK=1 mastra build
병렬성 제한병렬성 제한에 대한 직접 링크
CI의 경우 또는 리소스가 제한된 환경에서 실행할 때 설정을 통해 한 번에 실행되는 비용이 많이 드는 작업 수를 제한할 수 있습니다.MASTRA_CONCURRENCY.
MASTRA_CONCURRENCY=2 mastra build
mastra startmastra-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 buildmastra-worker-build에 대한 직접 링크
작업자 배포를 위해 Mastra 애플리케이션을 번들링합니다. mastra build와 동일하게 자체 완결형 .mastra/output/ 디렉터리를 생성합니다.
mastra worker build [options]
플래그플래그에 대한 직접 링크
--dir--dir-1에 대한 직접 링크
Mastra 소스 디렉터리의 경로입니다. 기본값은src/mastra.
--root--root에 대한 직접 링크
프로젝트 루트 디렉터리. 기본값은 현재 디렉터리입니다.
--tools--tools에 대한 직접 링크
번들에 포함할 쉼표로 구분된 Tool 경로입니다.
--output-dir--output-dir에 대한 직접 링크
사용자 정의 출력 디렉터리. 기본값은.mastra/output.
--debug--debug에 대한 직접 링크
빌드 중에 디버그 로깅을 활성화합니다.
mastra experiment buildmastra-experiment-build에 대한 직접 링크
HTTP 서버를 노출하지 않고 실험을 실행하는 독립 실행형 보조 작업자를 빌드합니다. 작업자는 내보낸 Mastra 인스턴스를 로드하고 표준 입력에서 버전이 지정된 줄바꿈 구분 JSON(NDJSON) 프로토콜 메시지를 받습니다. 프로토콜 이벤트는 표준 출력에 기록합니다.
mastra experiment build [options]
이 명령은 기본적으로 작업자를 .mastra/experiment-worker에 기록합니다. 디렉터리에는 실행 가능한 진입점, 프로덕션 종속성, experiment-worker-manifest.json이 포함됩니다. 표준 출력은 프로토콜 전용 출력으로 취급하세요. 작업자 진단 정보는 표준 오류에 기록됩니다.
유물계약유물계약에 대한 직접 링크
experiment-worker-manifest.json은 아티팩트를 버전 1의 mastra-experiment-worker로 식별하고 다음을 제공합니다.
- 실행 파일에 포함된 CLI 버전, 생성 시간 및 고유 빌드 ID입니다.
- 지원되는 프로토콜 및 데이터 세트 정규화 버전.
- 작업자를 시작하는 데 필요한 실행 파일, 인수 및 작업 디렉터리입니다.
- 종속성 매니페스트 및 생성된 잠금 파일 경로.
- 각 아티팩트 파일에 대한 정렬된 SHA-256 다이제스트입니다.
- 해당 파일 경로 및 다이제스트에서 파생된 SHA-256 콘텐츠 다이제스트입니다.
자기 참조 다이제스트를 방지하기 위해 콘텐츠 다이제스트에서 experiment-worker-manifest.json은 제외됩니다. 매니페스트를 나머지 디렉터리와 함께 패키징하세요. 매니페스트 자체를 증명해야 한다면 외부 패키지 다이제스트를 사용하세요.
프로토콜 계약프로토콜 계약에 대한 직접 링크
작업자는 고정된 실험 동료 작업자 프로토콜 버전 1을 구현합니다. 표준 입력에서 엄격한 UTF-8 NDJSON 프레임을 읽으며 마지막 프레임을 포함한 모든 프레임이 줄바꿈으로 끝나야 합니다. 1 MiB보다 큰 프레임, 잘못되거나 잘린 프레임, 지원되지 않는 프로토콜 또는 정규화 버전, 활성 실험 상관관계와 일치하지 않는 메시지는 프로토콜 실패로 거부됩니다.
실행 요청은 아티팩트에 포함된 빌드 ID와 일치해야 하며, 정렬된 데이터 세트 항목 수와 SHA-256 증명을 포함해야 합니다. 작업자는 0부터 시작하는 연속 시퀀스 번호, 타이머 기반 하트비트, 완료를 기다린 실험 수명 주기 이벤트, 정확히 하나의 종료 이벤트를 내보냅니다. 취소 요청은 활성 프로토콜 버전, 실험 ID, 작업 ID, 시도 횟수, 멱등성 키와 일치해야 합니다.
프로토콜 종료 코드는 다음과 같습니다.
| 코드 | 의미 |
|---|---|
0 | 완료 |
10 | 항목 오류와 함께 완료 |
20 | 치명적 실패 |
21 | 재시도 가능한 실패 |
30 | 취소됨 |
31 | 시간 초과 |
70 | 프로토콜 실패 |
패킷 필드 처리패킷 필드 처리에 대한 직접 링크
작업자는 대상 ID, 정렬된 인라인 데이터 세트 항목, 채점자 ID, 동시성, 제한 시간, 실험 메타데이터, 요청 컨텍스트, Tool 모의 객체, 취소를 runExperiment에 전달합니다. 채점자 버전과 아티팩트 출처는 실험 메타데이터로 유지됩니다. 채점자 코드 출처는 런타임 채점자 조회가 아니라 아티팩트 승인 과정에서 적용됩니다.
버전 1은 결정론적인 미선언 Tool 거부를 사용합니다. 네트워크 적용과 비밀 정보 구체화는 프로세스 Sandbox에서 담당하므로 비어 있지 않은 네트워크 허용 목록과 비밀 참조는 정책 실패로 거부됩니다. 데이터 세트 항목의 소스 및 예상 궤적 필드는 runExperiment에 전달될 때 항목 메타데이터로 보존됩니다.
플래그플래그에 대한 직접 링크
--dir--dir-2에 대한 직접 링크
Mastra 소스 디렉터리의 경로입니다. 기본값은src/mastra.
--root--root-1에 대한 직접 링크
프로젝트 루트 디렉터리. 기본값은 현재 디렉터리입니다.
--output-dir--output-dir-1에 대한 직접 링크
사용자 정의 아티팩트 디렉터리. 상대 경로는 프로젝트 루트에서 확인됩니다. 기본값은.mastra/experiment-worker.
--debug--debug-1에 대한 직접 링크
빌드 중에 디버그 로깅을 활성화합니다.
mastra worker startmastra-worker-start에 대한 직접 링크
mastra worker start를 사용하기 전에 mastra worker build 또는 mastra build를 실행해야 합니다.
이전에 빌드한 번들에서 워커 프로세스를 시작합니다. 선택적 name 인수는 생성된 프로세스에서 MASTRA_WORKERS를 설정하여 시작할 워커를 제어합니다.
mastra worker start [name] [options]
플래그플래그에 대한 직접 링크
--dir--dir-3에 대한 직접 링크
빌드 출력 디렉터리의 경로입니다. 기본값은.mastra/output.
--env--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
배포 토폴로지와 구성에 관한 내용은 Workers를 참조하세요.
mastra studiomastra-studio에 대한 직접 링크
Studio를 정적 서버로 시작합니다. 시작한 후 Mastra 인스턴스 URL(예: http://localhost:4111)을 입력하여 Studio를 Mastra 백엔드에 연결할 수 있습니다. 구성에 사용할 .env 및 .env.production 파일을 현재 작업 디렉터리에서 찾습니다.
플래그플래그에 대한 직접 링크
이 명령은 공통 플래그와 다음 추가 플래그를 지원합니다.
--port--port에 대한 직접 링크
Studio를 실행할 포트입니다. 기본값은3000.
--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 deploymastra-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 구성 파일, 자격 증명의 현재 조직, 마지막으로 대화형 Prompt 순서로 결정됩니다. 최초 배포 시 CLI는 결정된 조직 및 프로젝트 ID를 .mastra-project.json에 저장하므로 이후 배포에서는 Prompt를 건너뜁니다.
프로젝트가 아직 없으면 CLI는 확인 후 package.json의 name 필드를 사용하여 프로젝트를 생성합니다. 대상 환경이 없으면 CLI는 확인 후 해당 환경을 생성합니다(production 이외의 환경은 기본적으로 type: staging). --yes와 함께 사용하면 다음과 같이 하나의 비대화형 명령으로 모든 항목을 생성하고 배포합니다.
mastra deploy --env staging --yes
--env <name>이 설정되고 --env-file이 설정되지 않은 경우, 프로젝트 디렉터리에 .env.<name>이 있으면 CLI가 이를 자동으로 선택합니다(예: .env.staging). <name> 값은 파일 경로에 삽입되기 전에 엄격한 허용 목록을 기준으로 검증됩니다.
인수인수에 대한 직접 링크
[dir]dir에 대한 직접 링크
프로젝트 디렉토리. 기본값은 현재 디렉터리입니다.
플래그플래그에 대한 직접 링크
--env--env-1에 대한 직접 링크
대상 환경 이름입니다. 기본값은 production입니다. --env-file이 설정되지 않은 경우 프로젝트 디렉터리에서 .env.<name>을 자동으로 선택합니다. 환경이 없으면 CLI가 확인 후 생성합니다.
--org--org에 대한 직접 링크
조직 ID. 다음을 통해서도 설정할 수 있습니다.MASTRA_ORG_ID environment variable.
--project--project에 대한 직접 링크
프로젝트 ID, 슬러그 또는 이름입니다. MASTRA_PROJECT_ID 환경 변수로도 설정할 수 있습니다. 일치하는 프로젝트가 없으면 이 값이 배포 시 생성할 새 프로젝트의 이름으로 사용됩니다.
-y, --yes-y---yes에 대한 직접 링크
프로젝트 및 환경 생성을 포함하여 확인 메시지 없이 기본값을 자동으로 수락합니다.
-c, --config-c---config에 대한 직접 링크
프로젝트 구성 파일의 경로입니다. 기본값은.mastra-project.json.
--env-file--env-file에 대한 직접 링크
배포에 함께 번들링할 env 파일의 경로입니다(프로젝트 디렉터리 기준). 설정하면 --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이 설정되면 대화형 Prompt를 자동으로 건너뜁니다. 환경 생성을 자동 승인하려면 --yes와 함께 사용하세요.
export MASTRA_API_TOKEN="..."
export MASTRA_ORG_ID="..."
export MASTRA_PROJECT_ID="..."
mastra deploy --env staging --yes
mastra envmastra-env에 대한 직접 링크
Mastra 플랫폼에서 환경을 관리합니다. 환경은 프로젝트에 속하는 배포 대상입니다(예: production, staging, preview-42). 현재 조직은 저장된 자격 증명에서 결정됩니다.
모든 하위 명령은 고정된 순서로 프로젝트를 결정합니다. 먼저 MASTRA_PROJECT_ID 환경 변수와 --project <name|slug|id> 플래그를 확인합니다. 그런 다음 현재 디렉터리에서 mastra deploy가 작성한 .mastra-project.json 파일을 읽습니다. 프로젝트 디렉터리에서 실행하면 프로젝트를 지정할 필요가 없습니다.
mastra env listmastra-env-list에 대한 직접 링크
프로젝트의 환경을 나열합니다. 각 환경에는 최신 배포(트래픽을 처리 중이면 (active) 표시)와 연결된 데이터베이스 같은 관리형 리소스가 주입한 env 변수 이름이 표시됩니다.
mastra env list
--json--json에 대한 직접 링크
기계가 읽을 수 있는 JSON을 내보냅니다. 중요하지 않은 메타데이터(id, 이름, 슬러그, 유형, 지역, 분기, URL, 관리 환경 변수 이름 및 최신 배포 상태)만 포함되므로 출력은 CI에 안전하게 로그인할 수 있습니다.
mastra env createmastra-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 deletemastra-env-delete에 대한 직접 링크
환경을 삭제합니다.
mastra env delete <env>
<env>는 환경 이름, 슬러그 또는 ID일 수 있습니다. --yes를 전달하지 않으면 CLI에 확인 Prompt가 표시됩니다.
-y, --yes-y---yes-1에 대한 직접 링크
확인 메시지를 건너뜁니다.
mastra env restartmastra-env-restart에 대한 직접 링크
환경의 실행 중인 서비스를 다시 시작하여 저장된 환경 변수(연결된 데이터베이스의 관리 변수 포함)가 새 배포 없이 즉시 적용됩니다.
mastra env restart <env>
<env>환경 이름, 슬러그 또는 ID일 수 있습니다. 환경이 배포된 적이 없는 경우 충돌 오류로 인해 실패합니다.
mastra env vars pullmastra-env-vars-pull에 대한 직접 링크
환경의 env 변수를 로컬 env 파일(기본값: .env)로 가져옵니다. 이 파일에는 배포에서 사용되는 병합된 변수 집합이 포함됩니다. 환경에 저장된 변수(예: 대시보드의 환경 편집기에서 추가한 변수)와 프로젝트 수준 변수가 결합되며, 충돌하면 프로젝트 값이 우선합니다. 연결된 데이터베이스가 주입하는 관리형 변수는 플랫폼이 관리하는 비밀 값이므로 이름만 주석으로 나열됩니다.
mastra env vars pull
mastra env vars pull <env> --output .env.staging
<env>는 환경 이름, 슬러그 또는 ID일 수 있으며, 프로젝트에 환경이 정확히 하나만 있으면 생략할 수 있습니다. 파일은 0600 권한으로 작성됩니다. 출력 파일이 이미 있으면 명령이 중지됩니다. 교체하려면 --force를 전달하세요.
-o, --output-o---output에 대한 직접 링크
쓸 파일입니다. 기본값은.env.
-f, --force-f---force에 대한 직접 링크
기존 출력 파일을 바꿉니다.
mastra env dbmastra-env-db에 대한 직접 링크
Mastra 플랫폼의 프로젝트에 연결된 데이터베이스를 관리합니다. 데이터베이스는 관리형 공급자(예: Turso 또는 Neon)에서 프로비저닝되고 해당 연결 환경 변수를 배포에 자동으로 삽입합니다.
데이터베이스는 환경 범위(env 변수가 한 환경에만 적용됨) 또는 공유(프로젝트 범위: env 변수가 모든 환경에 적용됨) 중 하나입니다. mastra env db create의 기본값은 환경 범위입니다. 환경 인수를 전달하거나 CLI가 환경을 선택하거나 묻도록 두세요. 대신 공유 데이터베이스를 연결하려면 생성 시 --shared를 전달하세요. 다른 하위 명령(list, delete, keys)에서는 환경 범위 데이터베이스를 다룰 때 환경 인수를 전달하고, 공유 데이터베이스를 다룰 때는 생략하세요.
데이터베이스를 생성하고 삭제하려면 조직에서 admin 역할이 필요합니다.
mastra env db listmastra-env-db-list에 대한 직접 링크
공급자, 프로비저닝 상태, 범위(각 데이터베이스가 제공하는 환경) 및 각 데이터베이스가 삽입하는 환경 변수 이름을 포함하여 프로젝트에 연결된 데이터베이스를 나열합니다. 해당 환경(환경 범위 및 공유)을 제공하는 데이터베이스만 표시하려면 환경을 전달합니다.
mastra env db list
mastra env db list <env>
--json--json-2에 대한 직접 링크
기계가 읽을 수 있는 JSON을 내보냅니다.
mastra env db createmastra-env-db-create에 대한 직접 링크
관리형 데이터베이스를 프로비저닝하고 연결한 다음 준비될 때까지 폴링합니다. 프로비저닝 오류는 공급자의 오류 세부정보와 함께 인쇄됩니다.
기본적으로 데이터베이스의 범위는 단일 환경으로 지정됩니다. 환경을 선택하려면 환경 인수를 전달하고, CLI가 자동으로 선택하도록 하려면 인수를 생략하세요. 프로젝트에 환경이 하나뿐이면 해당 환경을 사용합니다. 환경이 여러 개면 CLI가 대화형으로 선택하라는 Prompt를 표시합니다. 비대화형 컨텍스트(CI, --json)에서는 환경 인수가 필요합니다. 대신 모든 환경이 공유하는 프로젝트 범위 데이터베이스를 연결하려면 --shared를 전달하세요.
환경 범위 데이터베이스는 환경에서 공급자 지역을 상속합니다. 공유 데이터베이스 허용--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에 대한 직접 링크
데이터베이스 이름. 기본값은 프로젝트 슬러그에서 파생된 이름입니다(예:my-app-db).
--region--region-1에 대한 직접 링크
공유 데이터베이스의 공급자 지역 ID입니다. 환경 범위 데이터베이스의 경우 무시됩니다.
--shared--shared에 대한 직접 링크
모든 환경에서 공유되는 프로젝트 범위 데이터베이스로 연결합니다. 환경 인수와 결합할 수 없습니다.
--no-wait--no-wait에 대한 직접 링크
데이터베이스가 준비될 때까지 폴링하는 대신 연결이 대기열에 추가된 후 즉시 반환합니다. 나중에 진행 상황을 확인하세요.mastra env db show.
--json--json-3에 대한 직접 링크
기계 판독 가능한 JSON을 출력합니다. 이 모드에서 프로젝트에 환경이 두 개 이상이면 환경 인수 또는 --shared가 필요합니다(대화형 Prompt 없음).
mastra env db showmastra-env-db-show에 대한 직접 링크
데이터베이스 세부 정보를 표시하고, 데이터베이스가 준비되면 해당 연결 환경 변수를 표시합니다. 비밀 값은 기본적으로 마스크되어 있습니다.
mastra env db show <database>
<database>데이터베이스 ID 또는 이름일 수 있습니다.
--show-secrets--show-secrets에 대한 직접 링크
비밀 연결 값을 마스킹하는 대신 인쇄하세요.
--json--json-4에 대한 직접 링크
기계 판독 가능한 JSON을 출력합니다. --show-secrets를 전달하지 않으면 비밀 값이 마스킹됩니다.
mastra env db deletemastra-env-db-delete에 대한 직접 링크
모든 데이터를 포함하여 Provider에서 데이터베이스를 영구적으로 삭제합니다. 이 작업은 되돌릴 수 없습니다. --yes를 전달하지 않으면 CLI에 확인 Prompt가 표시됩니다. 삭제 후 배포에는 더 이상 데이터베이스의 env 변수가 제공되지 않습니다.
mastra env db delete <database>
-y, --yes-y---yes-2에 대한 직접 링크
확인 메시지를 건너뜁니다.
mastra env deploysmastra-env-deploys에 대한 직접 링크
프로젝트에 대한 배포를 최신 항목부터 나열합니다. 트래픽을 제공하는 배포가 표시됩니다.(active).
mastra env deploys [environment]
모든 환경의 배포를 표시하려면 [environment]를 생략하고, 하나의 환경으로 필터링하려면 환경 이름, 슬러그 또는 ID를 전달하세요.
--json--json-5에 대한 직접 링크
기계가 읽을 수 있는 JSON을 내보냅니다.
mastra studio deploymastra-studio-deploy에 대한 직접 링크
mastra studio deploy는 계속 작동하지만, 단일 프로젝트에서 환경(--env staging, --env production)을 지원하는 mastra deploy로 대체되었습니다. 새로운 설정에서는 mastra deploy를 사용해야 합니다.
프로젝트를 빌드하여 Mastra 플랫폼에 배포합니다. mastra auth login 또는 MASTRA_API_TOKEN 환경 변수를 통한 인증이 필요합니다.
mastra studio deploy
이 명령은 mastra build를 실행하고 결과물을 압축합니다. 모든 항목을 플랫폼에 업로드하기 전에 프로젝트 디렉터리에서 env 파일을 읽습니다. 업로드 후에는 배포가 최종 상태에 도달할 때까지 배포 상태를 폴링하고 빌드 로그를 스트리밍합니다.
배포 명령은 프로젝트의 .env 파일을 사용합니다. MASTRA_PROJECT_ID가 Observability용으로 프로비저닝된 프로젝트를 가리키면 새 프로젝트를 생성하는 대신 해당 프로젝트에 배포를 연결합니다. Observability 전용 프로젝트에 Studio를 배포하면 플랫폼에서 해당 프로젝트가 Studio 프로젝트로 변환됩니다.
CLI를 사용하려면 프로젝트 디렉터리에 .env 또는 .env.* 파일(.env.example 제외)이 하나 이상 있어야 하며, 없으면 Error: No env file found for deploy. 오류가 발생합니다. env 파일이 여러 개면 CLI가 하나를 선택하라는 Prompt를 표시합니다(기본값: .env.production). 명시적으로 선택하려면 --env-file을 전달하세요. env 파일이 여러 개인 상태에서 --yes를 사용하려면 --env-file을 전달해야 하며, 그렇지 않으면 배포 오류가 발생합니다.
조직과 프로젝트는 환경 변수, 플래그, .mastra-project.json 구성 파일, 자격 증명의 현재 조직, 마지막으로 대화형 Prompt 순서로 결정됩니다. 최초 배포 시 CLI는 결정된 ID를 .mastra-project.json에 저장하므로 이후 배포에서는 Prompt를 건너뜁니다.
--project <value>가 기존 프로젝트와 ID 또는 슬러그로 일치하지 않으면 CLI는 <value>를 새 프로젝트 이름으로 간주하고 확인 후 프로젝트를 생성합니다. --yes와 함께 사용하면 다음과 같이 하나의 비대화형 명령으로 새 프로젝트를 생성하고 배포합니다.
mastra studio deploy --project "my-new-project" --yes
인수인수에 대한 직접 링크
[dir]dir-1에 대한 직접 링크
프로젝트 디렉토리. 기본값은 현재 디렉터리입니다.
플래그플래그에 대한 직접 링크
--org--org-1에 대한 직접 링크
조직 ID. 다음을 통해서도 설정할 수 있습니다.MASTRA_ORG_ID environment variable.
--project--project-1에 대한 직접 링크
프로젝트 ID 또는 슬러그입니다. MASTRA_PROJECT_ID 환경 변수로도 설정할 수 있습니다. 일치하는 프로젝트가 없으면 이 값이 배포 시 생성할 새 프로젝트의 이름으로 사용됩니다.
-y, --yes-y---yes-3에 대한 직접 링크
확인 메시지 없이 기본값을 자동으로 수락합니다.
-c, --config-c---config-1에 대한 직접 링크
프로젝트 구성 파일의 경로입니다. 기본값은.mastra-project.json.
--env-file--env-file-1에 대한 직접 링크
배포와 함께 번들링할 env 파일의 경로입니다(프로젝트 디렉터리 기준). 이를 사용하여 서로 다른 환경 파일을 가리켜 동일한 프로젝트를 여러 환경에 배포합니다(예:.env.staging, .env.production).
mastra studio deploy --env-file .env.staging --yes
--skip-build--skip-build-1에 대한 직접 링크
빌드 단계를 건너뛰고 기존 배포.mastra/output directory.
--debug--debug-3에 대한 직접 링크
빌드 단계 중에 디버그 로그를 활성화합니다.
CI/CD 사용CI/CD 사용에 대한 직접 링크
헤드리스 배포에서는 MASTRA_API_TOKEN, MASTRA_ORG_ID, MASTRA_PROJECT_ID를 환경 변수로 설정하세요. MASTRA_API_TOKEN이 설정되면 대화형 Prompt를 자동으로 건너뜁니다.
mastra studio deploy listmastra-studio-deploy-list에 대한 직접 링크
최신 배포 상태 및 URL과 함께 모든 프로젝트를 나열합니다.
mastra studio deploy statusmastra-studio-deploy-status에 대한 직접 링크
특정 배포 상태를 표시합니다.
mastra studio deploy status <deploy-id>
--watch, -w--watch--w에 대한 직접 링크
배포가 최종 상태에 도달할 때까지 상태 변경 사항을 폴링합니다.
mastra studio deploy logsmastra-studio-deploy-logs에 대한 직접 링크
특정 배포에 대한 로그를 표시합니다.
mastra studio deploy logs <deploy-id>
--follow, -f--follow--f에 대한 직접 링크
실시간으로 로그를 스트리밍합니다.
--tail--tail에 대한 직접 링크
표시할 최근 로그 줄 수입니다.
mastra studio deploy suggestionsmastra-studio-deploy-suggestions에 대한 직접 링크
실패한 Studio 배포에 대한 진단 결과 및 제안된 수정 사항을 표시합니다.
mastra studio deploy suggestions [deploy-id]
deploy-id를 생략하면 이 명령은 연결된 프로젝트의 최신 배포를 사용합니다. 아직 진단이 없으면 명령이 진단을 시작하고 결과가 준비될 때까지 폴링합니다. 진단에서 문제가 발견된 경우에만 제안이 표시됩니다.
mastra studio projectsmastra-studio-projects에 대한 직접 링크
현재 조직의 모든 프로젝트를 나열합니다.
mastra studio projects createmastra-studio-projects-create에 대한 직접 링크
대화형 Prompt를 통해 새 프로젝트를 생성합니다. 이 명령은 --name 플래그를 지원하지 않습니다. 비대화형으로 프로젝트를 생성하려면 대신 mastra studio deploy --project <name> --yes를 사용하세요. 이 명령은 프로젝트를 생성하고 한 단계로 배포합니다.
mastra server deploymastra-server-deploy에 대한 직접 링크
mastra server deploy는 계속 작동하지만, Studio와 Server 명령을 분리하지 않고 단일 프로젝트를 여러 환경에 배포하는 mastra deploy로 대체되었습니다. 새로운 설정에서는 mastra deploy를 사용해야 합니다.
프로젝트를 빌드하여 Mastra 플랫폼의 서버에 배포합니다. 동일한 플래그, 인수 및 결정 로직을 사용하는 mastra studio deploy와 동일하게 작동합니다.
배포 명령은 프로젝트의 .env 파일을 사용합니다. MASTRA_PROJECT_ID가 Observability용으로 프로비저닝된 프로젝트를 가리키면 새 프로젝트를 생성하는 대신 해당 프로젝트에 배포를 연결합니다. Observability 전용 프로젝트에 Server를 배포하면 플랫폼에서 해당 프로젝트가 Server 프로젝트로 변환됩니다.
mastra server deploy [dir]
mastra server deploy suggestionsmastra-server-deploy-suggestions에 대한 직접 링크
실패한 서버 배포에 대한 진단 결과 및 제안된 수정 사항을 표시합니다.
mastra server deploy suggestions [deploy-id]
deploy-id를 생략하면 이 명령은 연결된 프로젝트의 최신 배포를 사용합니다. 아직 진단이 없으면 명령이 진단을 시작하고 결과가 준비될 때까지 폴링합니다. 진단에서 문제가 발견된 경우에만 제안이 표시됩니다.
mastra server pausemastra-server-pause에 대한 직접 링크
연결된 프로젝트에 대해 실행 중인 서버 인스턴스를 일시 중지합니다. 조직 및 프로젝트 해결은 다음과 동일하게 작동합니다.mastra server deploy.
mastra server pause
플래그플래그에 대한 직접 링크
--org--org-2에 대한 직접 링크
조직 ID. 다음을 통해서도 설정할 수 있습니다.MASTRA_ORG_ID environment variable.
--project--project-2에 대한 직접 링크
MASTRA_PROJECT_ID가 설정되지 않은 경우 사용할 프로젝트 ID 또는 슬러그입니다. 슬러그는 현재 조직의 프로젝트를 기준으로 확인됩니다.
-c, --config-c---config-2에 대한 직접 링크
프로젝트 구성 파일의 경로입니다. 기본값은.mastra-project.json.
인스턴스가 실행되고 있지 않으면 실패합니다.
mastra server restartmastra-server-restart에 대한 직접 링크
연결된 프로젝트에서 일시 중지되거나 중단된 서버 인스턴스를 다시 시작합니다. 플랫폼이 재시작을 수락한 후 CLI는 배포 ID를 확인하고(API 응답에서 확인하거나, 응답에 ID가 없으면 프로젝트 및 배포 메타데이터를 폴링하여 확인) 배포가 최종 상태에 도달할 때까지 mastra server deploy와 같은 방식으로 빌드 및 배포 로그를 스트리밍합니다.
플래그플래그에 대한 직접 링크
mastra server pause와 같은 플래그인 --org, --project, **-c / --config**를 동일한 기본값 및 동작으로 지원합니다.
mastra server restart
이 프로젝트에 대한 배포가 여전히 활성 상태이면 실패합니다(실행, 빌드, 배포 등). 이는 플랫폼 제한 사항이므로 다른 배포가 진행 중인 동안에는 다시 시작할 수 없습니다.
mastra server envmastra-server-env에 대한 직접 링크
연결된 서버 배포를 위한 환경 변수를 관리합니다. 조직 및 프로젝트 해결은 다음과 동일하게 작동합니다.mastra server deploy.
모든 하위 명령은 프로젝트 구성 파일 경로에 -c / --config를 지원합니다(기본값: .mastra-project.json).
mastra server env listmastra-server-env-list에 대한 직접 링크
연결된 프로젝트의 모든 환경 변수를 나열합니다. 값은 출력에서 부분적으로 마스크됩니다.
mastra server env setmastra-server-env-set에 대한 직접 링크
환경 변수를 설정합니다. CLI는 현재 맵을 읽고 변경 사항을 적용하고 결과를 업로드합니다.
mastra server env set <key> <value>
mastra server env unsetmastra-server-env-unset에 대한 직접 링크
환경 변수를 제거합니다.
mastra server env unset <key>
mastra server env importmastra-server-env-import에 대한 직접 링크
파일(예: .env 파일)에서 변수를 가져와 기존 맵에 병합합니다. 새 값은 서버에 이미 있는 키를 재정의합니다.
mastra server env import <file>
mastra server env pullmastra-server-env-pull에 대한 직접 링크
연결된 프로젝트에서 환경 변수를 다운로드하여 로컬 파일에 씁니다. 이는 반대이다.mastra server env import.
mastra server env pull [file]
인수를 지정하지 않으면 파일 기본값은 .env입니다. 안전하게 셸에서 소싱할 수 있도록 모든 값을 큰따옴표로 감싸고 이스케이프합니다. 유효한 셸 식별자가 아닌 키는 건너뜁니다. 비밀 값이 포함되므로 출력 파일은 제한적인 권한(0600)으로 생성됩니다.
--project--project-3에 대한 직접 링크
프로젝트 ID 또는 슬러그입니다. MASTRA_PROJECT_ID가 설정되지 않은 경우 연결된 프로젝트를 재정의합니다.
CI 사용법CI 사용법에 대한 직접 링크
지속적 통합 파이프라인에서는 MASTRA_API_TOKEN으로 인증하고 앱을 실행하기 전에 환경을 가져오세요.
export MASTRA_API_TOKEN="..."
mastra server env pull .env.production --project my-project
mastra authmastra-auth에 대한 직접 링크
Mastra 플랫폼 인증을 관리합니다. 자격 증명은 ~/.mastra/credentials.json에 저장됩니다. 대화형 로그인 대신 MASTRA_API_TOKEN 환경 변수를 설정할 수도 있습니다.
mastra auth loginmastra-auth-login에 대한 직접 링크
로그인을 위해 브라우저를 열고 자격 증명을 로컬에 저장합니다.
mastra auth logoutmastra-auth-logout에 대한 직접 링크
저장된 자격 증명을 제거합니다. 환경에 MASTRA_API_TOKEN이 계속 설정되어 있으면 CLI는 해당 토큰이 계속 사용된다고 경고합니다.
mastra auth whoamimastra-auth-whoami에 대한 직접 링크
현재 사용자 이메일, 사용자 ID, 활성 조직을 표시합니다.
mastra auth orgsmastra-auth-orgs에 대한 직접 링크
각 조직에서 귀하의 역할이 있는 모든 조직을 나열합니다. 현재 조직이 표시됩니다.
mastra auth orgs switchmastra-auth-orgs-switch에 대한 직접 링크
대화형 Prompt를 통해 활성 조직을 전환합니다. MASTRA_API_TOKEN 또는 MASTRA_ORG_ID 환경 변수가 설정된 경우에는 사용할 수 없습니다.
mastra auth tokensmastra-auth-tokens에 대한 직접 링크
마지막으로 사용한 날짜와 함께 모든 API 토큰을 나열합니다.
mastra auth tokens createmastra-auth-tokens-create에 대한 직접 링크
새 API 토큰을 만듭니다. 비밀은 한 번 표시되며 다시 검색할 수 없습니다.
mastra auth tokens create <name>
mastra auth tokens revokemastra-auth-tokens-revoke에 대한 직접 링크
API 토큰을 취소합니다.
mastra auth tokens revoke <token-id>
mastra lintmastra-lint에 대한 직접 링크
mastra lint 명령은 Mastra 프로젝트의 구조와 코드를 검증합니다.
기본적으로 mastra lint는 소스 파일과 구성을 대상으로 프로젝트 검사를 실행합니다. 배포 전에 .mastra/output을 대상으로 번들 검사도 실행하려면 --preflight를 사용하세요.
mastra lint --preflight
그것은 받아들인다common flags.
플래그플래그에 대한 직접 링크
--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 scorersmastra-scorers에 대한 직접 링크
mastra scorers 명령은 AI 생성 출력의 품질, 정확성 및 성능을 측정하는 평가 채점자 관리 기능을 제공합니다.
자세한 내용은 채점자 개요를 참조하세요.
addadd에 대한 직접 링크
프로젝트에 새로운 득점자를 추가하세요. 대화형 Prompt를 사용할 수 있습니다:
mastra scorers add
또는 득점자 이름을 직접 입력하세요.
mastra scorers add answer-relevancy
올바른 ID를 확인하려면 list 명령을 사용하세요.
listlist에 대한 직접 링크
사용 가능한 모든 득점자 템플릿을 나열합니다. 해당 ID를 사용하세요.add command.
mastra createmastra-create에 대한 직접 링크
동일한 프로젝트 생성 흐름을 사용하여 독립형 Mastra 프로젝트를 생성합니다.create-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을 지정하면 대화형 설정 Prompt를 건너뜁니다. 임의의 템플릿에는 --template [template]을 사용하고, Provider가 없는 최소 스캐폴드에는 --empty를 사용하세요.
이 명령은 감지된 코딩 도우미에 Mastra Skill을 설치하고 해당하는 경우 Git을 초기화합니다. 제외하려면 --no-skills 또는 --no-git을 사용하세요.
모드 동작, 충돌, 검증 및 전체 플래그 설명은 create-mastra 레퍼런스를 참조하세요.
mastra initmastra-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에 대한 직접 링크
기본 Model 공급자. 다음 중에서 선택하세요:"openai" | "anthropic" | "groq" | "google" | "cerebras" | "mistral".
--llm-api-key--llm-api-key에 대한 직접 링크
선택한 Model 공급자의 API 키입니다. 환경 변수 파일(.env).
--example--example에 대한 직접 링크
활성화되면 예제 코드가 구성 요소 목록에 기록됩니다(예: 예제 Agent 코드).
--no-example--no-example에 대한 직접 링크
예제 코드를 포함하지 마세요. 사용할 때 유용합니다.--default flag.
--mcp--mcp에 대한 직접 링크
Mastra의 MCP 서버로 코드 편집기를 구성하십시오. 다음 중에서 선택하세요:"cursor" | "cursor-global" | "windsurf" | "vscode".
--observability--observability에 대한 직접 링크
Mastra 플랫폼에서 Observability을 활성화합니다. CLI는 기존 플랫폼 프로젝트를 선택하거나 새 프로젝트를 생성하라는 메시지를 표시합니다. 그런 다음 필요한 환경 변수를 작성하고 Observability 내보내기를 구성합니다.
--no-observability--no-observability에 대한 직접 링크
Mastra Observability Prompt를 건너뜁니다.
--observability-project--observability-project에 대한 직접 링크
Mastra Observability가 활성화된 경우 사용할 플랫폼 프로젝트 이름을 설정합니다.
mastra migratemastra-migrate에 대한 직접 링크
데이터베이스 마이그레이션을 실행하여 스토리지 스키마를 업데이트합니다. 이 명령은 스토리지 스키마 변경 사항이 포함된 Mastra 버전을 업그레이드할 때 유용합니다.
이 명령은 프로젝트를 번들로 묶고 구성된 스토리지 백엔드에 연결합니다. 그런 다음 보류 중인 마이그레이션을 실행합니다. 현재 다음을 지원합니다.
- 중복 스팬 마이그레이션: 중복된
(traceId, spanId)항목을 제거하고 데이터 무결성을 보장하기 위한 고유 제약 조건을 추가합니다. - ClickHouse 레거시에서 vNext로의 스팬 마이그레이션: 레거시
mastra_ai_spans테이블의 과거 스팬을 vNextmastra_span_events스키마로 복사합니다. Memory 제한을 초과하지 않도록 배치 단위로 실행됩니다. 자세한 내용은 ClickHouse 스토리지 레퍼런스를 참조하세요.
mastra migrate
마이그레이션이 필요한 시점에 관한 자세한 내용은 스토리지 마이그레이션 가이드를 참조하세요. 그것은 받아들인다common flags.
mastra apimastra-api에 대한 직접 링크
JSON 입력 및 JSON 출력을 사용하여 Mastra 런타임 서버를 호출합니다. 로컬 개발 서버, 배포된 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에 기록되며 0이 아닌 종료 코드를 반환합니다.
{
"error": {
"code": "SERVER_UNREACHABLE",
"message": "Could not connect to target server",
"details": {}
}
}
목표 해상도목표 해상도에 대한 직접 링크
런타임 명령의 경우 명령은 다음 순서로 대상 서버를 확인합니다.
--url <url>명시적인 원격 또는 자체 호스팅 서버의 경우.http://localhost:4111현지인을 위해mastra devserver..mastra-project.jsonMastra 플랫폼 프로젝트를 위해.
자동 플랫폼 인증은 CLI가 .mastra-project.json에서 Mastra 플랫폼 대상을 확인한 경우에만 사용됩니다. localhost 대상과 명시적인 --url 대상에는 자동 자격 증명이 제공되지 않습니다. --header로 전달한 헤더는 localhost를 포함한 모든 대상에 전송됩니다.
Observability 명령(trace, log, score, metric)에서 CLI는 기본적으로 프로젝트 배포 URL 대신 https://observability.mastra.ai를 대상으로 사용합니다. Trace Intelligence 명령(learning)도 동일하게 작동하지만 https://output.signals.mastra.ai를 대상으로 사용합니다. 두 명령 모두 다음 순서로 자격 증명을 결정합니다.
--header로 전달한 명시적Authorization및X-Mastra-Project-Id헤더.- 환경의
MASTRA_PLATFORM_ACCESS_TOKEN및MASTRA_PROJECT_ID. - 프로젝트 ID에 사용할
.mastra-project.json의 프로젝트 메타데이터. - 인증 대체 수단으로 사용할 Mastra CLI 로그인 토큰.
학습 명령은
X-Mastra-Organization-Id도 전송합니다. 이 값은 명시적--header, 환경의MASTRA_ORGANIZATION_ID,.mastra-project.json순서로 결정됩니다. 기본 호스팅 Observability 대상이나 자격 증명을 재정의해야 할 때는--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입니다. 서버가 사용자 지정 접두사 아래에 마운트된 경우(예: prefix: "/api/mastra-studio"를 사용하는 @mastra/fastify MastraServer) 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 지향 요청 스키마를 인쇄합니다. 스키마는 대상 서버의 경로 계약에서 나오며 명령 모양, 위치, 예제, 요청 스키마 및 응답 모양을 포함합니다.
--schemaJSON 입력을 허용하는 리프 명령에서 사용할 수 있습니다. 최상위 수준으로는 사용할 수 없습니다.mastra api flag.
mastra api agent run --schema
mastra api tool execute --schema
입력 Model입력 Model에 대한 직접 링크
입력을 허용하는 명령은 하나의 인라인 JSON 인수를 사용합니다. 파일 경로나 stdin을 전달하지 마세요.
mastra api workflow run start data-pipeline '{"inputData":{"source":"s3://bucket/data.csv"}}'
안정적인 ID에는 위치 인수를 사용하고 필터나 페이로드에는 JSON을 사용하세요. 쿼리 매개변수와 요청 본문이 모두 필요한 경로의 경우 하나의 JSON 객체를 전달합니다. CLI는 서버 경로 스키마에 따라 입력을 분할합니다.
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 입력에서 이를 허용합니다. 예를 들어 Observability 추적 목록은 페이지 매김 및 경로 지원 필터를 지원합니다.
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를 사용하려면 Memory 인스턴스에서 작업 Memory가 활성화되어 있어야 하며, mastra api workflow run resume은 일시 중단된 Workflow 실행에서만 작동합니다.
명령명령에 대한 직접 링크
mastra api agent listmastra-api-agent-list에 대한 직접 링크
대상 서버에 등록된 Agent를 나열합니다. 경로 지원 필터에 대한 선택적 JSON 입력을 전달합니다.
mastra api agent list [input]
mastra api agent getmastra-api-agent-get에 대한 직접 링크
등록된 Agent 하나에 대한 메타데이터를 가져옵니다.
mastra api agent get <agentId>
mastra api agent runmastra-api-agent-run에 대한 직접 링크
JSON 입력으로 Agent를 실행합니다. 명령 도움말을 사용하여 텍스트 Prompt, 채팅 메시지 및 Memory 스레드 옵션에 대한 예를 확인하세요.
mastra api agent run <agentId> <input>
mastra api workflow listmastra-api-workflow-list에 대한 직접 링크
대상 서버에 등록된 Workflow를 나열합니다. 경로 지원 필터에 대한 선택적 JSON 입력을 전달합니다.
mastra api workflow list [input]
mastra api workflow getmastra-api-workflow-get에 대한 직접 링크
등록된 하나의 Workflow에 대한 메타데이터를 가져옵니다.
mastra api workflow get <workflowId>
mastra api workflow run startmastra-api-workflow-run-start에 대한 직접 링크
JSON 입력으로 Workflow 실행을 시작합니다. Workflow 시작 명령은 실행을 완료하는 데 더 오랜 시간이 걸릴 수 있으므로 대부분의 명령보다 긴 기본 제한 시간을 사용합니다.
mastra api workflow run start <workflowId> <input>
mastra api workflow run listmastra-api-workflow-run-list에 대한 직접 링크
Workflow에 대한 실행을 나열합니다. 경로 지원 필터 또는 페이지 매김을 위해 선택적 JSON 입력을 전달합니다.
mastra api workflow run list <workflowId> [input]
mastra api workflow run getmastra-api-workflow-run-get에 대한 직접 링크
ID별로 실행되는 하나의 Workflow를 가져옵니다.
mastra api workflow run get <workflowId> <runId>
mastra api workflow run resumemastra-api-workflow-run-resume에 대한 직접 링크
JSON 입력을 사용하여 일시 중단된 Workflow 실행을 재개합니다. 실행은 일시 중지된 상태여야 합니다.
mastra api workflow run resume <workflowId> <runId> <input>
mastra api workflow run cancelmastra-api-workflow-run-cancel에 대한 직접 링크
Workflow 실행을 취소합니다.
mastra api workflow run cancel <workflowId> <runId>
mastra api tool listmastra-api-tool-list에 대한 직접 링크
대상 서버에 등록된 Tool을 나열합니다. 경로 지원 필터에 대한 선택적 JSON 입력을 전달합니다.
mastra api tool list [input]
mastra api tool getmastra-api-tool-get에 대한 직접 링크
하나의 Tool에 대한 메타데이터 및 스키마를 가져옵니다.
mastra api tool get <toolId>
mastra api tool executemastra-api-tool-execute에 대한 직접 링크
JSON 입력으로 Tool을 실행합니다. 명시적인 data 객체를 전달하지 않으면 원시 Tool 입력이 경로의 data 필드로 래핑됩니다.
mastra api tool execute <toolId> <input>
mastra api mcp listmastra-api-mcp-list에 대한 직접 링크
대상 서버에 등록된 MCP(Model Context Protocol) 서버를 나열합니다. 경로 지원 필터에 대한 선택적 JSON 입력을 전달합니다.
mastra api mcp list [input]
mastra api mcp getmastra-api-mcp-get에 대한 직접 링크
하나의 MCP 서버에 대한 메타데이터를 가져옵니다.
mastra api mcp get <id>
mastra api mcp tool listmastra-api-mcp-tool-list에 대한 직접 링크
MCP 서버에서 노출되는 Tool을 나열합니다. 경로 지원 필터에 대한 선택적 JSON 입력을 전달합니다.
mastra api mcp tool list <serverId> [input]
mastra api mcp tool getmastra-api-mcp-tool-get에 대한 직접 링크
하나의 MCP Tool에 대한 메타데이터 및 스키마를 가져옵니다.
mastra api mcp tool get <serverId> <toolId>
mastra api mcp tool executemastra-api-mcp-tool-execute에 대한 직접 링크
JSON 입력으로 MCP Tool을 실행합니다. 명시적인 data 객체를 전달하지 않으면 원시 Tool 입력이 경로의 data 필드로 래핑됩니다.
mastra api mcp tool execute <serverId> <toolId> <input>
mastra api thread listmastra-api-thread-list에 대한 직접 링크
Memory 스레드를 나열합니다. 경로 지원 필터에 대한 선택적 JSON 입력을 전달합니다.
mastra api thread list [input]
mastra api thread getmastra-api-thread-get에 대한 직접 링크
ID별로 하나의 Memory 스레드를 가져옵니다.
mastra api thread get <threadId>
mastra api thread createmastra-api-thread-create에 대한 직접 링크
Memory 스레드를 생성합니다. 단일 JSON 입력 객체를 전달합니다. 서버 경로에서 필요한 경우 CLI는 agentId 같은 필드를 쿼리 매개변수로 분리합니다.
mastra api thread create <input>
mastra api thread updatemastra-api-thread-update에 대한 직접 링크
Memory 스레드를 업데이트합니다. agentId, resourceId, title, metadata 같은 필드가 포함된 단일 JSON 입력 객체를 전달합니다.
mastra api thread update <threadId> <input>
mastra api thread deletemastra-api-thread-delete에 대한 직접 링크
Memory 스레드를 삭제합니다. 경로에 필요한 agentId 및 resourceId 같은 쿼리 매개변수를 JSON 입력으로 전달합니다.
mastra api thread delete <threadId> <input>
mastra api thread messagesmastra-api-thread-messages에 대한 직접 링크
Memory 스레드에 대한 메시지를 나열합니다. 경로 지원 필터 또는 페이지 매김을 위해 선택적 JSON 입력을 전달합니다.
mastra api thread messages <threadId> [input]
mastra api memory searchmastra-api-memory-search에 대한 직접 링크
장기 Memory를 검색합니다. agentId, resourceId, searchQuery 같은 필수 필드를 확인하려면 --help 또는 --schema를 사용하세요.
mastra api memory search <input>
mastra api memory current getmastra-api-memory-current-get에 대한 직접 링크
스레드의 현재 작업 Memory를 읽습니다.
mastra api memory current get <input>
mastra api memory current updatemastra-api-memory-current-update에 대한 직접 링크
스레드의 현재 작업 Memory를 업데이트합니다. Memory 인스턴스에 대해 작업 Memory를 활성화해야 합니다.
mastra api memory current update <input>
mastra api memory statusmastra-api-memory-status에 대한 직접 링크
Agent 및 선택적 스레드 또는 리소스 컨텍스트에 대한 Memory 상태를 가져옵니다.
mastra api memory status <input>
mastra api trace listmastra-api-trace-list에 대한 직접 링크
Observability 추적을 나열합니다. 경로 지원 필터 또는 페이지 매김을 위해 선택적 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는 기본적으로 경량 루트 스팬 레코드를 반환하므로 대규모 입력, 출력, 속성 또는 메타데이터 페이로드를 가져오지 않고 Trace를 페이지 단위로 탐색할 수 있습니다. 전체 루트 스팬 레코드를 가져오려면 --verbose를 전달하세요.
mastra api trace getmastra-api-trace-get에 대한 직접 링크
전체 스팬 입력, 출력, 속성 또는 메타데이터 페이로드를 가져오지 않고 하나의 Observability Trace에 대한 간략한 타임라인을 가져옵니다. 전체 Trace 페이로드를 가져오려면 --verbose를 전달하세요.
mastra api trace get <traceId>
mastra api trace get <traceId> --verbose
mastra api trace spanmastra-api-trace-span에 대한 직접 링크
Observability Trace에서 하나의 전체 스팬을 가져옵니다. 검사할 스팬을 알고 있다면 trace get을 사용하세요.
mastra api trace span <traceId> <spanId>
mastra api log listmastra-api-log-list에 대한 직접 링크
Observability 로그를 나열합니다. 경로 지원 필터 또는 페이지 매김을 위해 선택적 JSON 입력을 전달합니다.
mastra api log list [input]
mastra api metric aggregatemastra-api-metric-aggregate에 대한 직접 링크
단일 집계 측정항목 값을 가져옵니다.
mastra api metric aggregate '{"name":["latency_ms"],"aggregation":"avg"}'
mastra api metric breakdownmastra-api-metric-breakdown에 대한 직접 링크
라벨이나 필드별로 그룹화된 측정항목 값을 가져옵니다.
mastra api metric breakdown '{"name":["latency_ms"],"aggregation":"avg","groupBy":["model"],"limit":10}'
mastra api metric timeseriesmastra-api-metric-timeseries에 대한 직접 링크
시간 경과에 따른 측정항목 값을 가져옵니다.
mastra api metric timeseries '{"name":["latency_ms"],"aggregation":"avg","interval":"1h"}'
mastra api metric percentilesmastra-api-metric-percentiles에 대한 직접 링크
시간 경과에 따른 메트릭의 백분위수 값을 가져옵니다. 백분위수 값에는 0부터 1까지의 소수를 사용합니다.
mastra api metric percentiles '{"name":"latency_ms","percentiles":[0.5,0.95,0.99],"interval":"1h"}'
mastra api metric namesmastra-api-metric-names에 대한 직접 링크
검색된 메트릭 이름을 나열합니다. 접두사 검색 및 제한을 위해 선택적 JSON 입력을 전달합니다.
mastra api metric names '{"prefix":"lat","limit":10}'
mastra api metric label-keysmastra-api-metric-label-keys에 대한 직접 링크
측정항목의 라벨 키를 나열합니다.
mastra api metric label-keys '{"metricName":"latency_ms"}'
mastra api metric label-valuesmastra-api-metric-label-values에 대한 직접 링크
측정항목 라벨 키의 라벨 값을 나열합니다. 선택적 접두사 및 제한 값을 전달하여 결과 범위를 좁힙니다.
mastra api metric label-values '{"metricName":"latency_ms","labelKey":"model","prefix":"g","limit":10}'
Observabilitycurlobservability-with-curl에 대한 직접 링크
플랫폼 액세스 토큰 및 프로젝트 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
가벼운 추적 타임라인을 얻으세요:
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
특정 범위를 가져옵니다.
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 createmastra-api-score-create에 대한 직접 링크
Observability 점수를 생성합니다. 입력은 서버 점수 본문 모양을 사용합니다. 그것을 검사--schema.
mastra api score create <input>
mastra api score listmastra-api-score-list에 대한 직접 링크
Observability 점수를 나열합니다. 실행 ID 또는 페이지 매김과 같은 필터에 대한 선택적 JSON 입력을 전달합니다.
mastra api score list [input]
mastra api score getmastra-api-score-get에 대한 직접 링크
ID별로 하나의 Observability 점수를 가져옵니다.
mastra api score get <scoreId>
mastra api dataset listmastra-api-dataset-list에 대한 직접 링크
데이터세트를 나열합니다. 경로 지원 필터 또는 페이지 매김을 위해 선택적 JSON 입력을 전달합니다.
mastra api dataset list [input]
mastra api dataset getmastra-api-dataset-get에 대한 직접 링크
ID별로 하나의 데이터 세트를 가져옵니다.
mastra api dataset get <datasetId>
mastra api dataset createmastra-api-dataset-create에 대한 직접 링크
JSON 입력으로 데이터세트를 만듭니다.
mastra api dataset create <input>
mastra api dataset itemsmastra-api-dataset-items에 대한 직접 링크
데이터 세트의 항목을 나열합니다. 경로 지원 필터 또는 페이지 매김을 위해 선택적 JSON 입력을 전달합니다.
mastra api dataset items <datasetId> [input]
mastra api experiment listmastra-api-experiment-list에 대한 직접 링크
데이터 세트에 대한 실험을 나열합니다. 경로 지원 필터 또는 페이지 매김을 위해 선택적 JSON 입력을 전달합니다.
mastra api experiment list <datasetId> [input]
mastra api experiment getmastra-api-experiment-get에 대한 직접 링크
ID별로 하나의 실험을 가져옵니다.
mastra api experiment get <datasetId> <experimentId>
mastra api experiment runmastra-api-experiment-run에 대한 직접 링크
JSON 입력을 사용하여 데이터 세트에 대한 실험을 시작합니다.
mastra api experiment run <datasetId> <input>
mastra api experiment resultsmastra-api-experiment-results에 대한 직접 링크
실험 결과를 나열합니다. 경로 지원 필터 또는 페이지 매김을 위해 선택적 JSON 입력을 전달합니다.
mastra api experiment results <datasetId> <experimentId> [input]
mastra api learning entitiesmastra-api-learning-entities에 대한 직접 링크
엔터티별로 사용할 수 있는 추적 신호를 포함하여 Trace Intelligence 출력과 함께 엔터티(Agent)를 나열합니다. Trace Intelligence 비공개 베타에 등록해야 합니다.
mastra api learning entities '{"entityType":"agent"}'
mastra api learning snapshotsmastra-api-learning-snapshots에 대한 직접 링크
엔터티의 분석 스냅샷과 순서가 지정된 쉼표 구분 Trace 신호 목록을 나열합니다. 이후 명령에는 이 목록의 snapshotId가 필요합니다.
mastra api learning snapshots <entityId> '{"entityType":"agent","signalNames":"goal,outcome,behavior,sentiment","limit":10}'
mastra api learning flowmastra-api-learning-flow에 대한 직접 링크
하나의 스냅샷에 대한 교차 신호 테마 흐름을 가져옵니다. 개수가 고유한 추적인 Sankey 스타일 보기의 단계 및 링크입니다.
mastra api learning flow <entityId> '{"entityType":"agent","signalNames":"goal,outcome","snapshotId":"<snapshotId>"}'
mastra api learning pathsmastra-api-learning-paths에 대한 직접 링크
하나의 스냅샷에서 정렬된 Trace 신호 전체에 대한 Trace별 테마 할당을 가져옵니다. limit과 offset으로 페이지네이션합니다.
mastra api learning paths <entityId> '{"entityType":"agent","signalNames":"goal,outcome","snapshotId":"<snapshotId>","limit":100}'
mastra api learning theme listmastra-api-learning-theme-list에 대한 직접 링크
하나의 스냅샷에 하나의 추적 신호에 대한 테마를 나열합니다.
mastra api learning theme list <entityId> '{"entityType":"agent","signalName":"goal","snapshotId":"<snapshotId>"}'
mastra api learning theme getmastra-api-learning-theme-get에 대한 직접 링크
숫자 테마 ID로 하나의 스냅샷에서 하나의 테마를 가져옵니다.
mastra api learning theme get <entityId> <themeId> '{"entityType":"agent","signalName":"goal","snapshotId":"<snapshotId>"}'
mastra api learning theme examplesmastra-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 historymastra-api-learning-theme-history에 대한 직접 링크
분할 및 병합 관계를 포함하여 스냅샷 전체에서 하나의 지속 가능한 테마에 대한 수명 주기 기록을 가져옵니다. 아니오snapshotId.
mastra api learning theme history <entityId> <themeId> '{"entityType":"agent","signalName":"goal"}'
mastra api learning noise getmastra-api-learning-noise-get에 대한 직접 링크
하나의 스냅샷에서 하나의 추적 신호에 대한 클러스터되지 않은(노이즈) 버킷을 가져옵니다.
mastra api learning noise get <entityId> '{"entityType":"agent","signalName":"goal","snapshotId":"<snapshotId>"}'
mastra api learning noise examplesmastra-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는 OS, Mastra 버전, Node.js 버전 등 프로젝트에 관한 익명 정보를 수집합니다. 수집되는 정보를 확인하려면 소스 코드를 참조하세요.
mastra dev 또는 mastra start로 시작한 서버에서 Observability 메트릭이 활성화된 경우, Mastra는 시작 시 익명으로 집계된 Model 사용량도 전송합니다. 여기에는 Provider 및 Model별 입력·출력 토큰 수와 명령(dev 또는 start) 및 NODE_ENV가 포함됩니다. Prompt, 응답 또는 기타 메시지 콘텐츠는 전송되지 않습니다. 수집되는 정보를 확인하려면 소스 코드를 참조하세요.
서버가 시작될 때 Mastra는 등록된 Agent, Agent 컨트롤러, Workflow, Tool, 프로세서, 벡터 저장소, 채점자, Workspace, MCP 서버, 게이트웨이 및 채널의 수와 Memory, 음성, 편집기 및 Observability 사용 여부, 대략적인 스토리지 백엔드 범주를 포함한 익명의 프로젝트 기능 스냅샷도 전송합니다. 이름이나 식별자는 전송하지 않습니다. 수집되는 정보를 확인하려면 소스 코드를 참조하세요.
환경 변수를 설정하여 모든 CLI 및 사용량 분석을 옵트아웃할 수 있습니다.
MASTRA_TELEMETRY_DISABLED=1
다른 것을 사용하는 동안에도 이를 설정할 수 있습니다.mastra commands:
MASTRA_TELEMETRY_DISABLED=1 mastra dev