> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt # CLI 명령 Mastra에서 제공하는 명령줄 인터페이스(CLI)를 사용하여 Mastra 프로젝트를 개발, 빌드 및 시작할 수 있습니다. ## `mastra dev` Agent, Tool, Workflow를 위한 [Studio](https://mastra.zisheng.pro/ko/docs/studio/overview) 및 REST 엔드포인트를 노출하는 서버를 시작합니다. `mastra dev`가 실행 중일 때 에서 사용 가능한 모든 엔드포인트의 개요를 확인할 수 있습니다. [서버를 구성](https://mastra.zisheng.pro/ko/reference/configuration)할 수도 있습니다. ### 플래그 이 명령은 [공통 플래그](#common-flags)와 다음 추가 플래그를 받습니다. #### `--https` 로컬 HTTPS 지원을 활성화합니다.[Learn more](https://mastra.zisheng.pro/ko/reference/configuration). #### `--inspect` 디버깅에 도움이 되는 검사 모드로 개발 서버를 시작합니다. 선택적으로 사용자 정의 호스트와 포트를 지정합니다(예: Docker의 경우 `--inspect=0.0.0.0:9229`). `--inspect-brk`와 함께 사용할 수 없습니다. #### `--inspect-brk` 검사 모드로 개발 서버를 시작하고 스크립트 시작 부분에서 중단합니다. 선택적으로 사용자 정의 호스트와 포트를 지정합니다(예: `--inspect-brk=0.0.0.0:9229`). `--inspect`와 함께 사용할 수 없습니다. #### `--custom-args` Node.js 프로세스에 전달할 사용자 정의 인수의 쉼표로 구분된 목록입니다. 예: `--require=newrelic` 또는 `--experimental-transform-types`. #### `--request-context-presets` [요청 컨텍스트](https://mastra.zisheng.pro/ko/docs/server/request-context) 프리셋이 포함된 JSON 파일의 경로입니다. 제공하면 Studio의 요청 컨텍스트 편집기에 드롭다운이 표시되어 프리셋 구성 간에 빠르게 전환할 수 있습니다. ```bash mastra dev --request-context-presets ./presets.json ``` 파일은 각 키가 사전 설정된 이름이고 각 값이 객체인 JSON 객체여야 합니다. ```json { "development": { "userId": "dev-user", "env": "development" }, "production": { "userId": "prod-user", "env": "production" } } ``` ### 구성 환경 변수를 설정하여 동작을 수정할 수 있습니다.`mastra dev`. #### 피어 종속성 검사 건너뛰기 시작 시 피어 종속성 버전 불일치 검사를 건너뛰려면 `MASTRA_SKIP_PEERDEP_CHECK=1`을 설정하세요. ```bash MASTRA_SKIP_PEERDEP_CHECK=1 mastra dev ``` 이는 피어 종속성이 충돌할 수 있지만 패키지가 아직 게시되지 않은 단일 저장소 개발 중에 유용합니다. #### 빌드 캐싱 비활성화 `.mastra/` 아래에 캐시된 자산을 사용하지 않고 전체 빌드를 강제하려면 `MASTRA_DEV_NO_CACHE=1`을 설정하세요. ```bash MASTRA_DEV_NO_CACHE=1 mastra dev ``` 이는 번들러 플러그인을 디버깅하거나 오래된 출력이 의심되는 경우에 도움이 됩니다. #### 병렬성 제한 `MASTRA_CONCURRENCY`병렬로 실행되는 비용이 많이 드는 작업 수를 제한합니다(주로 빌드 및 평가 단계). 예를 들어: ```bash MASTRA_CONCURRENCY=4 mastra dev ``` CLI가 시스템에 적합한 기본값을 선택하도록 하려면 설정하지 않은 채로 두십시오. #### 맞춤형 제공자 엔드포인트 Vercel AI SDK에서 지원하는 공급자를 사용하는 경우 기본 URL을 설정하여 프록시 또는 내부 게이트웨이를 통해 요청을 리디렉션할 수 있습니다. OpenAI의 경우: ```bash OPENAI_API_KEY= \ OPENAI_BASE_URL=https://openrouter.example/v1 \ mastra dev ``` 인류를 위한: ```bash ANTHROPIC_API_KEY= \ ANTHROPIC_BASE_URL=https://anthropic.internal \ mastra dev ``` 이 값은 Mastra Model 라우터에 전달되며 모든 `"openai/..."` 또는 `"anthropic/..."` Model 선택에서 작동합니다. ## `mastra factory dev` [Agent Builder](https://agent-builder.mastra.ai/) 개발을 위한 개발 서버를 시작합니다. [`mastra dev`](#mastra-dev)와 동일한 개발 런타임 및 플래그를 사용하며 같은 `.mastra/output` 디렉터리에 기록합니다. ```bash npx mastra factory dev ``` 두 명령은 동일한 개발 잠금을 공유하므로 같은 프로젝트에서 `mastra dev`와 `mastra factory dev`를 동시에 실행할 수 없습니다. 하나가 이미 실행 중이면 다른 하나는 중복 개발 서버 오류와 함께 종료됩니다. Agent Builder 기능을 개발할 때 `mastra factory dev`를 사용하세요. `--https`, `--inspect`, `--inspect-brk`, `--custom-args`, `--request-context-presets`를 비롯해 [`mastra dev`](#mastra-dev)와 동일한 플래그를 받습니다. ## `mastra build` `mastra build` 명령은 Mastra 프로젝트를 프로덕션용 Hono 서버로 번들링합니다. [Hono](https://hono.dev/)는 미들웨어를 지원하는 HTTP 엔드포인트로 Mastra Agent를 간편하게 배포할 수 있게 해주는 경량 타입 안전 웹 프레임워크입니다. 내부적으로 Mastra의 롤업 서버는 Mastra 항목 파일을 찾아 이를 프로덕션용 Hono 서버에 번들로 묶습니다. 번들링하는 동안 코드를 트리 셰이크하고 디버깅을 위한 소스 맵을 생성합니다. `.mastra`의 출력은 [`mastra start`](#mastra-start)를 사용하여 모든 클라우드 서버에 배포할 수 있습니다. [서버리스 플랫폼](https://mastra.zisheng.pro/ko/docs/deployment/cloud-providers)에 배포하는 경우 `.mastra`에 올바른 출력을 생성하려면 적절한 배포 도구를 설치해야 합니다. 그것은 받아들인다[common flags](#common-flags). ### 플래그 #### `--studio` Studio UI를 빌드와 함께 번들로 묶습니다. ### 구성 환경 변수를 설정하여 동작을 수정할 수 있습니다.`mastra build`. #### 피어 종속성 검사 건너뛰기 피어 종속성 버전 불일치 검사를 건너뛰려면 `MASTRA_SKIP_PEERDEP_CHECK=1`을 설정하세요. ```bash MASTRA_SKIP_PEERDEP_CHECK=1 mastra build ``` #### 병렬성 제한 CI의 경우 또는 리소스가 제한된 환경에서 실행할 때 설정을 통해 한 번에 실행되는 비용이 많이 드는 작업 수를 제한할 수 있습니다.`MASTRA_CONCURRENCY`. ```bash MASTRA_CONCURRENCY=2 mastra build ``` ## `mastra start` > **정보:** `mastra start`를 사용하기 전에 `mastra build`를 실행해야 합니다. 프로덕션 모드에서 빌드된 Mastra 애플리케이션을 제공하기 위한 로컬 서버를 시작합니다. 기본적으로 [OTEL Tracing](https://mastra.zisheng.pro/ko/docs/observability/tracing/overview)이 활성화됩니다. ### 플래그 이 명령은 [공통 플래그](#common-flags)와 다음 추가 플래그를 받습니다. #### `--dir` 빌드된 Mastra 출력 디렉터리의 경로입니다. 기본값은`.mastra/output`. #### `--custom-args` Node.js 프로세스에 전달할 사용자 정의 인수의 쉼표로 구분된 목록입니다. 예: `--require=newrelic` 또는 `--experimental-transform-types`. ## `mastra worker build` 작업자 배포를 위해 Mastra 애플리케이션을 번들링합니다. `mastra build`와 동일하게 자체 완결형 `.mastra/output/` 디렉터리를 생성합니다. ```bash mastra worker build [options] ``` ### 플래그 #### `--dir` Mastra 소스 디렉터리의 경로입니다. 기본값은`src/mastra`. #### `--root` 프로젝트 루트 디렉터리. 기본값은 현재 디렉터리입니다. #### `--tools` 번들에 포함할 쉼표로 구분된 Tool 경로입니다. #### `--output-dir` 사용자 정의 출력 디렉터리. 기본값은`.mastra/output`. #### `--debug` 빌드 중에 디버그 로깅을 활성화합니다. ## `mastra experiment build` HTTP 서버를 노출하지 않고 실험을 실행하는 독립 실행형 보조 작업자를 빌드합니다. 작업자는 내보낸 `Mastra` 인스턴스를 로드하고 표준 입력에서 버전이 지정된 줄바꿈 구분 JSON(NDJSON) 프로토콜 메시지를 받습니다. 프로토콜 이벤트는 표준 출력에 기록합니다. ```bash 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` Mastra 소스 디렉터리의 경로입니다. 기본값은`src/mastra`. #### `--root` 프로젝트 루트 디렉터리. 기본값은 현재 디렉터리입니다. #### `--output-dir` 사용자 정의 아티팩트 디렉터리. 상대 경로는 프로젝트 루트에서 확인됩니다. 기본값은`.mastra/experiment-worker`. #### `--debug` 빌드 중에 디버그 로깅을 활성화합니다. ## `mastra worker start` > **정보:** `mastra worker start`를 사용하기 전에 `mastra worker build` 또는 `mastra build`를 실행해야 합니다. 이전에 빌드한 번들에서 워커 프로세스를 시작합니다. 선택적 `name` 인수는 생성된 프로세스에서 `MASTRA_WORKERS`를 설정하여 시작할 워커를 제어합니다. ```bash mastra worker start [name] [options] ``` ### 플래그 #### `--dir` 빌드 출력 디렉터리의 경로입니다. 기본값은`.mastra/output`. #### `--env` 환경 파일의 경로입니다. 기본값은 `.env.production`이며, 없으면 `.env`를 사용합니다. ### 예 ```bash # Start only the orchestration worker mastra worker start orchestration # Start only the scheduler mastra worker start scheduler # Start from a custom build directory mastra worker start orchestration --dir ./dist ``` 배포 토폴로지와 구성에 관한 내용은 [Workers](https://mastra.zisheng.pro/ko/docs/deployment/workers)를 참조하세요. ## `mastra studio` [Studio](https://mastra.zisheng.pro/ko/docs/studio/overview)를 정적 서버로 시작합니다. 시작한 후 Mastra 인스턴스 URL(예: `http://localhost:4111`)을 입력하여 Studio를 Mastra 백엔드에 연결할 수 있습니다. 구성에 사용할 `.env` 및 `.env.production` 파일을 현재 작업 디렉터리에서 찾습니다. ### 플래그 이 명령은 [공통 플래그](#common-flags)와 다음 추가 플래그를 지원합니다. #### `--port` Studio를 실행할 포트입니다. 기본값은`3000`. #### `--server-host` 연결할 Mastra API 서버의 호스트입니다. 기본값은`localhost`. #### `--server-port` 연결할 Mastra API 서버의 포트입니다. 기본값은`4111`. #### `--server-protocol` 연결할 Mastra API 서버의 프로토콜입니다. 기본값은`http`. #### `--server-api-prefix` Mastra API 서버의 API 경로 접두사입니다. 기본값은`/api`. #### `--request-context-presets` [요청 컨텍스트](https://mastra.zisheng.pro/ko/docs/server/request-context) 프리셋이 포함된 JSON 파일의 경로입니다. [`mastra dev` 플래그](#--request-context-presets)와 동일하게 작동합니다. ```bash mastra studio --request-context-presets ./presets.json ``` ## `mastra deploy` `--env`로 선택한 Mastra 플랫폼 환경에 프로젝트를 빌드하고 배포합니다. 모든 신규 배포에 권장되는 명령이며, 계속 작동하지만 새로운 설정에는 더 이상 사용하지 않아야 하는 [`mastra studio deploy`](#mastra-studio-deploy)와 [`mastra server deploy`](#mastra-server-deploy)를 모두 대체합니다. [`mastra auth login`](#mastra-auth-login) 또는 `MASTRA_API_TOKEN` 환경 변수를 통한 인증이 필요합니다. ```bash mastra deploy mastra deploy --env staging mastra deploy --env production --region eu ``` 이 명령은 `mastra build`를 실행하고 결과물을 압축한 후 선택한 환경에 업로드합니다. 그런 다음 배포가 최종 상태에 도달할 때까지 빌드 로그를 스트리밍하면서 배포 상태를 폴링합니다. 조직, 프로젝트, 환경은 환경 변수(`MASTRA_ORG_ID`, `MASTRA_PROJECT_ID`), CLI 플래그(`--org`, `--project`, `--env`), `.mastra-project.json` 구성 파일, 자격 증명의 현재 조직, 마지막으로 대화형 Prompt 순서로 결정됩니다. 최초 배포 시 CLI는 결정된 조직 및 프로젝트 ID를 `.mastra-project.json`에 저장하므로 이후 배포에서는 Prompt를 건너뜁니다. 프로젝트가 아직 없으면 CLI는 확인 후 `package.json`의 `name` 필드를 사용하여 프로젝트를 생성합니다. 대상 환경이 없으면 CLI는 확인 후 해당 환경을 생성합니다(`production` 이외의 환경은 기본적으로 `type: staging`). `--yes`와 함께 사용하면 다음과 같이 하나의 비대화형 명령으로 모든 항목을 생성하고 배포합니다. ```bash mastra deploy --env staging --yes ``` `--env `이 설정되고 `--env-file`이 설정되지 않은 경우, 프로젝트 디렉터리에 `.env.`이 있으면 CLI가 이를 자동으로 선택합니다(예: `.env.staging`). `` 값은 파일 경로에 삽입되기 전에 엄격한 허용 목록을 기준으로 검증됩니다. ### 인수 #### `[dir]` 프로젝트 디렉토리. 기본값은 현재 디렉터리입니다. ### 플래그 #### `--env` 대상 환경 이름입니다. 기본값은 `production`입니다. `--env-file`이 설정되지 않은 경우 프로젝트 디렉터리에서 `.env.`을 자동으로 선택합니다. 환경이 없으면 CLI가 확인 후 생성합니다. #### `--org` 조직 ID. 다음을 통해서도 설정할 수 있습니다.`MASTRA_ORG_ID` environment variable. #### `--project` 프로젝트 ID, 슬러그 또는 이름입니다. `MASTRA_PROJECT_ID` 환경 변수로도 설정할 수 있습니다. 일치하는 프로젝트가 없으면 이 값이 배포 시 생성할 새 프로젝트의 이름으로 사용됩니다. #### `-y, --yes` 프로젝트 및 환경 생성을 포함하여 확인 메시지 없이 기본값을 자동으로 수락합니다. #### `-c, --config` 프로젝트 구성 파일의 경로입니다. 기본값은`.mastra-project.json`. #### `--env-file` 배포에 함께 번들링할 env 파일의 경로입니다(프로젝트 디렉터리 기준). 설정하면 `--env`를 기반으로 한 `.env.` 자동 선택이 비활성화됩니다. ```bash mastra deploy --env staging --env-file .env.staging.local ``` #### `--region` 새로 생성되는 환경의 리전입니다(예: `eu`). CLI가 환경을 생성할 때만 적용됩니다. #### `--skip-build` 빌드 단계를 건너뛰고 기존 `.mastra/output` 디렉터리를 배포합니다. 기존 빌드가 현재 소스보다 오래된 경우 CLI가 경고합니다. #### `--skip-preflight` 빌드된 출력의 사전 업로드 유효성 검사를 건너뜁니다. #### `--debug` 빌드 단계 중에 디버그 로그를 활성화합니다. ### CI/CD 사용 헤드리스 배포에서는 `MASTRA_API_TOKEN`, `MASTRA_ORG_ID`, `MASTRA_PROJECT_ID`를 환경 변수로 설정하세요. `MASTRA_API_TOKEN`이 설정되면 대화형 Prompt를 자동으로 건너뜁니다. 환경 생성을 자동 승인하려면 `--yes`와 함께 사용하세요. ```bash export MASTRA_API_TOKEN="..." export MASTRA_ORG_ID="..." export MASTRA_PROJECT_ID="..." mastra deploy --env staging --yes ``` ## `mastra env` Mastra 플랫폼에서 환경을 관리합니다. 환경은 프로젝트에 속하는 배포 대상입니다(예: `production`, `staging`, `preview-42`). 현재 조직은 저장된 자격 증명에서 결정됩니다. 모든 하위 명령은 고정된 순서로 프로젝트를 결정합니다. 먼저 `MASTRA_PROJECT_ID` 환경 변수와 `--project ` 플래그를 확인합니다. 그런 다음 현재 디렉터리에서 [`mastra deploy`](#mastra-deploy)가 작성한 `.mastra-project.json` 파일을 읽습니다. 프로젝트 디렉터리에서 실행하면 프로젝트를 지정할 필요가 없습니다. ### `mastra env list` 프로젝트의 환경을 나열합니다. 각 환경에는 최신 배포(트래픽을 처리 중이면 `(active)` 표시)와 연결된 데이터베이스 같은 관리형 리소스가 주입한 env 변수 이름이 표시됩니다. ```bash mastra env list ``` #### `--json` 기계가 읽을 수 있는 JSON을 내보냅니다. 중요하지 않은 메타데이터(id, 이름, 슬러그, 유형, 지역, 분기, URL, 관리 환경 변수 이름 및 최신 배포 상태)만 포함되므로 출력은 CI에 안전하게 로그인할 수 있습니다. ### `mastra env create` 프로젝트에 대한 새 환경을 만듭니다. ```bash mastra env create staging --type staging --region eu ``` #### `-t, --type` 환경 유형입니다. `production`, `staging`, `preview` 중 하나이며, 기본값은 `staging`입니다. #### `-r, --region` 환경 지역(예:`eu`). #### `--json` 기계가 읽을 수 있는 JSON을 내보냅니다. 다음과 같이 민감한 필드는 생략됩니다.[`mastra env list`](#mastra-env-list). ### `mastra env delete` 환경을 삭제합니다. ```bash mastra env delete ``` ``는 환경 이름, 슬러그 또는 ID일 수 있습니다. `--yes`를 전달하지 않으면 CLI에 확인 Prompt가 표시됩니다. #### `-y, --yes` 확인 메시지를 건너뜁니다. ### `mastra env restart` 환경의 실행 중인 서비스를 다시 시작하여 저장된 환경 변수(연결된 데이터베이스의 관리 변수 포함)가 새 배포 없이 즉시 적용됩니다. ```bash mastra env restart ``` ``환경 이름, 슬러그 또는 ID일 수 있습니다. 환경이 배포된 적이 없는 경우 충돌 오류로 인해 실패합니다. ### `mastra env vars pull` 환경의 env 변수를 로컬 env 파일(기본값: `.env`)로 가져옵니다. 이 파일에는 배포에서 사용되는 병합된 변수 집합이 포함됩니다. 환경에 저장된 변수(예: 대시보드의 환경 편집기에서 추가한 변수)와 프로젝트 수준 변수가 결합되며, 충돌하면 프로젝트 값이 우선합니다. 연결된 데이터베이스가 주입하는 관리형 변수는 플랫폼이 관리하는 비밀 값이므로 이름만 주석으로 나열됩니다. ```bash mastra env vars pull mastra env vars pull --output .env.staging ``` ``는 환경 이름, 슬러그 또는 ID일 수 있으며, 프로젝트에 환경이 정확히 하나만 있으면 생략할 수 있습니다. 파일은 `0600` 권한으로 작성됩니다. 출력 파일이 이미 있으면 명령이 중지됩니다. 교체하려면 `--force`를 전달하세요. #### `-o, --output` 쓸 파일입니다. 기본값은`.env`. #### `-f, --force` 기존 출력 파일을 바꿉니다. ### `mastra env db` Mastra 플랫폼의 프로젝트에 연결된 데이터베이스를 관리합니다. 데이터베이스는 관리형 공급자(예: Turso 또는 Neon)에서 프로비저닝되고 해당 연결 환경 변수를 배포에 자동으로 삽입합니다. 데이터베이스는 **환경 범위**(env 변수가 한 환경에만 적용됨) 또는 **공유**(프로젝트 범위: env 변수가 모든 환경에 적용됨) 중 하나입니다. `mastra env db create`의 기본값은 환경 범위입니다. 환경 인수를 전달하거나 CLI가 환경을 선택하거나 묻도록 두세요. 대신 공유 데이터베이스를 연결하려면 생성 시 `--shared`를 전달하세요. 다른 하위 명령(`list`, `delete`, `keys`)에서는 환경 범위 데이터베이스를 다룰 때 환경 인수를 전달하고, 공유 데이터베이스를 다룰 때는 생략하세요. 데이터베이스를 생성하고 삭제하려면 조직에서 `admin` 역할이 필요합니다. ### `mastra env db list` 공급자, 프로비저닝 상태, 범위(각 데이터베이스가 제공하는 환경) 및 각 데이터베이스가 삽입하는 환경 변수 이름을 포함하여 프로젝트에 연결된 데이터베이스를 나열합니다. 해당 환경(환경 범위 및 공유)을 제공하는 데이터베이스만 표시하려면 환경을 전달합니다. ```bash mastra env db list mastra env db list ``` #### `--json` 기계가 읽을 수 있는 JSON을 내보냅니다. ### `mastra env db create` 관리형 데이터베이스를 프로비저닝하고 연결한 다음 준비될 때까지 폴링합니다. 프로비저닝 오류는 공급자의 오류 세부정보와 함께 인쇄됩니다. 기본적으로 데이터베이스의 범위는 단일 환경으로 지정됩니다. 환경을 선택하려면 환경 인수를 전달하고, CLI가 자동으로 선택하도록 하려면 인수를 생략하세요. 프로젝트에 환경이 하나뿐이면 해당 환경을 사용합니다. 환경이 여러 개면 CLI가 대화형으로 선택하라는 Prompt를 표시합니다. 비대화형 컨텍스트(CI, `--json`)에서는 환경 인수가 필요합니다. 대신 모든 환경이 공유하는 프로젝트 범위 데이터베이스를 연결하려면 `--shared`를 전달하세요. 환경 범위 데이터베이스는 환경에서 공급자 지역을 상속합니다. 공유 데이터베이스 허용`--region`. ```bash mastra env db create --kind turso # picks or prompts for an environment mastra env db create staging --kind turso # scoped to the "staging" environment mastra env db create --kind turso --shared # shared by all environments mastra env db create --kind neon --name my-app-db --region aws-us-east-1 --shared ``` #### `--kind` 데이터베이스 Provider입니다(필수). `turso` 또는 `neon` 중 하나입니다. #### `--name` 데이터베이스 이름. 기본값은 프로젝트 슬러그에서 파생된 이름입니다(예:`my-app-db`). #### `--region` 공유 데이터베이스의 공급자 지역 ID입니다. 환경 범위 데이터베이스의 경우 무시됩니다. #### `--shared` 모든 환경에서 공유되는 프로젝트 범위 데이터베이스로 연결합니다. 환경 인수와 결합할 수 없습니다. #### `--no-wait` 데이터베이스가 준비될 때까지 폴링하는 대신 연결이 대기열에 추가된 후 즉시 반환합니다. 나중에 진행 상황을 확인하세요.`mastra env db show`. #### `--json` 기계 판독 가능한 JSON을 출력합니다. 이 모드에서 프로젝트에 환경이 두 개 이상이면 환경 인수 또는 `--shared`가 필요합니다(대화형 Prompt 없음). ### `mastra env db show` 데이터베이스 세부 정보를 표시하고, 데이터베이스가 준비되면 해당 연결 환경 변수를 표시합니다. 비밀 값은 기본적으로 마스크되어 있습니다. ```bash mastra env db show ``` ``데이터베이스 ID 또는 이름일 수 있습니다. #### `--show-secrets` 비밀 연결 값을 마스킹하는 대신 인쇄하세요. #### `--json` 기계 판독 가능한 JSON을 출력합니다. `--show-secrets`를 전달하지 않으면 비밀 값이 마스킹됩니다. ### `mastra env db delete` 모든 데이터를 포함하여 Provider에서 데이터베이스를 영구적으로 삭제합니다. 이 작업은 되돌릴 수 없습니다. `--yes`를 전달하지 않으면 CLI에 확인 Prompt가 표시됩니다. 삭제 후 배포에는 더 이상 데이터베이스의 env 변수가 제공되지 않습니다. ```bash mastra env db delete ``` #### `-y, --yes` 확인 메시지를 건너뜁니다. ### `mastra env deploys` 프로젝트에 대한 배포를 최신 항목부터 나열합니다. 트래픽을 제공하는 배포가 표시됩니다.`(active)`. ```bash mastra env deploys [environment] ``` 모든 환경의 배포를 표시하려면 `[environment]`를 생략하고, 하나의 환경으로 필터링하려면 환경 이름, 슬러그 또는 ID를 전달하세요. #### `--json` 기계가 읽을 수 있는 JSON을 내보냅니다. ## `mastra studio deploy` > **정보:** `mastra studio deploy`는 계속 작동하지만, 단일 프로젝트에서 환경(`--env staging`, `--env production`)을 지원하는 [`mastra deploy`](#mastra-deploy)로 대체되었습니다. 새로운 설정에서는 `mastra deploy`를 사용해야 합니다. 프로젝트를 빌드하여 Mastra 플랫폼에 배포합니다. [`mastra auth login`](#mastra-auth-login) 또는 `MASTRA_API_TOKEN` 환경 변수를 통한 인증이 필요합니다. ```bash 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 `가 기존 프로젝트와 ID 또는 슬러그로 일치하지 않으면 CLI는 ``를 새 프로젝트 이름으로 간주하고 확인 후 프로젝트를 생성합니다. `--yes`와 함께 사용하면 다음과 같이 하나의 비대화형 명령으로 새 프로젝트를 생성하고 배포합니다. ```bash mastra studio deploy --project "my-new-project" --yes ``` ### 인수 #### `[dir]` 프로젝트 디렉토리. 기본값은 현재 디렉터리입니다. ### 플래그 #### `--org` 조직 ID. 다음을 통해서도 설정할 수 있습니다.`MASTRA_ORG_ID` environment variable. #### `--project` 프로젝트 ID 또는 슬러그입니다. `MASTRA_PROJECT_ID` 환경 변수로도 설정할 수 있습니다. 일치하는 프로젝트가 없으면 이 값이 배포 시 생성할 새 프로젝트의 이름으로 사용됩니다. #### `-y, --yes` 확인 메시지 없이 기본값을 자동으로 수락합니다. #### `-c, --config` 프로젝트 구성 파일의 경로입니다. 기본값은`.mastra-project.json`. #### `--env-file` 배포와 함께 번들링할 env 파일의 경로입니다(프로젝트 디렉터리 기준). 이를 사용하여 서로 다른 환경 파일을 가리켜 동일한 프로젝트를 여러 환경에 배포합니다(예:`.env.staging`, `.env.production`). ```bash mastra studio deploy --env-file .env.staging --yes ``` #### `--skip-build` 빌드 단계를 건너뛰고 기존 배포`.mastra/output` directory. #### `--debug` 빌드 단계 중에 디버그 로그를 활성화합니다. ### CI/CD 사용 헤드리스 배포에서는 `MASTRA_API_TOKEN`, `MASTRA_ORG_ID`, `MASTRA_PROJECT_ID`를 환경 변수로 설정하세요. `MASTRA_API_TOKEN`이 설정되면 대화형 Prompt를 자동으로 건너뜁니다. ### `mastra studio deploy list` 최신 배포 상태 및 URL과 함께 모든 프로젝트를 나열합니다. ### `mastra studio deploy status` 특정 배포 상태를 표시합니다. ```bash mastra studio deploy status ``` #### `--watch, -w` 배포가 최종 상태에 도달할 때까지 상태 변경 사항을 폴링합니다. ### `mastra studio deploy logs` 특정 배포에 대한 로그를 표시합니다. ```bash mastra studio deploy logs ``` #### `--follow, -f` 실시간으로 로그를 스트리밍합니다. #### `--tail` 표시할 최근 로그 줄 수입니다. ### `mastra studio deploy suggestions` 실패한 Studio 배포에 대한 진단 결과 및 제안된 수정 사항을 표시합니다. ```bash mastra studio deploy suggestions [deploy-id] ``` `deploy-id`를 생략하면 이 명령은 연결된 프로젝트의 최신 배포를 사용합니다. 아직 진단이 없으면 명령이 진단을 시작하고 결과가 준비될 때까지 폴링합니다. 진단에서 문제가 발견된 경우에만 제안이 표시됩니다. ### `mastra studio projects` 현재 조직의 모든 프로젝트를 나열합니다. ### `mastra studio projects create` 대화형 Prompt를 통해 새 프로젝트를 생성합니다. 이 명령은 `--name` 플래그를 지원하지 않습니다. 비대화형으로 프로젝트를 생성하려면 대신 [`mastra studio deploy --project --yes`](#mastra-studio-deploy)를 사용하세요. 이 명령은 프로젝트를 생성하고 한 단계로 배포합니다. ## `mastra server deploy` > **정보:** `mastra server deploy`는 계속 작동하지만, Studio와 Server 명령을 분리하지 않고 단일 프로젝트를 여러 환경에 배포하는 [`mastra deploy`](#mastra-deploy)로 대체되었습니다. 새로운 설정에서는 `mastra deploy`를 사용해야 합니다. 프로젝트를 빌드하여 Mastra 플랫폼의 서버에 배포합니다. 동일한 플래그, 인수 및 결정 로직을 사용하는 [`mastra studio deploy`](#mastra-studio-deploy)와 동일하게 작동합니다. 배포 명령은 프로젝트의 `.env` 파일을 사용합니다. `MASTRA_PROJECT_ID`가 Observability용으로 프로비저닝된 프로젝트를 가리키면 새 프로젝트를 생성하는 대신 해당 프로젝트에 배포를 연결합니다. Observability 전용 프로젝트에 Server를 배포하면 플랫폼에서 해당 프로젝트가 Server 프로젝트로 변환됩니다. ```bash mastra server deploy [dir] ``` ### `mastra server deploy suggestions` 실패한 서버 배포에 대한 진단 결과 및 제안된 수정 사항을 표시합니다. ```bash mastra server deploy suggestions [deploy-id] ``` `deploy-id`를 생략하면 이 명령은 연결된 프로젝트의 최신 배포를 사용합니다. 아직 진단이 없으면 명령이 진단을 시작하고 결과가 준비될 때까지 폴링합니다. 진단에서 문제가 발견된 경우에만 제안이 표시됩니다. ## `mastra server pause` 연결된 프로젝트에 대해 실행 중인 서버 인스턴스를 일시 중지합니다. 조직 및 프로젝트 해결은 다음과 동일하게 작동합니다.[`mastra server deploy`](#mastra-server-deploy). ```bash mastra server pause ``` ### 플래그 #### `--org` 조직 ID. 다음을 통해서도 설정할 수 있습니다.`MASTRA_ORG_ID` environment variable. #### `--project` `MASTRA_PROJECT_ID`가 설정되지 않은 경우 사용할 프로젝트 ID 또는 슬러그입니다. 슬러그는 현재 조직의 프로젝트를 기준으로 확인됩니다. #### `-c, --config` 프로젝트 구성 파일의 경로입니다. 기본값은`.mastra-project.json`. 인스턴스가 실행되고 있지 않으면 실패합니다. ## `mastra server restart` 연결된 프로젝트에서 일시 중지되거나 중단된 서버 인스턴스를 다시 시작합니다. 플랫폼이 재시작을 수락한 후 CLI는 배포 ID를 확인하고(API 응답에서 확인하거나, 응답에 ID가 없으면 프로젝트 및 배포 메타데이터를 폴링하여 확인) 배포가 최종 상태에 도달할 때까지 [`mastra server deploy`](#mastra-server-deploy)와 같은 방식으로 빌드 및 배포 로그를 스트리밍합니다. ### 플래그 [`mastra server pause`](#mastra-server-pause)와 같은 플래그인 **`--org`**, **`--project`**, \*\*`-c` / `--config`\*\*를 동일한 기본값 및 동작으로 지원합니다. ```bash mastra server restart ``` 이 프로젝트에 대한 배포가 여전히 활성 상태이면 실패합니다(실행, 빌드, 배포 등). 이는 플랫폼 제한 사항이므로 다른 배포가 진행 중인 동안에는 다시 시작할 수 없습니다. ## `mastra server env` 연결된 서버 배포를 위한 환경 변수를 관리합니다. 조직 및 프로젝트 해결은 다음과 동일하게 작동합니다.[`mastra server deploy`](#mastra-server-deploy). 모든 하위 명령은 프로젝트 구성 파일 경로에 `-c` / `--config`를 지원합니다(기본값: `.mastra-project.json`). ### `mastra server env list` 연결된 프로젝트의 모든 환경 변수를 나열합니다. 값은 출력에서 ​​부분적으로 마스크됩니다. ### `mastra server env set` 환경 변수를 설정합니다. CLI는 현재 맵을 읽고 변경 사항을 적용하고 결과를 업로드합니다. ```bash mastra server env set ``` ### `mastra server env unset` 환경 변수를 제거합니다. ```bash mastra server env unset ``` ### `mastra server env import` 파일(예: `.env` 파일)에서 변수를 가져와 기존 맵에 병합합니다. 새 값은 서버에 이미 있는 키를 재정의합니다. ```bash mastra server env import ``` ### `mastra server env pull` 연결된 프로젝트에서 환경 변수를 다운로드하여 로컬 파일에 씁니다. 이는 반대이다.[`mastra server env import`](#mastra-server-env-import). ```bash mastra server env pull [file] ``` 인수를 지정하지 않으면 파일 기본값은 `.env`입니다. 안전하게 셸에서 소싱할 수 있도록 모든 값을 큰따옴표로 감싸고 이스케이프합니다. 유효한 셸 식별자가 아닌 키는 건너뜁니다. 비밀 값이 포함되므로 출력 파일은 제한적인 권한(`0600`)으로 생성됩니다. #### `--project` 프로젝트 ID 또는 슬러그입니다. `MASTRA_PROJECT_ID`가 설정되지 않은 경우 연결된 프로젝트를 재정의합니다. #### CI 사용법 지속적 통합 파이프라인에서는 `MASTRA_API_TOKEN`으로 인증하고 앱을 실행하기 전에 환경을 가져오세요. ```bash export MASTRA_API_TOKEN="..." mastra server env pull .env.production --project my-project ``` ## `mastra auth` Mastra 플랫폼 인증을 관리합니다. 자격 증명은 `~/.mastra/credentials.json`에 저장됩니다. 대화형 로그인 대신 `MASTRA_API_TOKEN` 환경 변수를 설정할 수도 있습니다. ### `mastra auth login` 로그인을 위해 브라우저를 열고 자격 증명을 로컬에 저장합니다. ### `mastra auth logout` 저장된 자격 증명을 제거합니다. 환경에 `MASTRA_API_TOKEN`이 계속 설정되어 있으면 CLI는 해당 토큰이 계속 사용된다고 경고합니다. ### `mastra auth whoami` 현재 사용자 이메일, 사용자 ID, 활성 조직을 표시합니다. ### `mastra auth orgs` 각 조직에서 귀하의 역할이 있는 모든 조직을 나열합니다. 현재 조직이 표시됩니다. #### `mastra auth orgs switch` 대화형 Prompt를 통해 활성 조직을 전환합니다. `MASTRA_API_TOKEN` 또는 `MASTRA_ORG_ID` 환경 변수가 설정된 경우에는 사용할 수 없습니다. ### `mastra auth tokens` 마지막으로 사용한 날짜와 함께 모든 API 토큰을 나열합니다. #### `mastra auth tokens create` 새 API 토큰을 만듭니다. 비밀은 한 번 표시되며 다시 검색할 수 없습니다. ```bash mastra auth tokens create ``` #### `mastra auth tokens revoke` API 토큰을 취소합니다. ```bash mastra auth tokens revoke ``` ## `mastra lint` `mastra lint` 명령은 Mastra 프로젝트의 구조와 코드를 검증합니다. 기본적으로 `mastra lint`는 소스 파일과 구성을 대상으로 프로젝트 검사를 실행합니다. 배포 전에 `.mastra/output`을 대상으로 번들 검사도 실행하려면 `--preflight`를 사용하세요. ```bash mastra lint --preflight ``` 그것은 받아들인다[common flags](#common-flags). ### 플래그 #### `--preflight` 빌드된 Mastra 출력에 대해 배포 실행 전 검사를 실행합니다. 통과하지 않는 한 프로젝트를 확인하기 전에 프로젝트를 빌드합니다.`--skip-build`. #### `--skip-build` 빌드 단계를 건너뛰고 기존 `.mastra/output` 디렉터리를 재사용합니다. 이 플래그는 `--preflight`가 설정된 경우에만 적용됩니다. #### `--env-file ` 배포 전 검증에 지정한 환경 파일을 사용합니다. 이 플래그는 `--preflight`가 설정된 경우에만 적용됩니다. #### `--strict` 경고를 오류로 처리합니다. #### `--json` 기계가 읽을 수 있는 JSON 출력을 내보냅니다. #### `--debug` 디버그 로그를 활성화합니다. ## `mastra scorers` `mastra scorers` 명령은 AI 생성 출력의 품질, 정확성 및 성능을 측정하는 평가 채점자 관리 기능을 제공합니다. 자세한 내용은 [채점자 개요](https://mastra.zisheng.pro/ko/docs/evals/overview)를 참조하세요. ### `add` 프로젝트에 새로운 득점자를 추가하세요. 대화형 Prompt를 사용할 수 있습니다: ```bash mastra scorers add ``` 또는 득점자 이름을 직접 입력하세요. ```bash mastra scorers add answer-relevancy ``` 올바른 ID를 확인하려면 [`list`](#list) 명령을 사용하세요. ### `list` 사용 가능한 모든 득점자 템플릿을 나열합니다. 해당 ID를 사용하세요.`add` command. ## `mastra create` 동일한 프로젝트 생성 흐름을 사용하여 독립형 Mastra 프로젝트를 생성합니다.[`create-mastra`](https://mastra.zisheng.pro/ko/reference/cli/create-mastra). **npm**: ```bash npx mastra@latest create ``` **pnpm**: ```bash pnpm dlx mastra@latest create ``` **Yarn**: ```bash yarn dlx mastra@latest create ``` **Bun**: ```bash bun x mastra@latest create ``` 프로젝트 이름과 `--llm`을 지정하면 대화형 설정 Prompt를 건너뜁니다. 임의의 템플릿에는 `--template [template]`을 사용하고, Provider가 없는 최소 스캐폴드에는 `--empty`를 사용하세요. 이 명령은 감지된 코딩 도우미에 Mastra Skill을 설치하고 해당하는 경우 Git을 초기화합니다. 제외하려면 `--no-skills` 또는 `--no-git`을 사용하세요. 모드 동작, 충돌, 검증 및 전체 플래그 설명은 [`create-mastra` 레퍼런스](https://mastra.zisheng.pro/ko/reference/cli/create-mastra)를 참조하세요. ## `mastra init` `mastra init` 명령은 기존 프로젝트에서 Mastra를 초기화합니다. 처음부터 새 프로젝트를 생성하지 않고 필요한 폴더와 구성을 스캐폴딩하려면 이 명령을 사용하세요. ### 플래그 이 명령은 다음과 같은 추가 플래그를 허용합니다. #### `--default` OpenAI를 사용하여 `src` 내부에 파일을 생성합니다. 또한 `src/mastra` 폴더를 예제 코드로 채웁니다. #### `--dir` Mastra 파일을 저장해야 하는 디렉터리입니다. 기본값은`src`. #### `--components` 추가할 구성 요소를 쉼표로 구분한 목록입니다. 각 구성 요소에 새 폴더가 생성됩니다. `"agents" | "tools" | "workflows" | "scorers"` 중에서 선택하세요. 기본값은 `['agents', 'tools', 'workflows']`입니다. #### `--llm` 기본 Model 공급자. 다음 중에서 선택하세요:`"openai" | "anthropic" | "groq" | "google" | "cerebras" | "mistral"`. #### `--llm-api-key` 선택한 Model 공급자의 API 키입니다. 환경 변수 파일(`.env`). #### `--example` 활성화되면 예제 코드가 구성 요소 목록에 기록됩니다(예: 예제 Agent 코드). #### `--no-example` 예제 코드를 포함하지 마세요. 사용할 때 유용합니다.`--default` flag. #### `--mcp` Mastra의 MCP 서버로 코드 편집기를 구성하십시오. 다음 중에서 선택하세요:`"cursor" | "cursor-global" | "windsurf" | "vscode"`. #### `--observability` Mastra 플랫폼에서 Observability을 활성화합니다. CLI는 기존 플랫폼 프로젝트를 선택하거나 새 프로젝트를 생성하라는 메시지를 표시합니다. 그런 다음 필요한 환경 변수를 작성하고 Observability 내보내기를 구성합니다. #### `--no-observability` Mastra Observability Prompt를 건너뜁니다. #### `--observability-project` Mastra Observability가 활성화된 경우 사용할 플랫폼 프로젝트 이름을 설정합니다. ## `mastra migrate` 데이터베이스 마이그레이션을 실행하여 스토리지 스키마를 업데이트합니다. 이 명령은 스토리지 스키마 변경 사항이 포함된 Mastra 버전을 업그레이드할 때 유용합니다. 이 명령은 프로젝트를 번들로 묶고 구성된 스토리지 백엔드에 연결합니다. 그런 다음 보류 중인 마이그레이션을 실행합니다. 현재 다음을 지원합니다. - **중복 스팬 마이그레이션**: 중복된 `(traceId, spanId)` 항목을 제거하고 데이터 무결성을 보장하기 위한 고유 제약 조건을 추가합니다. - **ClickHouse 레거시에서 vNext로의 스팬 마이그레이션**: 레거시 `mastra_ai_spans` 테이블의 과거 스팬을 vNext `mastra_span_events` 스키마로 복사합니다. Memory 제한을 초과하지 않도록 배치 단위로 실행됩니다. 자세한 내용은 [ClickHouse 스토리지 레퍼런스](https://mastra.zisheng.pro/ko/reference/storage/clickhouse)를 참조하세요. ```bash mastra migrate ``` 마이그레이션이 필요한 시점에 관한 자세한 내용은 [스토리지 마이그레이션 가이드](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/storage)를 참조하세요. 그것은 받아들인다[common flags](#common-flags). ## `mastra api` JSON 입력 및 JSON 출력을 사용하여 Mastra 런타임 서버를 호출합니다. 로컬 개발 서버, 배포된 Mastra 플랫폼 프로젝트, 자체 호스팅 Mastra 서버 또는 호스팅 Mastra Platform Observability API에 사용하세요. ```bash mastra api agent list mastra api agent run weather-agent '{"messages":"What is the weather in London?"}' mastra api tool execute get-weather '{"location":"San Francisco"}' mastra api trace list '{"page":0,"perPage":20}' ``` 명령의 예제를 보려면 `mastra api --help`를 사용하세요. ### 산출 성공 응답은 JSON으로 `stdout`에 기록됩니다. 단일 리소스 명령은 다음을 반환합니다. ```json { "data": {} } ``` 목록 명령은 `data` 배열과 페이지네이션 메타데이터를 반환합니다. ```json { "data": [], "page": { "total": 0, "page": 0, "perPage": 0, "hasMore": false } } ``` 오류는 JSON으로 `stderr`에 기록되며 0이 아닌 종료 코드를 반환합니다. ```json { "error": { "code": "SERVER_UNREACHABLE", "message": "Could not connect to target server", "details": {} } } ``` ### 목표 해상도 런타임 명령의 경우 명령은 다음 순서로 대상 서버를 확인합니다. 1. `--url `명시적인 원격 또는 자체 호스팅 서버의 경우. 2. `http://localhost:4111`현지인을 위해`mastra dev` server. 3. `.mastra-project.json`Mastra 플랫폼 프로젝트를 위해. 자동 플랫폼 인증은 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`를 대상으로 사용합니다. 두 명령 모두 다음 순서로 자격 증명을 결정합니다. 1. `--header`로 전달한 명시적 `Authorization` 및 `X-Mastra-Project-Id` 헤더. 2. 환경의 `MASTRA_PLATFORM_ACCESS_TOKEN` 및 `MASTRA_PROJECT_ID`. 3. 프로젝트 ID에 사용할 `.mastra-project.json`의 프로젝트 메타데이터. 4. 인증 대체 수단으로 사용할 Mastra CLI 로그인 토큰. 학습 명령은 `X-Mastra-Organization-Id`도 전송합니다. 이 값은 명시적 `--header`, 환경의 `MASTRA_ORGANIZATION_ID`, `.mastra-project.json` 순서로 결정됩니다. 기본 호스팅 Observability 대상이나 자격 증명을 재정의해야 할 때는 `--url`과 `--header`를 사용하세요. ### 플래그 #### `--url ` 특정 Mastra 서버 URL을 타겟팅합니다. ```bash mastra api --url https://example.com agent list ``` #### `--server-api-prefix ` 대상 서버의 API 경로 접두사를 설정합니다. 기본값은 `/api`입니다. 서버가 사용자 지정 접두사 아래에 마운트된 경우(예: `prefix: "/api/mastra-studio"`를 사용하는 `@mastra/fastify` `MastraServer`) `mastra studio`에서 `--server-api-prefix`를 사용하는 것과 같은 방식으로 사용하세요. 플래그를 전달하는 대신 `MASTRA_API_PREFIX` 환경 변수를 설정할 수도 있습니다. ```bash mastra api --url https://example.com --server-api-prefix /api/mastra-studio agent list ``` #### `--header <"Key: Value">` 사용자 정의 HTTP 헤더를 보냅니다. 여러 헤더를 보내려면 플래그를 반복하세요. ```bash mastra api --url https://example.com --header "Authorization: Bearer $TOKEN" agent list ``` #### `--timeout ` 요청 제한 시간을 밀리초 단위로 설정합니다. 기본값은 `30000`입니다. Workflow 실행 시작 및 재개 명령의 기본값은 `120000`입니다. #### `--pretty` JSON 출력을 예쁘게 인쇄합니다. 기본값은`false`. #### `--schema` JSON 입력을 허용하는 명령에 대한 CLI 지향 요청 스키마를 인쇄합니다. 스키마는 대상 서버의 경로 계약에서 나오며 명령 모양, 위치, 예제, 요청 스키마 및 응답 모양을 포함합니다. `--schema`JSON 입력을 허용하는 리프 명령에서 사용할 수 있습니다. 최상위 수준으로는 사용할 수 없습니다.`mastra api` flag. ```bash mastra api agent run --schema mastra api tool execute --schema ``` ### 입력 Model 입력을 허용하는 명령은 하나의 인라인 JSON 인수를 사용합니다. 파일 경로나 stdin을 전달하지 마세요. ```bash mastra api workflow run start data-pipeline '{"inputData":{"source":"s3://bucket/data.csv"}}' ``` 안정적인 ID에는 위치 인수를 사용하고 필터나 페이로드에는 JSON을 사용하세요. 쿼리 매개변수와 요청 본문이 모두 필요한 경로의 경우 하나의 JSON 객체를 전달합니다. CLI는 서버 경로 스키마에 따라 입력을 분할합니다. ```bash mastra api thread create '{"agentId":"weather-agent","resourceId":"user_123","threadId":"thread_abc123","title":"Support conversation"}' ``` 대상 경로가 페이지네이션을 지원하는 경우 목록 명령은 JSON 입력에서 `page`와 `perPage`를 허용합니다. ```bash mastra api score list '{"page":0,"perPage":50}' mastra api trace list '{"page":0,"perPage":20}' ``` 필터를 지원하는 경로는 동일한 JSON 입력에서 이를 허용합니다. 예를 들어 Observability 추적 목록은 페이지 매김 및 경로 지원 필터를 지원합니다. ```bash mastra api trace list '{"page":0,"perPage":20,"filters":{"spanType":"agent"}}' ``` ### 명령별 도움말 보기 각 `mastra api` 말단 명령의 도움말 출력에는 해당 명령에 관한 예제가 포함됩니다. 호출하려는 정확한 명령에 `--help`를 사용하세요. ```bash mastra api agent run --help mastra api tool execute --help mastra api memory current update --help mastra api workflow run resume --help ``` JSON 입력을 받는 명령에서 대상 서버가 반환하는 요청 구조를 확인하려면 `--schema`를 사용하세요. ```bash mastra api agent run --schema mastra api thread create --schema mastra api score create --schema ``` 일부 명령에는 중요한 런타임 요구 사항이 있습니다. 예를 들어 `mastra api memory current update`를 사용하려면 Memory 인스턴스에서 작업 Memory가 활성화되어 있어야 하며, `mastra api workflow run resume`은 일시 중단된 Workflow 실행에서만 작동합니다. ### 명령 #### `mastra api agent list` 대상 서버에 등록된 Agent를 나열합니다. 경로 지원 필터에 대한 선택적 JSON 입력을 전달합니다. ```bash mastra api agent list [input] ``` #### `mastra api agent get` 등록된 Agent 하나에 대한 메타데이터를 가져옵니다. ```bash mastra api agent get ``` #### `mastra api agent run` JSON 입력으로 Agent를 실행합니다. 명령 도움말을 사용하여 텍스트 Prompt, 채팅 메시지 및 Memory 스레드 옵션에 대한 예를 확인하세요. ```bash mastra api agent run ``` #### `mastra api workflow list` 대상 서버에 등록된 Workflow를 나열합니다. 경로 지원 필터에 대한 선택적 JSON 입력을 전달합니다. ```bash mastra api workflow list [input] ``` #### `mastra api workflow get` 등록된 하나의 Workflow에 대한 메타데이터를 가져옵니다. ```bash mastra api workflow get ``` #### `mastra api workflow run start` JSON 입력으로 Workflow 실행을 시작합니다. Workflow 시작 명령은 실행을 완료하는 데 더 오랜 시간이 걸릴 수 있으므로 대부분의 명령보다 긴 기본 제한 시간을 사용합니다. ```bash mastra api workflow run start ``` #### `mastra api workflow run list` Workflow에 대한 실행을 나열합니다. 경로 지원 필터 또는 페이지 매김을 위해 선택적 JSON 입력을 전달합니다. ```bash mastra api workflow run list [input] ``` #### `mastra api workflow run get` ID별로 실행되는 하나의 Workflow를 가져옵니다. ```bash mastra api workflow run get ``` #### `mastra api workflow run resume` JSON 입력을 사용하여 일시 중단된 Workflow 실행을 재개합니다. 실행은 일시 중지된 상태여야 합니다. ```bash mastra api workflow run resume ``` #### `mastra api workflow run cancel` Workflow 실행을 취소합니다. ```bash mastra api workflow run cancel ``` #### `mastra api tool list` 대상 서버에 등록된 Tool을 나열합니다. 경로 지원 필터에 대한 선택적 JSON 입력을 전달합니다. ```bash mastra api tool list [input] ``` #### `mastra api tool get` 하나의 Tool에 대한 메타데이터 및 스키마를 가져옵니다. ```bash mastra api tool get ``` #### `mastra api tool execute` JSON 입력으로 Tool을 실행합니다. 명시적인 `data` 객체를 전달하지 않으면 원시 Tool 입력이 경로의 `data` 필드로 래핑됩니다. ```bash mastra api tool execute ``` #### `mastra api mcp list` 대상 서버에 등록된 MCP(Model Context Protocol) 서버를 나열합니다. 경로 지원 필터에 대한 선택적 JSON 입력을 전달합니다. ```bash mastra api mcp list [input] ``` #### `mastra api mcp get` 하나의 MCP 서버에 대한 메타데이터를 가져옵니다. ```bash mastra api mcp get ``` #### `mastra api mcp tool list` MCP 서버에서 노출되는 Tool을 나열합니다. 경로 지원 필터에 대한 선택적 JSON 입력을 전달합니다. ```bash mastra api mcp tool list [input] ``` #### `mastra api mcp tool get` 하나의 MCP Tool에 대한 메타데이터 및 스키마를 가져옵니다. ```bash mastra api mcp tool get ``` #### `mastra api mcp tool execute` JSON 입력으로 MCP Tool을 실행합니다. 명시적인 `data` 객체를 전달하지 않으면 원시 Tool 입력이 경로의 `data` 필드로 래핑됩니다. ```bash mastra api mcp tool execute ``` #### `mastra api thread list` Memory 스레드를 나열합니다. 경로 지원 필터에 대한 선택적 JSON 입력을 전달합니다. ```bash mastra api thread list [input] ``` #### `mastra api thread get` ID별로 하나의 Memory 스레드를 가져옵니다. ```bash mastra api thread get ``` #### `mastra api thread create` Memory 스레드를 생성합니다. 단일 JSON 입력 객체를 전달합니다. 서버 경로에서 필요한 경우 CLI는 `agentId` 같은 필드를 쿼리 매개변수로 분리합니다. ```bash mastra api thread create ``` #### `mastra api thread update` Memory 스레드를 업데이트합니다. `agentId`, `resourceId`, `title`, `metadata` 같은 필드가 포함된 단일 JSON 입력 객체를 전달합니다. ```bash mastra api thread update ``` #### `mastra api thread delete` Memory 스레드를 삭제합니다. 경로에 필요한 `agentId` 및 `resourceId` 같은 쿼리 매개변수를 JSON 입력으로 전달합니다. ```bash mastra api thread delete ``` #### `mastra api thread messages` Memory 스레드에 대한 메시지를 나열합니다. 경로 지원 필터 또는 페이지 매김을 위해 선택적 JSON 입력을 전달합니다. ```bash mastra api thread messages [input] ``` #### `mastra api memory search` 장기 Memory를 검색합니다. `agentId`, `resourceId`, `searchQuery` 같은 필수 필드를 확인하려면 `--help` 또는 `--schema`를 사용하세요. ```bash mastra api memory search ``` #### `mastra api memory current get` 스레드의 현재 작업 Memory를 읽습니다. ```bash mastra api memory current get ``` #### `mastra api memory current update` 스레드의 현재 작업 Memory를 업데이트합니다. Memory 인스턴스에 대해 작업 Memory를 활성화해야 합니다. ```bash mastra api memory current update ``` #### `mastra api memory status` Agent 및 선택적 스레드 또는 리소스 컨텍스트에 대한 Memory 상태를 가져옵니다. ```bash mastra api memory status ``` #### `mastra api trace list` Observability 추적을 나열합니다. 경로 지원 필터 또는 페이지 매김을 위해 선택적 JSON 입력을 전달합니다. ```bash mastra api trace list [input] mastra api trace list '{"page":0,"perPage":20}' mastra api trace list '{"page":0,"perPage":20}' --verbose ``` `trace list`는 기본적으로 경량 루트 스팬 레코드를 반환하므로 대규모 입력, 출력, 속성 또는 메타데이터 페이로드를 가져오지 않고 Trace를 페이지 단위로 탐색할 수 있습니다. 전체 루트 스팬 레코드를 가져오려면 `--verbose`를 전달하세요. #### `mastra api trace get` 전체 스팬 입력, 출력, 속성 또는 메타데이터 페이로드를 가져오지 않고 하나의 Observability Trace에 대한 간략한 타임라인을 가져옵니다. 전체 Trace 페이로드를 가져오려면 `--verbose`를 전달하세요. ```bash mastra api trace get mastra api trace get --verbose ``` #### `mastra api trace span` Observability Trace에서 하나의 전체 스팬을 가져옵니다. 검사할 스팬을 알고 있다면 `trace get`을 사용하세요. ```bash mastra api trace span ``` #### `mastra api log list` Observability 로그를 나열합니다. 경로 지원 필터 또는 페이지 매김을 위해 선택적 JSON 입력을 전달합니다. ```bash mastra api log list [input] ``` #### `mastra api metric aggregate` 단일 집계 측정항목 값을 가져옵니다. ```bash mastra api metric aggregate '{"name":["latency_ms"],"aggregation":"avg"}' ``` #### `mastra api metric breakdown` 라벨이나 필드별로 그룹화된 측정항목 값을 가져옵니다. ```bash mastra api metric breakdown '{"name":["latency_ms"],"aggregation":"avg","groupBy":["model"],"limit":10}' ``` #### `mastra api metric timeseries` 시간 경과에 따른 측정항목 값을 가져옵니다. ```bash mastra api metric timeseries '{"name":["latency_ms"],"aggregation":"avg","interval":"1h"}' ``` #### `mastra api metric percentiles` 시간 경과에 따른 메트릭의 백분위수 값을 가져옵니다. 백분위수 값에는 `0`부터 `1`까지의 소수를 사용합니다. ```bash mastra api metric percentiles '{"name":"latency_ms","percentiles":[0.5,0.95,0.99],"interval":"1h"}' ``` #### `mastra api metric names` 검색된 메트릭 이름을 나열합니다. 접두사 검색 및 제한을 위해 선택적 JSON 입력을 전달합니다. ```bash mastra api metric names '{"prefix":"lat","limit":10}' ``` #### `mastra api metric label-keys` 측정항목의 라벨 키를 나열합니다. ```bash mastra api metric label-keys '{"metricName":"latency_ms"}' ``` #### `mastra api metric label-values` 측정항목 라벨 키의 라벨 값을 나열합니다. 선택적 접두사 및 제한 값을 전달하여 결과 범위를 좁힙니다. ```bash mastra api metric label-values '{"metricName":"latency_ms","labelKey":"model","prefix":"g","limit":10}' ``` #### Observability`curl` 플랫폼 액세스 토큰 및 프로젝트 ID를 사용하여 호스팅된 관측 가능성 API를 직접 호출할 수 있습니다. ```bash curl -sS "https://observability.mastra.ai/api/observability/traces?page=0&perPage=20" \ -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \ -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" | jq ``` 가벼운 추적 타임라인을 얻으세요: ```bash curl -sS "https://observability.mastra.ai/api/observability/traces//light" \ -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \ -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" | jq ``` 특정 범위를 가져옵니다. ```bash curl -sS "https://observability.mastra.ai/api/observability/traces//spans/" \ -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \ -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" | jq ``` #### `mastra api score create` Observability 점수를 생성합니다. 입력은 서버 점수 본문 모양을 사용합니다. 그것을 검사`--schema`. ```bash mastra api score create ``` #### `mastra api score list` Observability 점수를 나열합니다. 실행 ID 또는 페이지 매김과 같은 필터에 대한 선택적 JSON 입력을 전달합니다. ```bash mastra api score list [input] ``` #### `mastra api score get` ID별로 하나의 Observability 점수를 가져옵니다. ```bash mastra api score get ``` #### `mastra api dataset list` 데이터세트를 나열합니다. 경로 지원 필터 또는 페이지 매김을 위해 선택적 JSON 입력을 전달합니다. ```bash mastra api dataset list [input] ``` #### `mastra api dataset get` ID별로 하나의 데이터 세트를 가져옵니다. ```bash mastra api dataset get ``` #### `mastra api dataset create` JSON 입력으로 데이터세트를 만듭니다. ```bash mastra api dataset create ``` #### `mastra api dataset items` 데이터 세트의 항목을 나열합니다. 경로 지원 필터 또는 페이지 매김을 위해 선택적 JSON 입력을 전달합니다. ```bash mastra api dataset items [input] ``` #### `mastra api experiment list` 데이터 세트에 대한 실험을 나열합니다. 경로 지원 필터 또는 페이지 매김을 위해 선택적 JSON 입력을 전달합니다. ```bash mastra api experiment list [input] ``` #### `mastra api experiment get` ID별로 하나의 실험을 가져옵니다. ```bash mastra api experiment get ``` #### `mastra api experiment run` JSON 입력을 사용하여 데이터 세트에 대한 실험을 시작합니다. ```bash mastra api experiment run ``` #### `mastra api experiment results` 실험 결과를 나열합니다. 경로 지원 필터 또는 페이지 매김을 위해 선택적 JSON 입력을 전달합니다. ```bash mastra api experiment results [input] ``` #### `mastra api learning entities` 엔터티별로 사용할 수 있는 추적 신호를 포함하여 Trace Intelligence 출력과 함께 엔터티(Agent)를 나열합니다. Trace Intelligence 비공개 베타에 등록해야 합니다. ```bash mastra api learning entities '{"entityType":"agent"}' ``` #### `mastra api learning snapshots` 엔터티의 분석 스냅샷과 순서가 지정된 쉼표 구분 Trace 신호 목록을 나열합니다. 이후 명령에는 이 목록의 `snapshotId`가 필요합니다. ```bash mastra api learning snapshots '{"entityType":"agent","signalNames":"goal,outcome,behavior,sentiment","limit":10}' ``` #### `mastra api learning flow` 하나의 스냅샷에 대한 교차 신호 테마 흐름을 가져옵니다. 개수가 고유한 추적인 Sankey 스타일 보기의 단계 및 링크입니다. ```bash mastra api learning flow '{"entityType":"agent","signalNames":"goal,outcome","snapshotId":""}' ``` #### `mastra api learning paths` 하나의 스냅샷에서 정렬된 Trace 신호 전체에 대한 Trace별 테마 할당을 가져옵니다. `limit`과 `offset`으로 페이지네이션합니다. ```bash mastra api learning paths '{"entityType":"agent","signalNames":"goal,outcome","snapshotId":"","limit":100}' ``` #### `mastra api learning theme list` 하나의 스냅샷에 하나의 추적 신호에 대한 테마를 나열합니다. ```bash mastra api learning theme list '{"entityType":"agent","signalName":"goal","snapshotId":""}' ``` #### `mastra api learning theme get` 숫자 테마 ID로 하나의 스냅샷에서 하나의 테마를 가져옵니다. ```bash mastra api learning theme get '{"entityType":"agent","signalName":"goal","snapshotId":""}' ``` #### `mastra api learning theme examples` 하나의 스냅샷에서 특정 테마의 Trace 예제를 나열합니다. `limit`과 `offset`으로 페이지네이션합니다. ```bash mastra api learning theme examples '{"entityType":"agent","signalName":"goal","snapshotId":"","limit":10}' ``` #### `mastra api learning theme history` 분할 및 병합 관계를 포함하여 스냅샷 전체에서 하나의 지속 가능한 테마에 대한 수명 주기 기록을 가져옵니다. 아니오`snapshotId`. ```bash mastra api learning theme history '{"entityType":"agent","signalName":"goal"}' ``` #### `mastra api learning noise get` 하나의 스냅샷에서 하나의 추적 신호에 대한 클러스터되지 않은(노이즈) 버킷을 가져옵니다. ```bash mastra api learning noise get '{"entityType":"agent","signalName":"goal","snapshotId":""}' ``` #### `mastra api learning noise examples` 하나의 스냅샷에서 노이즈 버킷의 Trace 예제를 나열합니다. `limit`과 `offset`으로 페이지네이션합니다. ```bash mastra api learning noise examples '{"entityType":"agent","signalName":"goal","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는 OS, Mastra 버전, Node.js 버전 등 프로젝트에 관한 익명 정보를 수집합니다. 수집되는 정보를 확인하려면 [소스 코드](https://github.com/mastra-ai/mastra/blob/main/packages/cli/src/analytics/index.ts)를 참조하세요. `mastra dev` 또는 `mastra start`로 시작한 서버에서 Observability 메트릭이 활성화된 경우, Mastra는 시작 시 익명으로 집계된 Model 사용량도 전송합니다. 여기에는 Provider 및 Model별 입력·출력 토큰 수와 명령(`dev` 또는 `start`) 및 `NODE_ENV`가 포함됩니다. Prompt, 응답 또는 기타 메시지 콘텐츠는 전송되지 않습니다. 수집되는 정보를 확인하려면 [소스 코드](https://github.com/mastra-ai/mastra/blob/main/packages/core/src/telemetry/usage-telemetry.ts)를 참조하세요. 서버가 시작될 때 Mastra는 등록된 Agent, Agent 컨트롤러, Workflow, Tool, 프로세서, 벡터 저장소, 채점자, Workspace, MCP 서버, 게이트웨이 및 채널의 수와 Memory, 음성, 편집기 및 Observability 사용 여부, 대략적인 스토리지 백엔드 범주를 포함한 익명의 프로젝트 기능 스냅샷도 전송합니다. 이름이나 식별자는 전송하지 않습니다. 수집되는 정보를 확인하려면 [소스 코드](https://github.com/mastra-ai/mastra/blob/main/packages/core/src/telemetry/feature-telemetry.ts)를 참조하세요. 환경 변수를 설정하여 모든 CLI 및 사용량 분석을 옵트아웃할 수 있습니다. ```bash MASTRA_TELEMETRY_DISABLED=1 ``` 다른 것을 사용하는 동안에도 이를 설정할 수 있습니다.`mastra` commands: ```bash MASTRA_TELEMETRY_DISABLED=1 mastra dev ```