> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt # Commandes CLI Vous pouvez utiliser l’interface en ligne de commande (CLI) fournie par Mastra pour développer, compiler et démarrer votre projet Mastra. ## `mastra dev` Démarre un serveur qui expose [Studio](https://mastra.zisheng.pro/fr/docs/studio/overview) ainsi que des endpoints REST pour vos agents, tools et workflows. Une fois `mastra dev` en cours d’exécution, consultez pour obtenir un aperçu de tous les endpoints disponibles. Vous pouvez également [configurer le serveur](https://mastra.zisheng.pro/fr/reference/configuration). ### Options La commande accepte les [options communes](#common-flags) ainsi que les options supplémentaires suivantes : #### `--https` Active la prise en charge locale de HTTPS. [En savoir plus](https://mastra.zisheng.pro/fr/reference/configuration). #### `--inspect` Démarre le serveur de développement en mode d’inspection, utile pour le débogage. Vous pouvez spécifier un hôte et un port personnalisés (par exemple, `--inspect=0.0.0.0:9229` pour Docker). Cette option ne peut pas être utilisée avec `--inspect-brk`. #### `--inspect-brk` Démarre le serveur de développement en mode d’inspection et interrompt l’exécution au début du script. Vous pouvez spécifier un hôte et un port personnalisés (par exemple, `--inspect-brk=0.0.0.0:9229`). Cette option ne peut pas être utilisée avec `--inspect`. #### `--custom-args` Liste d’arguments personnalisés, séparés par des virgules, à transmettre au processus Node.js, par exemple `--require=newrelic` ou `--experimental-transform-types`. #### `--request-context-presets` Chemin vers un fichier JSON contenant des préréglages de [contexte de requête](https://mastra.zisheng.pro/fr/docs/server/request-context). Lorsqu’il est fourni, une liste déroulante s’affiche dans l’éditeur de contexte de requête de Studio afin de passer rapidement d’une configuration prédéfinie à une autre. ```bash mastra dev --request-context-presets ./presets.json ``` Le fichier doit être un objet JSON dont chaque clé est le nom d’un préréglage et chaque valeur un objet : ```json { "development": { "userId": "dev-user", "env": "development" }, "production": { "userId": "prod-user", "env": "production" } } ``` ### Configuration Vous pouvez définir des variables d’environnement pour modifier le comportement de `mastra dev`. #### Ignorer la vérification des dépendances homologues Définissez `MASTRA_SKIP_PEERDEP_CHECK=1` pour ignorer, au démarrage, la vérification des incompatibilités de versions des dépendances homologues : ```bash MASTRA_SKIP_PEERDEP_CHECK=1 mastra dev ``` C’est utile lors du développement dans un monorepo, lorsque les versions des dépendances homologues ont pu être augmentées alors que les packages ne sont pas encore publiés. #### Désactiver le cache de compilation Définissez `MASTRA_DEV_NO_CACHE=1` pour forcer une recompilation complète au lieu d’utiliser les ressources mises en cache dans `.mastra/` : ```bash MASTRA_DEV_NO_CACHE=1 mastra dev ``` C’est utile lorsque vous déboguez des plugins de bundler ou soupçonnez que la sortie n’est plus à jour. #### Limiter le parallélisme `MASTRA_CONCURRENCY` limite le nombre d’opérations coûteuses exécutées en parallèle (principalement les étapes de compilation et d’évaluation). Par exemple : ```bash MASTRA_CONCURRENCY=4 mastra dev ``` Ne la définissez pas pour laisser la CLI choisir une valeur par défaut adaptée à la machine. #### Endpoints personnalisés pour les providers Lorsque vous utilisez des providers pris en charge par le SDK Vercel AI, vous pouvez rediriger les requêtes via des proxys ou des passerelles internes en définissant une URL de base. Pour OpenAI : ```bash OPENAI_API_KEY= \ OPENAI_BASE_URL=https://openrouter.example/v1 \ mastra dev ``` Pour Anthropic : ```bash ANTHROPIC_API_KEY= \ ANTHROPIC_BASE_URL=https://anthropic.internal \ mastra dev ``` Ces valeurs sont transmises au routeur de modèles Mastra et fonctionnent avec toute sélection de modèle `"openai/..."` ou `"anthropic/..."`. ## `mastra factory dev` Démarre un serveur de développement pour développer [Agent Builder](https://agent-builder.mastra.ai/). Il utilise le même environnement d’exécution de développement et les mêmes options que [`mastra dev`](#mastra-dev), et écrit dans le même répertoire `.mastra/output`. ```bash npx mastra factory dev ``` Les deux commandes partagent le même verrou de développement. `mastra dev` et `mastra factory dev` ne peuvent donc pas s’exécuter simultanément dans un même projet. Si l’une est déjà en cours d’exécution, l’autre s’arrête avec une erreur signalant un serveur de développement en double. Utilisez `mastra factory dev` lorsque vous développez des fonctionnalités d’Agent Builder. Cette commande accepte les mêmes options que [`mastra dev`](#mastra-dev), notamment `--https`, `--inspect`, `--inspect-brk`, `--custom-args` et `--request-context-presets`. ## `mastra build` La commande `mastra build` regroupe votre projet Mastra dans un serveur Hono prêt pour la production. [Hono](https://hono.dev/) est un framework web léger et fortement typé qui simplifie le déploiement d’agents Mastra sous forme d’endpoints HTTP avec prise en charge des middlewares. En interne, le serveur Rollup de Mastra localise le fichier d’entrée de votre projet Mastra et le regroupe dans un serveur Hono prêt pour la production. Au cours de cette opération, il élimine le code inutilisé et génère des source maps pour le débogage. La sortie dans `.mastra` peut être déployée sur n’importe quel serveur cloud à l’aide de [`mastra start`](#mastra-start). Si vous déployez sur une [plateforme serverless](https://mastra.zisheng.pro/fr/docs/deployment/cloud-providers), vous devez installer le deployer approprié afin d’obtenir la sortie adéquate dans `.mastra`. Elle accepte les [options communes](#common-flags). ### Options #### `--studio` Inclut l’interface de Studio dans la compilation. ### Configuration Vous pouvez définir des variables d’environnement pour modifier le comportement de `mastra build`. #### Ignorer la vérification des dépendances homologues Définissez `MASTRA_SKIP_PEERDEP_CHECK=1` pour ignorer la vérification des incompatibilités de versions des dépendances homologues : ```bash MASTRA_SKIP_PEERDEP_CHECK=1 mastra build ``` #### Limiter le parallélisme Dans un environnement de CI ou disposant de ressources limitées, vous pouvez limiter le nombre de tâches coûteuses exécutées simultanément en définissant `MASTRA_CONCURRENCY`. ```bash MASTRA_CONCURRENCY=2 mastra build ``` ## `mastra start` > **Info:** Vous devez exécuter `mastra build` avant d’utiliser `mastra start`. Démarre un serveur local qui sert votre application Mastra compilée en mode production. Par défaut, le [traçage OTEL](https://mastra.zisheng.pro/fr/docs/observability/tracing/overview) est activé. ### Options La commande accepte les [options communes](#common-flags) ainsi que les options supplémentaires suivantes : #### `--dir` Chemin vers le répertoire de sortie de votre application Mastra compilée. La valeur par défaut est `.mastra/output`. #### `--custom-args` Liste d’arguments personnalisés, séparés par des virgules, à transmettre au processus Node.js, par exemple `--require=newrelic` ou `--experimental-transform-types`. ## `mastra worker build` Regroupe votre application Mastra en vue d’un déploiement en tant que worker. Produit la même sortie que `mastra build` : un répertoire `.mastra/output/` autonome. ```bash mastra worker build [options] ``` ### Options #### `--dir` Chemin vers le répertoire source de Mastra. La valeur par défaut est `src/mastra`. #### `--root` Répertoire racine du projet. La valeur par défaut est le répertoire actuel. #### `--tools` Liste, séparée par des virgules, des chemins de tools à inclure dans le bundle. #### `--output-dir` Répertoire de sortie personnalisé. La valeur par défaut est `.mastra/output`. #### `--debug` Active la journalisation de débogage pendant la compilation. ## `mastra experiment build` Compile un worker compagnon autonome qui exécute des expériences sans exposer de serveur HTTP. Le worker charge votre instance `Mastra` exportée et accepte sur l’entrée standard des messages de protocole JSON délimités par des sauts de ligne (NDJSON) et versionnés. Il écrit les événements du protocole sur la sortie standard. ```bash mastra experiment build [options] ``` Par défaut, la commande écrit le worker dans `.mastra/experiment-worker`. Le répertoire contient le point d’entrée exécutable, les dépendances de production et `experiment-worker-manifest.json`. Réservez la sortie standard aux seules données du protocole. Les diagnostics du worker sont écrits sur la sortie d’erreur standard. ### Contrat de l’artefact `experiment-worker-manifest.json` identifie l’artefact comme `mastra-experiment-worker` version `1` et fournit : - La version de la CLI, la date de création et l’ID de compilation unique intégrés à l’exécutable. - Les versions prises en charge du protocole et de la canonisation des datasets. - L’exécutable, les arguments et le répertoire de travail nécessaires pour lancer le worker. - Les chemins du manifeste de dépendances et du fichier de verrouillage généré. - Une empreinte SHA-256 triée pour chaque fichier de l’artefact. - Une empreinte SHA-256 du contenu dérivée de ces chemins de fichiers et de leurs empreintes. L’empreinte du contenu exclut `experiment-worker-manifest.json` afin d’éviter une empreinte autoréférentielle. Incluez le manifeste dans le package avec le reste du répertoire. Utilisez l’empreinte d’un package externe lorsque le manifeste lui-même doit être attesté. ### Contrat du protocole Le worker implémente la version `1`, figée, du protocole du worker compagnon d’expérimentation. Il lit sur l’entrée standard des trames NDJSON UTF-8 strictes et exige que chacune d’elles, y compris la dernière, se termine par un saut de ligne. Les trames de plus de 1 Mio, mal formées ou tronquées, les versions de protocole ou de canonisation non prises en charge et les messages qui ne correspondent pas à la corrélation de l’expérience active sont rejetés comme des échecs de protocole. Une requête d’exécution doit correspondre à l’ID de compilation intégré à l’artefact et inclure le nombre ordonné d’éléments du dataset ainsi que l’attestation SHA-256. Le worker émet des numéros de séquence contigus à partir de `0`, des signaux de vie déclenchés par minuterie, les événements attendus du cycle de vie de l’expérience et exactement un événement terminal. Une annulation doit correspondre à la version active du protocole, à l’ID de l’expérience, à l’ID de la tâche, à la tentative et à la clé d’idempotence. Les codes de sortie du protocole sont les suivants : | Code | Signification | | ---- | ---------------------------------------------------- | | `0` | Terminé | | `10` | Terminé avec des erreurs sur certains éléments | | `20` | Échec fatal | | `21` | Échec pouvant faire l’objet d’une nouvelle tentative | | `30` | Annulé | | `31` | Délai dépassé | | `70` | Échec du protocole | ### Traitement des champs des paquets Le worker transmet à `runExperiment` l’identité de la cible, les éléments ordonnés du dataset en ligne, les ID des scorers, la concurrence, le délai d’expiration, les métadonnées de l’expérience, le contexte de requête, les mocks de tools et l’annulation. Les versions des scorers et la provenance de l’artefact sont conservées dans les métadonnées de l’expérience. La provenance du code des scorers est contrôlée lors de l’admission de l’artefact plutôt que par une recherche des scorers à l’exécution. La version `1` refuse de manière déterministe les tools non déclarés. Les listes d’autorisation réseau non vides et les références à des secrets sont rejetées avec un échec de stratégie, car l’application des règles réseau et la matérialisation des secrets relèvent de la sandbox du processus. Les champs de source et de trajectoire attendue des éléments du dataset sont conservés comme métadonnées des éléments lors de leur transmission à `runExperiment`. ### Options #### `--dir` Chemin vers le répertoire source de Mastra. La valeur par défaut est `src/mastra`. #### `--root` Répertoire racine du projet. La valeur par défaut est le répertoire actuel. #### `--output-dir` Répertoire d’artefacts personnalisé. Les chemins relatifs sont résolus à partir de la racine du projet. La valeur par défaut est `.mastra/experiment-worker`. #### `--debug` Active la journalisation de débogage pendant la compilation. ## `mastra worker start` > **Info:** Vous devez exécuter `mastra worker build` ou `mastra build` avant d’utiliser `mastra worker start`. Démarre un processus worker à partir d’un bundle précédemment compilé. L’argument facultatif `name` définit `MASTRA_WORKERS` dans le processus créé et détermine ainsi quel worker démarre. ```bash mastra worker start [name] [options] ``` ### Options #### `--dir` Chemin vers le répertoire de sortie de la compilation. La valeur par défaut est `.mastra/output`. #### `--env` Chemin vers le fichier d’environnement. La valeur par défaut est `.env.production`, avec repli sur `.env`. ### Exemples ```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 ``` Consultez [Workers](https://mastra.zisheng.pro/fr/docs/deployment/workers) pour connaître les topologies de déploiement et leur configuration. ## `mastra studio` Démarre [Studio](https://mastra.zisheng.pro/fr/docs/studio/overview) sous forme de serveur statique. Après le démarrage, vous pouvez saisir l’URL de votre instance Mastra (par exemple `http://localhost:4111`) pour connecter Studio à votre backend Mastra. La configuration recherche les fichiers `.env` et `.env.production` dans le répertoire de travail actuel. ### Options La commande accepte les [options communes](#common-flags) ainsi que les options supplémentaires suivantes : #### `--port` Port sur lequel exécuter Studio. La valeur par défaut est `3000`. #### `--server-host` Hôte du serveur API Mastra auquel se connecter. La valeur par défaut est `localhost`. #### `--server-port` Port du serveur API Mastra auquel se connecter. La valeur par défaut est `4111`. #### `--server-protocol` Protocole du serveur API Mastra auquel se connecter. La valeur par défaut est `http`. #### `--server-api-prefix` Préfixe des routes API du serveur API Mastra. La valeur par défaut est `/api`. #### `--request-context-presets` Chemin vers un fichier JSON contenant des préréglages de [contexte de requête](https://mastra.zisheng.pro/fr/docs/server/request-context). Fonctionne de la même manière que [l’option `mastra dev`](#--request-context-presets). ```bash mastra studio --request-context-presets ./presets.json ``` ## `mastra deploy` Compile et déploie votre projet dans l’environnement de la plateforme Mastra sélectionné par `--env`. Cette commande est recommandée pour tous les nouveaux déploiements et remplace à la fois [`mastra studio deploy`](#mastra-studio-deploy) et [`mastra server deploy`](#mastra-server-deploy), qui continuent de fonctionner mais ne doivent plus être utilisés pour les nouvelles configurations. Nécessite une authentification via [`mastra auth login`](#mastra-auth-login) ou la variable d’environnement `MASTRA_API_TOKEN`. ```bash mastra deploy mastra deploy --env staging mastra deploy --env production --region eu ``` La commande exécute `mastra build` et compresse la sortie avant de l’importer dans l’environnement sélectionné. Elle vérifie ensuite régulièrement l’état du déploiement tout en diffusant les journaux de compilation, jusqu’à ce que le déploiement atteigne un état terminal. L’organisation, le projet et l’environnement sont déterminés dans cet ordre à partir des éléments suivants : variables d’environnement (`MASTRA_ORG_ID`, `MASTRA_PROJECT_ID`), options de la CLI (`--org`, `--project`, `--env`), fichier de configuration `.mastra-project.json`, organisation actuelle issue des identifiants, puis invite interactive. Lors du premier déploiement, la CLI enregistre dans `.mastra-project.json` les ID de l’organisation et du projet ainsi déterminés, afin que les déploiements suivants n’affichent plus ces invites. Si le projet n’existe pas encore, la CLI le crée, après confirmation, à partir de `package.json`, en utilisant son champ `name`. Si l’environnement cible n’existe pas, la CLI le crée après confirmation (avec `type: staging` par défaut pour toute valeur autre que `production`). Associé à `--yes`, ce comportement permet de tout créer et déployer en une seule commande non interactive : ```bash mastra deploy --env staging --yes ``` Lorsque `--env ` est défini contrairement à `--env-file`, la CLI sélectionne automatiquement `.env.` dans le répertoire du projet s’il existe (par exemple `.env.staging`). La valeur `` est validée par rapport à une liste d’autorisation stricte avant d’être interpolée dans un chemin de fichier. ### Arguments #### `[dir]` Répertoire du projet. La valeur par défaut est le répertoire actuel. ### Options #### `--env` Nom de l’environnement cible. La valeur par défaut est `production`. Sélectionne automatiquement `.env.` dans le répertoire du projet lorsque `--env-file` n’est pas défini. Si l’environnement n’existe pas, la CLI le crée après confirmation. #### `--org` ID de l’organisation. Peut également être défini à l’aide de la variable d’environnement `MASTRA_ORG_ID`. #### `--project` ID, slug ou nom du projet. Peut également être défini à l’aide de la variable d’environnement `MASTRA_PROJECT_ID`. Si aucun projet ne correspond, la valeur sert de nom au nouveau projet créé lors du déploiement. #### `-y, --yes` Accepte automatiquement les valeurs par défaut sans demander de confirmation, y compris pour la création de projets et d’environnements. #### `-c, --config` Chemin vers le fichier de configuration du projet. La valeur par défaut est `.mastra-project.json`. #### `--env-file` Chemin vers le fichier d’environnement à inclure dans le déploiement (relatif au répertoire du projet). Lorsqu’elle est définie, cette option désactive la sélection automatique de `.env.` fondée sur `--env`. ```bash mastra deploy --env staging --env-file .env.staging.local ``` #### `--region` Région d’un environnement nouvellement créé (par exemple `eu`). S’applique uniquement lorsque la CLI crée l’environnement. #### `--skip-build` Ignore l’étape de compilation et déploie le répertoire `.mastra/output` existant. La CLI émet un avertissement si la compilation existante n’est plus à jour par rapport au code source actuel. #### `--skip-preflight` Ignore la validation de la sortie compilée avant son importation. #### `--debug` Active les journaux de débogage pendant l’étape de compilation. ### Utilisation en CI/CD Définissez `MASTRA_API_TOKEN`, `MASTRA_ORG_ID` et `MASTRA_PROJECT_ID` comme variables d’environnement pour les déploiements sans interface. Les invites interactives sont automatiquement ignorées lorsque `MASTRA_API_TOKEN` est défini. Ajoutez `--yes` pour accepter automatiquement la création de l’environnement. ```bash export MASTRA_API_TOKEN="..." export MASTRA_ORG_ID="..." export MASTRA_PROJECT_ID="..." mastra deploy --env staging --yes ``` ## `mastra env` Gère les environnements sur la plateforme Mastra. Les environnements sont des cibles de déploiement (par exemple `production`, `staging`, `preview-42`) qui appartiennent à un projet. L’organisation actuelle est déterminée à partir des identifiants enregistrés. Chaque sous-commande détermine son projet dans un ordre fixe. Elle vérifie d’abord la variable d’environnement `MASTRA_PROJECT_ID` et l’option `--project `. Elle lit ensuite, dans le répertoire actuel, le fichier `.mastra-project.json` écrit par [`mastra deploy`](#mastra-deploy). Exécutez la commande depuis le répertoire de votre projet pour ne jamais avoir à préciser le projet. ### `mastra env list` Répertorie les environnements d’un projet. Chaque environnement affiche son déploiement le plus récent (avec un indicateur `(active)` lorsqu’il reçoit du trafic) ainsi que les noms des variables d’environnement injectées par des ressources gérées, telles que les bases de données associées. ```bash mastra env list ``` #### `--json` Produit du JSON lisible par une machine. Seules les métadonnées non sensibles (ID, nom, slug, type, région, branche, URL, noms des variables d’environnement gérées et état du dernier déploiement) sont incluses, afin que la sortie puisse être enregistrée sans risque dans les journaux de CI. ### `mastra env create` Crée un environnement pour un projet. ```bash mastra env create staging --type staging --region eu ``` #### `-t, --type` Type d’environnement. L’une des valeurs suivantes : `production`, `staging` ou `preview`. La valeur par défaut est `staging`. #### `-r, --region` Région de l’environnement (par exemple `eu`). #### `--json` Produit du JSON lisible par une machine. Les champs sensibles sont omis, comme avec [`mastra env list`](#mastra-env-list). ### `mastra env delete` Supprime un environnement. ```bash mastra env delete ``` `` peut être le nom, le slug ou l’ID d’un environnement. La CLI demande une confirmation, sauf si `--yes` est fourni. #### `-y, --yes` Ignore la demande de confirmation. ### `mastra env restart` Redémarre le service en cours d’exécution d’un environnement afin que les variables d’environnement enregistrées (y compris les variables gérées provenant des bases de données associées) prennent effet immédiatement, sans nouveau déploiement. ```bash mastra env restart ``` `` peut être le nom, le slug ou l’ID d’un environnement. La commande échoue avec une erreur de conflit si l’environnement n’a jamais été déployé. ### `mastra env vars pull` Récupère les variables d’environnement d’un environnement dans un fichier d’environnement local (par défaut : `.env`). Le fichier contient l’ensemble fusionné utilisé lors d’un déploiement. Il combine les variables enregistrées dans l’environnement (par exemple, celles ajoutées dans l’éditeur d’environnement du tableau de bord) avec les variables définies au niveau du projet. En cas de conflit, les valeurs du projet prévalent. Les variables gérées injectées par les bases de données associées figurent sous forme de commentaires (noms uniquement), car leurs valeurs sont des secrets gérés par la plateforme. ```bash mastra env vars pull mastra env vars pull --output .env.staging ``` `` peut être le nom, le slug ou l’ID d’un environnement, et peut être omis lorsque le projet ne comporte qu’un seul environnement. Le fichier est écrit avec les permissions `0600`. La commande s’arrête si le fichier de sortie existe déjà. Fournissez `--force` pour le remplacer. #### `-o, --output` Fichier dans lequel écrire. La valeur par défaut est `.env`. #### `-f, --force` Remplace un fichier de sortie existant. ### `mastra env db` Gère les bases de données associées à un projet sur la plateforme Mastra. Les bases de données sont provisionnées auprès d’un provider géré (par exemple Turso ou Neon) et injectent automatiquement leurs variables d’environnement de connexion dans les déploiements. Une base de données est soit **limitée à un environnement** (ses variables d’environnement ne sont transmises qu’à un seul environnement), soit **partagée** (limitée au projet : ses variables d’environnement sont transmises à tous les environnements). Pour `mastra env db create`, la portée limitée à un environnement est utilisée par défaut : fournissez un environnement en argument, ou laissez la CLI en choisir un ou vous inviter à le faire. Lors de la création, fournissez plutôt `--shared` pour associer une base de données partagée. Pour les autres sous-commandes (`list`, `delete`, `keys`), fournissez l’environnement en argument afin de travailler avec des bases de données limitées à cet environnement, et omettez-le pour les bases de données partagées. La création et la suppression de bases de données nécessitent le rôle `admin` dans l’organisation. ### `mastra env db list` Répertorie les bases de données associées à un projet, notamment leur provider, leur état de provisionnement, leur portée (l’environnement alimenté par chaque base de données) et les noms des variables d’environnement injectées par chacune. Fournissez un environnement pour n’afficher que les bases de données qui l’alimentent (celles qui lui sont limitées et celles qui sont partagées). ```bash mastra env db list mastra env db list ``` #### `--json` Produit du JSON lisible par une machine. ### `mastra env db create` Provisionne et associe une base de données gérée, puis vérifie régulièrement son état jusqu’à ce qu’elle soit prête. Les erreurs de provisionnement sont affichées avec les détails fournis par le provider. Par défaut, la base de données est limitée à un seul environnement : fournissez un environnement en argument pour le choisir, ou omettez l’argument afin que la CLI le choisisse pour vous. Lorsque le projet comporte un seul environnement, celui-ci est utilisé. Lorsqu’il en comporte plusieurs, la CLI vous invite à en sélectionner un de manière interactive ; dans les contextes non interactifs (CI, `--json`), l’environnement doit être fourni en argument. Vous pouvez plutôt fournir `--shared` pour associer une base de données limitée au projet et partagée par tous les environnements. Les bases de données limitées à un environnement héritent de la région du provider définie par cet environnement. Les bases de données partagées acceptent `--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 de base de données (obligatoire). L’une des valeurs suivantes : `turso` ou `neon`. #### `--name` Nom de la base de données. La valeur par défaut est un nom dérivé du slug du projet (par exemple `my-app-db`). #### `--region` ID de région du provider pour les bases de données partagées. Ignoré pour les bases de données limitées à un environnement. #### `--shared` Associe la base comme une base de données limitée au projet et partagée par tous les environnements. Cette option ne peut pas être combinée avec un environnement en argument. #### `--no-wait` Rend immédiatement la main une fois la demande d’association placée dans la file d’attente, au lieu de vérifier régulièrement l’état jusqu’à ce que la base de données soit prête. Vérifiez ultérieurement la progression avec `mastra env db show`. #### `--json` Produit du JSON lisible par une machine. Dans ce mode, lorsque le projet comporte plusieurs environnements, un environnement en argument ou `--shared` est obligatoire (aucune invite interactive). ### `mastra env db show` Affiche les détails de la base de données et, une fois celle-ci prête, ses variables d’environnement de connexion. Les valeurs secrètes sont masquées par défaut. ```bash mastra env db show ``` `` peut être l’ID ou le nom d’une base de données. #### `--show-secrets` Affiche les valeurs secrètes de connexion au lieu de les masquer. #### `--json` Produit du JSON lisible par une machine. Les valeurs secrètes sont masquées, sauf si `--show-secrets` est fourni. ### `mastra env db delete` Supprime définitivement une base de données auprès du provider, ainsi que toutes ses données. Cette opération est irréversible. La CLI demande une confirmation, sauf si `--yes` est fourni. Après la suppression, les déploiements ne reçoivent plus les variables d’environnement de la base de données. ```bash mastra env db delete ``` #### `-y, --yes` Ignore l’invite de confirmation. ### `mastra env deploys` Répertorie les déploiements d’un projet, du plus récent au plus ancien. Les déploiements qui servent du trafic sont marqués `(active)`. ```bash mastra env deploys [environment] ``` Omettez `[environment]` pour afficher les déploiements de tous les environnements ; indiquez le nom, le slug ou l’ID d’un environnement pour n’afficher que celui-ci. #### `--json` Produit du JSON lisible par une machine. ## `mastra studio deploy` > **Info:** `mastra studio deploy` continue de fonctionner, mais est remplacé par [`mastra deploy`](#mastra-deploy), qui prend en charge plusieurs environnements (`--env staging`, `--env production`) au sein d’un même projet. Les nouvelles configurations doivent utiliser `mastra deploy`. Compile et déploie votre projet sur la plateforme Mastra. Nécessite une authentification via [`mastra auth login`](#mastra-auth-login) ou une variable d’environnement `MASTRA_API_TOKEN`. ```bash mastra studio deploy ``` La commande exécute `mastra build` et compresse la sortie au format ZIP. Elle lit un fichier d’environnement dans le répertoire du projet avant de tout téléverser vers la plateforme. Après le téléversement, elle interroge régulièrement l’état du déploiement et diffuse les journaux de compilation jusqu’à ce que le déploiement atteigne un état final. La commande de déploiement charge automatiquement le fichier `.env` du projet. Si `MASTRA_PROJECT_ID` pointe vers un projet provisionné pour Observability, le déploiement est associé à ce projet au lieu d’en créer un nouveau. Le déploiement de Studio vers un projet réservé à l’observabilité convertit celui-ci en projet Studio du côté de la plateforme. La CLI exige au moins un fichier `.env` ou `.env.*` (à l’exclusion de `.env.example`) dans le répertoire du projet et échoue avec `Error: No env file found for deploy.` s’il n’en existe aucun. Si plusieurs fichiers d’environnement sont présents, la CLI vous invite à en choisir un (`.env.production` par défaut). Utilisez `--env-file` pour le sélectionner explicitement. Avec `--yes` et plusieurs fichiers d’environnement, vous devez fournir `--env-file`, sinon le déploiement échoue. L’organisation et le projet sont déterminés dans l’ordre suivant : option de variable d’environnement, fichier de configuration `.mastra-project.json`, organisation actuelle issue des identifiants, puis invite interactive. Lors du premier déploiement, la CLI enregistre les ID déterminés dans `.mastra-project.json` afin que les déploiements suivants ignorent les invites. Si `--project ` ne correspond à aucun projet existant (par ID ou slug), la CLI considère `` comme le nom d’un nouveau projet et le crée après confirmation. Combinée à `--yes`, cette option crée et déploie un nouveau projet à l’aide d’une seule commande non interactive : ```bash mastra studio deploy --project "my-new-project" --yes ``` ### Arguments #### `[dir]` Répertoire du projet. Utilise le répertoire actuel par défaut. ### Options #### `--org` ID de l’organisation. Peut également être défini à l’aide de la variable d’environnement `MASTRA_ORG_ID`. #### `--project` ID ou slug du projet. Peut également être défini à l’aide de la variable d’environnement `MASTRA_PROJECT_ID`. Si aucun projet ne correspond, la valeur sert de nom au nouveau projet créé lors du déploiement. #### `-y, --yes` Accepte automatiquement les valeurs par défaut sans invite de confirmation. #### `-c, --config` Chemin du fichier de configuration du projet. Utilise `.mastra-project.json` par défaut. #### `--env-file` Chemin du fichier d’environnement à inclure dans le déploiement (relatif au répertoire du projet). Utilisez cette option pour déployer le même projet dans plusieurs environnements en désignant différents fichiers d’environnement (par exemple `.env.staging`, `.env.production`). ```bash mastra studio deploy --env-file .env.staging --yes ``` #### `--skip-build` Ignore l’étape de compilation et déploie le répertoire `.mastra/output` existant. #### `--debug` Active les journaux de débogage pendant l’étape de compilation. ### Utilisation en CI/CD Définissez `MASTRA_API_TOKEN`, `MASTRA_ORG_ID` et `MASTRA_PROJECT_ID` comme variables d’environnement pour les déploiements sans interface. Les invites interactives sont automatiquement ignorées lorsque `MASTRA_API_TOKEN` est défini. ### `mastra studio deploy list` Répertorie tous les projets avec l’état et l’URL de leur dernier déploiement. ### `mastra studio deploy status` Affiche l’état d’un déploiement précis. ```bash mastra studio deploy status ``` #### `--watch, -w` Interroge régulièrement les changements d’état jusqu’à ce que le déploiement atteigne un état final. ### `mastra studio deploy logs` Affiche les journaux d’un déploiement précis. ```bash mastra studio deploy logs ``` #### `--follow, -f` Diffuse les journaux en temps réel. #### `--tail` Nombre de lignes de journal récentes à afficher. ### `mastra studio deploy suggestions` Affiche les résultats du diagnostic et les correctifs suggérés pour un déploiement Studio ayant échoué. ```bash mastra studio deploy suggestions [deploy-id] ``` Si vous omettez `deploy-id`, la commande utilise le dernier déploiement du projet associé. Si aucun diagnostic n’existe encore, la commande en lance un et l’interroge jusqu’à ce que les résultats soient disponibles. Les suggestions n’apparaissent que si le diagnostic détecte un problème. ### `mastra studio projects` Répertorie tous les projets de l’organisation actuelle. ### `mastra studio projects create` Crée un projet à l’aide d’une invite interactive. Cette commande n’accepte pas l’option `--name` ; pour créer un projet de manière non interactive, utilisez plutôt [`mastra studio deploy --project --yes`](#mastra-studio-deploy), qui crée le projet et y effectue un déploiement en une seule étape. ## `mastra server deploy` > **Info:** `mastra server deploy` continue de fonctionner, mais est remplacé par [`mastra deploy`](#mastra-deploy), qui déploie un même projet dans plusieurs environnements au lieu d’utiliser des commandes Studio et Server distinctes. Les nouvelles configurations doivent utiliser `mastra deploy`. Compile et déploie votre projet vers Server sur la plateforme Mastra. Fonctionne comme [`mastra studio deploy`](#mastra-studio-deploy), avec les mêmes options, arguments et règles de détermination. La commande de déploiement charge automatiquement le fichier `.env` du projet. Si `MASTRA_PROJECT_ID` pointe vers un projet provisionné pour Observability, le déploiement est associé à ce projet au lieu d’en créer un nouveau. Le déploiement de Server vers un projet réservé à l’observabilité convertit celui-ci en projet Server du côté de la plateforme. ```bash mastra server deploy [dir] ``` ### `mastra server deploy suggestions` Affiche les résultats du diagnostic et les correctifs suggérés pour un déploiement Server ayant échoué. ```bash mastra server deploy suggestions [deploy-id] ``` Si vous omettez `deploy-id`, la commande utilise le dernier déploiement du projet associé. Si aucun diagnostic n’existe encore, la commande en lance un et l’interroge jusqu’à ce que les résultats soient disponibles. Les suggestions n’apparaissent que si le diagnostic détecte un problème. ## `mastra server pause` Met en pause l’instance de serveur en cours d’exécution pour le projet associé. L’organisation et le projet sont déterminés de la même manière que pour [`mastra server deploy`](#mastra-server-deploy). ```bash mastra server pause ``` ### Options #### `--org` ID de l’organisation. Peut également être défini à l’aide de la variable d’environnement `MASTRA_ORG_ID`. #### `--project` ID ou slug du projet lorsque `MASTRA_PROJECT_ID` n’est pas défini. Les slugs sont recherchés parmi les projets de l’organisation actuelle. #### `-c, --config` Chemin du fichier de configuration du projet. Utilise `.mastra-project.json` par défaut. Échoue si l’instance n’est pas en cours d’exécution. ## `mastra server restart` Redémarre une instance de serveur en pause ou arrêtée pour le projet associé. Une fois le redémarrage accepté par la plateforme, la CLI détermine l’ID du déploiement (à partir de la réponse de l’API ou en interrogeant les métadonnées du projet et du déploiement lorsque la réponse ne contient aucun ID), puis diffuse les journaux de compilation et de déploiement de la même manière que [`mastra server deploy`](#mastra-server-deploy), jusqu’à ce que le déploiement atteigne un état final. ### Options Mêmes options que pour [`mastra server pause`](#mastra-server-pause) : **`--org`**, **`--project`** et **`-c` / `--config`**, avec les mêmes valeurs par défaut et le même comportement. ```bash mastra server restart ``` Échoue si un déploiement est toujours actif pour ce projet (en cours d’exécution, de compilation, de déploiement, etc.). Cette restriction de la plateforme empêche tout redémarrage lorsqu’un autre déploiement est en cours. ## `mastra server env` Gère les variables d’environnement du déploiement de serveur associé. L’organisation et le projet sont déterminés de la même manière que pour [`mastra server deploy`](#mastra-server-deploy). Chaque sous-commande accepte `-c` / `--config` pour indiquer le chemin du fichier de configuration du projet (`.mastra-project.json` par défaut). ### `mastra server env list` Répertorie toutes les variables d’environnement du projet associé. Les valeurs sont partiellement masquées dans la sortie. ### `mastra server env set` Définit une variable d’environnement. La CLI lit la table actuelle, applique la modification et téléverse le résultat. ```bash mastra server env set ``` ### `mastra server env unset` Supprime une variable d’environnement. ```bash mastra server env unset ``` ### `mastra server env import` Importe les variables d’un fichier (par exemple, un fichier `.env`) et les fusionne avec la table existante. Les nouvelles valeurs remplacent les clés déjà présentes sur le serveur. ```bash mastra server env import ``` ### `mastra server env pull` Télécharge les variables d’environnement du projet associé et les écrit dans un fichier local. Cette opération est l’inverse de [`mastra server env import`](#mastra-server-env-import). ```bash mastra server env pull [file] ``` Le fichier utilisé par défaut est `.env` lorsqu’aucun argument n’est fourni. Toutes les valeurs sont placées entre guillemets doubles et échappées afin de pouvoir être chargées en toute sécurité par le shell. Les clés qui ne constituent pas des identifiants shell valides sont ignorées. Le fichier de sortie est créé avec des autorisations restrictives (`0600`), car il contient des secrets. #### `--project` ID ou slug du projet. Remplace le projet associé lorsque `MASTRA_PROJECT_ID` n’est pas défini. #### Utilisation en CI Dans un pipeline d’intégration continue, authentifiez-vous avec `MASTRA_API_TOKEN` et récupérez l’environnement avant d’exécuter votre application : ```bash export MASTRA_API_TOKEN="..." mastra server env pull .env.production --project my-project ``` ## `mastra auth` Gère l’authentification à la plateforme Mastra. Les identifiants sont stockés dans `~/.mastra/credentials.json`. Vous pouvez également définir la variable d’environnement `MASTRA_API_TOKEN` à la place d’une connexion interactive. ### `mastra auth login` Ouvre un navigateur pour vous connecter et stocke les identifiants localement. ### `mastra auth logout` Supprime les identifiants stockés. Si `MASTRA_API_TOKEN` est toujours défini dans l’environnement, la CLI avertit qu’il continuera d’être utilisé. ### `mastra auth whoami` Affiche l’adresse e-mail et l’ID de l’utilisateur actuel, ainsi que l’organisation active. ### `mastra auth orgs` Répertorie toutes les organisations avec votre rôle dans chacune d’elles. L’organisation actuelle est signalée. #### `mastra auth orgs switch` Change l’organisation active à l’aide d’une invite interactive. Cette commande ne peut pas être utilisée lorsque les variables d’environnement `MASTRA_API_TOKEN` ou `MASTRA_ORG_ID` sont définies. ### `mastra auth tokens` Répertorie tous les jetons d’API avec leur date de dernière utilisation. #### `mastra auth tokens create` Crée un jeton d’API. Le secret n’est affiché qu’une seule fois et ne peut plus être récupéré par la suite. ```bash mastra auth tokens create ``` #### `mastra auth tokens revoke` Révoque un jeton d’API. ```bash mastra auth tokens revoke ``` ## `mastra lint` La commande `mastra lint` valide la structure et le code de votre projet Mastra. Par défaut, `mastra lint` vérifie le projet à partir de vos fichiers sources et de votre configuration. Utilisez `--preflight` pour vérifier également le bundle dans `.mastra/output` avant le déploiement. ```bash mastra lint --preflight ``` Elle accepte les [options communes](#common-flags). ### Options #### `--preflight` Exécute les vérifications préalables au déploiement sur la sortie Mastra compilée. Le projet est compilé avant la vérification, sauf si vous fournissez également `--skip-build`. #### `--skip-build` Ignore l’étape de compilation et réutilise le répertoire `.mastra/output` existant. Cette option ne s’applique que lorsque `--preflight` est défini. #### `--env-file ` Utilise le fichier d’environnement indiqué pour la validation préalable. Cette option ne s’applique que lorsque `--preflight` est défini. #### `--strict` Traite les avertissements comme des erreurs. #### `--json` Produit une sortie JSON lisible par une machine. #### `--debug` Active les journaux de débogage. ## `mastra scorers` La commande `mastra scorers` permet de gérer les scorers d’évaluation qui mesurent la qualité, la précision et les performances des sorties générées par l’IA. Pour en savoir plus, consultez la [présentation des Scorers](https://mastra.zisheng.pro/fr/docs/evals/overview). ### `add` Ajoute un scorer à votre projet. Vous pouvez utiliser une invite interactive : ```bash mastra scorers add ``` Ou indiquer directement le nom d’un scorer : ```bash mastra scorers add answer-relevancy ``` Utilisez la commande [`list`](#list) pour obtenir l’ID correct. ### `list` Répertorie tous les modèles de scorer disponibles. Utilisez leur ID avec la commande `add`. ## `mastra create` Crée un projet Mastra autonome en suivant le même processus de création de projet que [`create-mastra`](https://mastra.zisheng.pro/fr/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 ``` Fournir à la fois le nom du projet et `--llm` permet d’ignorer les invites de configuration interactives. Utilisez `--template [template]` pour choisir un modèle quelconque ou `--empty` pour créer une structure minimale sans Provider. La commande installe les Skills Mastra pour les assistants de programmation détectés et initialise Git lorsque cela est approprié. Utilisez `--no-skills` ou `--no-git` pour désactiver ces opérations. Consultez la [référence de `create-mastra`](https://mastra.zisheng.pro/fr/reference/cli/create-mastra) pour connaître le comportement des modes, les conflits, la validation et la description complète des options. ## `mastra init` La commande `mastra init` initialise Mastra dans un projet existant. Utilisez-la pour créer les dossiers et la configuration nécessaires sans générer un nouveau projet à partir de zéro. ### Options La commande accepte les options supplémentaires suivantes : #### `--default` Crée des fichiers dans `src` à l’aide d’OpenAI. Elle ajoute également du code d’exemple dans les dossiers `src/mastra`. #### `--dir` Répertoire dans lequel enregistrer les fichiers Mastra. Utilise `src` par défaut. #### `--components` Liste, séparée par des virgules, des composants à ajouter. Un nouveau dossier est créé pour chaque composant. Valeurs possibles : `"agents" | "tools" | "workflows" | "scorers"`. Utilise `['agents', 'tools', 'workflows']` par défaut. #### `--llm` Provider de modèle par défaut. Valeurs possibles : `"openai" | "anthropic" | "groq" | "google" | "cerebras" | "mistral"`. #### `--llm-api-key` Clé d’API du Provider de modèle choisi. Elle sera écrite dans un fichier de variables d’environnement (`.env`). #### `--example` Si cette option est activée, du code d’exemple est ajouté aux composants de la liste (par exemple, du code d’exemple pour un Agent). #### `--no-example` N’inclut pas de code d’exemple. Utile avec l’option `--default`. #### `--mcp` Configure votre éditeur de code avec le serveur MCP de Mastra. Valeurs possibles : `"cursor" | "cursor-global" | "windsurf" | "vscode"`. #### `--observability` Active Observability sur la plateforme Mastra. La CLI vous invite à sélectionner un projet existant sur la plateforme ou à en créer un. Elle écrit ensuite les variables d’environnement requises et configure les exportateurs d’observabilité. #### `--no-observability` Ignore l’invite Mastra Observability. #### `--observability-project` Définit le nom du projet de la plateforme à utiliser lorsque Mastra Observability est activé. ## `mastra migrate` Exécute les migrations de base de données afin de mettre à jour votre schéma de stockage. Cette commande est utile lors de la mise à niveau vers des versions de Mastra qui modifient le schéma de stockage. La commande crée le bundle de votre projet et se connecte au backend de stockage configuré. Elle exécute ensuite toutes les migrations en attente. Elle prend actuellement en charge : - **Migration des spans en double** : supprime les entrées `(traceId, spanId)` en double et ajoute une contrainte d’unicité afin de garantir l’intégrité des données. - **Migration des spans ClickHouse de l’ancien schéma vers vNext** : copie les spans historiques de l’ancienne table `mastra_ai_spans` vers le schéma vNext `mastra_span_events`. Elle s’exécute par lots afin de respecter les limites de mémoire. Pour plus de détails, consultez la [référence du stockage ClickHouse](https://mastra.zisheng.pro/fr/reference/storage/clickhouse). ```bash mastra migrate ``` Consultez le [guide de migration du stockage](https://mastra.zisheng.pro/fr/guides/migrations/upgrade-to-v1/storage) pour savoir dans quels cas les migrations sont nécessaires. Elle accepte les [options communes](#common-flags). ## `mastra api` Appelle un serveur d’exécution Mastra avec une entrée et une sortie JSON. Utilisez cette commande avec des serveurs de développement locaux, des projets déployés sur la plateforme Mastra, des serveurs Mastra auto-hébergés ou les API hébergées de Mastra Platform Observability. ```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}' ``` Utilisez `mastra api --help` pour afficher des exemples relatifs à une commande. ### Sortie Les réponses réussies sont écrites dans `stdout` au format JSON. Les commandes portant sur une seule ressource renvoient : ```json { "data": {} } ``` Les commandes de liste renvoient un tableau `data` et des métadonnées de pagination : ```json { "data": [], "page": { "total": 0, "page": 0, "perPage": 0, "hasMore": false } } ``` Les erreurs sont écrites dans `stderr` au format JSON et renvoient un code de sortie différent de zéro : ```json { "error": { "code": "SERVER_UNREACHABLE", "message": "Could not connect to target server", "details": {} } } ``` ### Détermination de la cible Pour les commandes d’exécution, la commande détermine le serveur cible dans l’ordre suivant : 1. `--url ` pour un serveur distant ou auto-hébergé explicite. 2. `http://localhost:4111` pour un serveur `mastra dev` local. 3. `.mastra-project.json` pour un projet de la plateforme Mastra. L’authentification automatique à la plateforme n’est utilisée que lorsque la CLI détermine une cible de la plateforme Mastra à partir de `.mastra-project.json`. Les cibles localhost et les cibles `--url` explicites ne reçoivent pas automatiquement d’identifiants. Les en-têtes fournis avec `--header` sont envoyés à toutes les cibles, y compris localhost. Pour les commandes d’observabilité (`trace`, `log`, `score` et `metric`), la CLI cible `https://observability.mastra.ai` par défaut, et non l’URL de déploiement d’un projet. Les commandes Trace Intelligence (`learning`) fonctionnent de la même manière, mais ciblent `https://output.signals.mastra.ai`. Dans les deux cas, les identifiants sont déterminés dans l’ordre suivant : 1. Les en-têtes explicites `Authorization` et `X-Mastra-Project-Id` fournis avec `--header`. 2. `MASTRA_PLATFORM_ACCESS_TOKEN` et `MASTRA_PROJECT_ID` issus de votre environnement. 3. Les métadonnées du projet provenant de `.mastra-project.json` pour l’ID du projet. 4. Votre jeton de connexion à la CLI Mastra comme solution d’authentification de secours. Les commandes Learning envoient également `X-Mastra-Organization-Id`, déterminé à partir d’un `--header` explicite, de `MASTRA_ORGANIZATION_ID` dans votre environnement ou de `.mastra-project.json`, dans cet ordre. Utilisez `--url` et `--header` lorsque vous devez remplacer la cible d’observabilité hébergée ou les identifiants par défaut. ### Options #### `--url ` Cible l’URL d’un serveur Mastra précis. ```bash mastra api --url https://example.com agent list ``` #### `--server-api-prefix ` Définit le préfixe des routes d’API du serveur cible. Utilise `/api` par défaut. Utilisez cette option lorsque le serveur est monté sous un préfixe personnalisé (par exemple, un `@mastra/fastify` `MastraServer` avec `prefix: "/api/mastra-studio"`), de la même manière que `mastra studio` accepte `--server-api-prefix`. Vous pouvez également définir la variable d’environnement `MASTRA_API_PREFIX` au lieu de fournir cette option. ```bash mastra api --url https://example.com --server-api-prefix /api/mastra-studio agent list ``` #### `--header <"Key: Value">` Envoie un en-tête HTTP personnalisé. Répétez l’option pour envoyer plusieurs en-têtes. ```bash mastra api --url https://example.com --header "Authorization: Bearer $TOKEN" agent list ``` #### `--timeout ` Définit le délai d’expiration de la requête en millisecondes. Utilise `30000` par défaut. Les commandes de démarrage et de reprise d’une exécution de Workflow utilisent `120000` par défaut. #### `--pretty` Formate la sortie JSON pour la rendre lisible. Utilise `false` par défaut. #### `--schema` Affiche le schéma de requête destiné à la CLI pour une commande qui accepte une entrée JSON. Ce schéma provient des contrats de route du serveur cible et comprend la forme de la commande, les arguments positionnels, les exemples, les schémas de requête et la forme de la réponse. `--schema` est disponible pour les commandes terminales qui acceptent une entrée JSON. Elle n’est pas disponible comme option de premier niveau de `mastra api`. ```bash mastra api agent run --schema mastra api tool execute --schema ``` ### Modèle d’entrée Les commandes qui acceptent une entrée prennent un unique argument JSON en ligne. Ne fournissez ni chemin de fichier ni entrée standard. ```bash mastra api workflow run start data-pipeline '{"inputData":{"source":"s3://bucket/data.csv"}}' ``` Utilisez des arguments positionnels pour les ID stables et du JSON pour les filtres ou les charges utiles. Pour les routes qui nécessitent à la fois des paramètres de requête et un corps de requête, fournissez un seul objet JSON. La CLI répartit l’entrée selon le schéma de route du serveur. ```bash mastra api thread create '{"agentId":"weather-agent","resourceId":"user_123","threadId":"thread_abc123","title":"Support conversation"}' ``` Les commandes de liste acceptent `page` et `perPage` dans l’entrée JSON lorsque la route cible prend en charge la pagination : ```bash mastra api score list '{"page":0,"perPage":50}' mastra api trace list '{"page":0,"perPage":20}' ``` Les routes qui prennent en charge les filtres les acceptent dans la même entrée JSON. Par exemple, la liste des traces d’observabilité prend en charge la pagination et les filtres pris en charge par la route : ```bash mastra api trace list '{"page":0,"perPage":20,"filters":{"spanType":"agent"}}' ``` ### Obtenir l’aide propre à une commande Chaque commande terminale `mastra api` inclut des exemples qui lui sont propres dans sa sortie d’aide. Utilisez `--help` avec la commande exacte que vous souhaitez appeler : ```bash mastra api agent run --help mastra api tool execute --help mastra api memory current update --help mastra api workflow run resume --help ``` Utilisez `--schema` avec les commandes qui acceptent une entrée JSON afin d’examiner la structure de la requête renvoyée par le serveur cible : ```bash mastra api agent run --schema mastra api thread create --schema mastra api score create --schema ``` Certaines commandes ont des exigences d’exécution importantes. Par exemple, `mastra api memory current update` nécessite que la mémoire de travail soit activée pour l’instance de mémoire, tandis que `mastra api workflow run resume` ne fonctionne que pour les exécutions de workflow suspendues. ### Commandes #### `mastra api agent list` Répertorie les agents enregistrés sur le serveur cible. Transmettez une entrée JSON facultative pour utiliser les filtres pris en charge par la route. ```bash mastra api agent list [input] ``` #### `mastra api agent get` Récupère les métadonnées d’un agent enregistré. ```bash mastra api agent get ``` #### `mastra api agent run` Exécute un agent avec une entrée JSON. Consultez l’aide de la commande pour voir des exemples d’invites textuelles, de messages de chat et d’options de thread de mémoire. ```bash mastra api agent run ``` #### `mastra api workflow list` Répertorie les workflows enregistrés sur le serveur cible. Transmettez une entrée JSON facultative pour utiliser les filtres pris en charge par la route. ```bash mastra api workflow list [input] ``` #### `mastra api workflow get` Récupère les métadonnées d’un workflow enregistré. ```bash mastra api workflow get ``` #### `mastra api workflow run start` Démarre une exécution de workflow avec une entrée JSON. Les commandes de démarrage de workflow utilisent un délai d’expiration par défaut plus long que la plupart des commandes, car les exécutions peuvent prendre davantage de temps. ```bash mastra api workflow run start ``` #### `mastra api workflow run list` Répertorie les exécutions d’un workflow. Transmettez une entrée JSON facultative pour utiliser les filtres ou la pagination pris en charge par la route. ```bash mastra api workflow run list [input] ``` #### `mastra api workflow run get` Récupère une exécution de workflow à partir de son ID. ```bash mastra api workflow run get ``` #### `mastra api workflow run resume` Reprend une exécution de workflow suspendue avec une entrée JSON. L’exécution doit être à l’état suspendu. ```bash mastra api workflow run resume ``` #### `mastra api workflow run cancel` Annule une exécution de workflow. ```bash mastra api workflow run cancel ``` #### `mastra api tool list` Répertorie les outils enregistrés sur le serveur cible. Transmettez une entrée JSON facultative pour utiliser les filtres pris en charge par la route. ```bash mastra api tool list [input] ``` #### `mastra api tool get` Récupère les métadonnées et les schémas d’un outil. ```bash mastra api tool get ``` #### `mastra api tool execute` Exécute un outil avec une entrée JSON. L’entrée brute de l’outil est encapsulée dans le champ `data` de la route, sauf si vous transmettez explicitement un objet `data`. ```bash mastra api tool execute ``` #### `mastra api mcp list` Répertorie les serveurs Model Context Protocol (MCP) enregistrés sur le serveur cible. Transmettez une entrée JSON facultative pour utiliser les filtres pris en charge par la route. ```bash mastra api mcp list [input] ``` #### `mastra api mcp get` Récupère les métadonnées d’un serveur MCP. ```bash mastra api mcp get ``` #### `mastra api mcp tool list` Répertorie les outils exposés par un serveur MCP. Transmettez une entrée JSON facultative pour utiliser les filtres pris en charge par la route. ```bash mastra api mcp tool list [input] ``` #### `mastra api mcp tool get` Récupère les métadonnées et les schémas d’un outil MCP. ```bash mastra api mcp tool get ``` #### `mastra api mcp tool execute` Exécute un outil MCP avec une entrée JSON. L’entrée brute de l’outil est encapsulée dans le champ `data` de la route, sauf si vous transmettez explicitement un objet `data`. ```bash mastra api mcp tool execute ``` #### `mastra api thread list` Répertorie les threads de mémoire. Transmettez une entrée JSON facultative pour utiliser les filtres pris en charge par la route. ```bash mastra api thread list [input] ``` #### `mastra api thread get` Récupère un thread de mémoire à partir de son ID. ```bash mastra api thread get ``` #### `mastra api thread create` Crée un thread de mémoire. Transmettez un objet d’entrée JSON ; la CLI convertit les champs tels que `agentId` en paramètres de requête lorsque la route du serveur l’exige. ```bash mastra api thread create ``` #### `mastra api thread update` Met à jour un thread de mémoire. Transmettez un objet d’entrée JSON pour les champs tels que `agentId`, `resourceId`, `title` ou `metadata`. ```bash mastra api thread update ``` #### `mastra api thread delete` Supprime un thread de mémoire. Transmettez une entrée JSON pour les paramètres de requête exigés par la route, tels que `agentId` et `resourceId`. ```bash mastra api thread delete ``` #### `mastra api thread messages` Répertorie les messages d’un thread de mémoire. Transmettez une entrée JSON facultative pour utiliser les filtres ou la pagination pris en charge par la route. ```bash mastra api thread messages [input] ``` #### `mastra api memory search` Effectue une recherche dans la mémoire à long terme. Utilisez `--help` ou `--schema` pour examiner les champs obligatoires tels que `agentId`, `resourceId` et `searchQuery`. ```bash mastra api memory search ``` #### `mastra api memory current get` Lit la mémoire de travail actuelle d’un thread. ```bash mastra api memory current get ``` #### `mastra api memory current update` Met à jour la mémoire de travail actuelle d’un thread. La mémoire de travail doit être activée pour l’instance de mémoire. ```bash mastra api memory current update ``` #### `mastra api memory status` Récupère l’état de la mémoire pour un agent, ainsi que, facultativement, le contexte d’un thread ou d’une ressource. ```bash mastra api memory status ``` #### `mastra api trace list` Répertorie les traces d’observabilité. Transmettez une entrée JSON facultative pour utiliser les filtres ou la pagination pris en charge par la route. ```bash mastra api trace list [input] mastra api trace list '{"page":0,"perPage":20}' mastra api trace list '{"page":0,"perPage":20}' --verbose ``` Par défaut, `trace list` renvoie des enregistrements légers de spans racines afin de parcourir les traces page par page sans récupérer de volumineuses charges utiles d’entrée, de sortie, d’attributs ou de métadonnées. Transmettez `--verbose` pour récupérer les enregistrements complets des spans racines. #### `mastra api trace get` Récupère une chronologie légère d’une trace d’observabilité sans récupérer les charges utiles complètes d’entrée, de sortie, d’attributs ou de métadonnées des spans. Transmettez `--verbose` pour récupérer la charge utile complète de la trace. ```bash mastra api trace get mastra api trace get --verbose ``` #### `mastra api trace span` Récupère un span complet d’une trace d’observabilité. Utilisez cette commande après `trace get` lorsque vous savez quel span examiner. ```bash mastra api trace span ``` #### `mastra api log list` Répertorie les journaux d’observabilité. Transmettez une entrée JSON facultative pour utiliser les filtres ou la pagination pris en charge par la route. ```bash mastra api log list [input] ``` #### `mastra api metric aggregate` Récupère une valeur de métrique agrégée unique. ```bash mastra api metric aggregate '{"name":["latency_ms"],"aggregation":"avg"}' ``` #### `mastra api metric breakdown` Récupère les valeurs de métrique regroupées par libellé ou par champ. ```bash mastra api metric breakdown '{"name":["latency_ms"],"aggregation":"avg","groupBy":["model"],"limit":10}' ``` #### `mastra api metric timeseries` Récupère les valeurs de métrique au fil du temps. ```bash mastra api metric timeseries '{"name":["latency_ms"],"aggregation":"avg","interval":"1h"}' ``` #### `mastra api metric percentiles` Récupère les valeurs de percentiles d’une métrique au fil du temps. Les valeurs de percentile utilisent des nombres décimaux de `0` à `1`. ```bash mastra api metric percentiles '{"name":"latency_ms","percentiles":[0.5,0.95,0.99],"interval":"1h"}' ``` #### `mastra api metric names` Répertorie les noms de métriques détectés. Transmettez une entrée JSON facultative pour la recherche par préfixe et la limite. ```bash mastra api metric names '{"prefix":"lat","limit":10}' ``` #### `mastra api metric label-keys` Répertorie les clés de libellé d’une métrique. ```bash mastra api metric label-keys '{"metricName":"latency_ms"}' ``` #### `mastra api metric label-values` Répertorie les valeurs de libellé associées à une clé de libellé de métrique. Transmettez facultativement des valeurs de préfixe et de limite pour affiner le résultat. ```bash mastra api metric label-values '{"metricName":"latency_ms","labelKey":"model","prefix":"g","limit":10}' ``` #### Observabilité avec `curl` Vous pouvez appeler directement l’API d’observabilité hébergée avec votre jeton d’accès à la plateforme et l’ID de votre projet : ```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 ``` Récupérez une chronologie légère de la trace : ```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 ``` Récupérez un span précis : ```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` Crée un score d’observabilité. L’entrée utilise la structure du corps de score du serveur. Examinez-la avec `--schema`. ```bash mastra api score create ``` #### `mastra api score list` Répertorie les scores d’observabilité. Transmettez une entrée JSON facultative pour les filtres tels que l’ID d’exécution ou la pagination. ```bash mastra api score list [input] ``` #### `mastra api score get` Récupère un score d’observabilité à partir de son ID. ```bash mastra api score get ``` #### `mastra api dataset list` Répertorie les jeux de données. Transmettez une entrée JSON facultative pour utiliser les filtres ou la pagination pris en charge par la route. ```bash mastra api dataset list [input] ``` #### `mastra api dataset get` Récupère un jeu de données à partir de son ID. ```bash mastra api dataset get ``` #### `mastra api dataset create` Crée un jeu de données avec une entrée JSON. ```bash mastra api dataset create ``` #### `mastra api dataset items` Répertorie les éléments d’un jeu de données. Transmettez une entrée JSON facultative pour utiliser les filtres ou la pagination pris en charge par la route. ```bash mastra api dataset items [input] ``` #### `mastra api experiment list` Répertorie les expériences d’un jeu de données. Transmettez une entrée JSON facultative pour utiliser les filtres ou la pagination pris en charge par la route. ```bash mastra api experiment list [input] ``` #### `mastra api experiment get` Récupère une expérience à partir de son ID. ```bash mastra api experiment get ``` #### `mastra api experiment run` Démarre une expérience pour un jeu de données avec une entrée JSON. ```bash mastra api experiment run ``` #### `mastra api experiment results` Répertorie les résultats d’une expérience. Transmettez une entrée JSON facultative pour utiliser les filtres ou la pagination pris en charge par la route. ```bash mastra api experiment results [input] ``` #### `mastra api learning entities` Répertorie les entités (agents) accompagnées des résultats de Trace Intelligence, notamment les signaux de trace disponibles pour chaque entité. Nécessite une inscription à la version bêta privée de Trace Intelligence. ```bash mastra api learning entities '{"entityType":"agent"}' ``` #### `mastra api learning snapshots` Répertorie les instantanés d’analyse d’une entité pour une liste ordonnée de signaux de trace séparés par des virgules. Les commandes suivantes nécessitent un `snapshotId` issu de cette liste. ```bash mastra api learning snapshots '{"entityType":"agent","signalNames":"goal,outcome,behavior,sentiment","limit":10}' ``` #### `mastra api learning flow` Récupère le flux de thèmes entre les signaux pour un instantané : les étapes et les liens d’une vue de type Sankey dans laquelle les nombres correspondent à des traces distinctes. ```bash mastra api learning flow '{"entityType":"agent","signalNames":"goal,outcome","snapshotId":""}' ``` #### `mastra api learning paths` Récupère, pour chaque trace, les thèmes attribués dans l’ensemble des signaux de trace ordonnés d’un instantané. Utilisez `limit` et `offset` pour la pagination. ```bash mastra api learning paths '{"entityType":"agent","signalNames":"goal,outcome","snapshotId":"","limit":100}' ``` #### `mastra api learning theme list` Répertorie les thèmes d’un signal de trace dans un instantané. ```bash mastra api learning theme list '{"entityType":"agent","signalName":"goal","snapshotId":""}' ``` #### `mastra api learning theme get` Récupère un thème dans un instantané à partir de son ID de thème numérique. ```bash mastra api learning theme get '{"entityType":"agent","signalName":"goal","snapshotId":""}' ``` #### `mastra api learning theme examples` Répertorie les exemples de traces associés à un thème dans un instantané. Utilisez `limit` et `offset` pour la pagination. ```bash mastra api learning theme examples '{"entityType":"agent","signalName":"goal","snapshotId":"","limit":10}' ``` #### `mastra api learning theme history` Récupère l’historique du cycle de vie d’un thème persistant dans plusieurs instantanés, y compris les relations de fractionnement et de fusion. N’accepte aucun `snapshotId`. ```bash mastra api learning theme history '{"entityType":"agent","signalName":"goal"}' ``` #### `mastra api learning noise get` Récupère le groupe non classé (bruit) d’un signal de trace dans un instantané. ```bash mastra api learning noise get '{"entityType":"agent","signalName":"goal","snapshotId":""}' ``` #### `mastra api learning noise examples` Répertorie les exemples de traces du groupe de bruit dans un instantané. Utilisez `limit` et `offset` pour la pagination. ```bash mastra api learning noise examples '{"entityType":"agent","signalName":"goal","snapshotId":"","limit":10}' ``` ## Options communes ### `--dir` **Disponible dans :** `dev`, `build`, `lint`, `migrate` Chemin d’accès à votre dossier Mastra. La valeur par défaut est `src/mastra`. ### `--debug` **Disponible dans :** `dev`, `build`, `migrate` Active la journalisation détaillée des composants internes de Mastra. La valeur par défaut est `false`. ### `--env` **Disponible dans :** `dev`, `start`, `studio`, `migrate` Fichier personnalisé de variables d’environnement à inclure. Par défaut, `.env.development`, `.env.local` et `.env` sont inclus. ### `--root` **Disponible dans :** `dev`, `build`, `lint`, `migrate` Chemin d’accès à votre dossier racine. La valeur par défaut est `process.cwd()`. ### `--tools` **Disponible dans :** `dev`, `build`, `lint` Liste, séparée par des virgules, des chemins d’accès aux outils à inclure. La valeur par défaut est `src/mastra/tools`. ## Options globales Utilisez ces options pour obtenir des informations sur la CLI `mastra`. ### `--version` Affiche la version de la CLI Mastra, puis quitte. ### `--help` Affiche le message d’aide, puis quitte. ## Télémétrie Par défaut, Mastra recueille des informations anonymes sur votre projet, telles que votre système d’exploitation, la version de Mastra ou la version de Node.js. Vous pouvez consulter le [code source](https://github.com/mastra-ai/mastra/blob/main/packages/cli/src/analytics/index.ts) pour vérifier les données recueillies. Lorsqu’un serveur démarré avec `mastra dev` ou `mastra start` a activé les métriques d’observabilité, Mastra envoie également au démarrage des données anonymes et agrégées sur l’utilisation des modèles : le nombre de tokens d’entrée et de sortie par fournisseur et par modèle, ainsi que la commande (`dev` ou `start`) et `NODE_ENV`. Aucune invite, réponse ni aucun autre contenu de message n’est envoyé. Vous pouvez consulter le [code source](https://github.com/mastra-ai/mastra/blob/main/packages/core/src/telemetry/usage-telemetry.ts) pour vérifier les données recueillies. Au démarrage du serveur, Mastra envoie également un instantané anonyme de la surface du projet : le nombre d’agents, de contrôleurs d’agents, de workflows, d’outils, de processeurs, de bases de données vectorielles, de scorers, de workspaces, de serveurs MCP, de gateways et de canaux enregistrés, ainsi que des valeurs booléennes indiquant l’utilisation de la mémoire, de la voix, de l’éditeur et de l’observabilité, et la catégorie générale du backend de stockage. Aucun nom ni identifiant n’est envoyé. Vous pouvez consulter le [code source](https://github.com/mastra-ai/mastra/blob/main/packages/core/src/telemetry/feature-telemetry.ts) pour vérifier les données recueillies. Vous pouvez désactiver toutes les données d’analyse de la CLI et de l’utilisation en définissant une variable d’environnement : ```bash MASTRA_TELEMETRY_DISABLED=1 ``` Vous pouvez également définir cette variable lorsque vous utilisez d’autres commandes `mastra` : ```bash MASTRA_TELEMETRY_DISABLED=1 mastra dev ```