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 ainsi que des endpoints REST pour vos agents, tools et workflows. Une fois mastra dev en cours d’exécution, consultez http://localhost:4111/swagger-ui pour obtenir un aperçu de tous les endpoints disponibles.

Vous pouvez également configurer le serveur.

Options

La commande accepte les options communes ainsi que les options supplémentaires suivantes :

--https

Active la prise en charge locale de HTTPS. En savoir plus.

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

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 :

{
  "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 :

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

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 :

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 :

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

Pour Anthropic :

ANTHROPIC_API_KEY=<your-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. Il utilise le même environnement d’exécution de développement et les mêmes options que mastra dev, et écrit dans le même répertoire .mastra/output.

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

Si vous déployez sur une plateforme serverless, vous devez installer le deployer approprié afin d’obtenir la sortie adéquate dans .mastra.

Elle accepte les options communes.

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 :

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.

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 est activé.

Options

La commande accepte les options communes 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.

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.

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.

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

# 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 pour connaître les topologies de déploiement et leur configuration.

mastra studio

Démarre Studio 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 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. Fonctionne de la même manière que l’option mastra dev.

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 et 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 ou la variable d’environnement MASTRA_API_TOKEN.

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 :

mastra deploy --env staging --yes

Lorsque --env <name> est défini contrairement à --env-file, la CLI sélectionne automatiquement .env.<name> dans le répertoire du projet s’il existe (par exemple .env.staging). La valeur <name> 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.<name> 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.<name> fondée sur --env.

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.

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 <name|slug|id>. Elle lit ensuite, dans le répertoire actuel, le fichier .mastra-project.json écrit par 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.

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.

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 delete

Supprime un environnement.

mastra env delete <env>

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

mastra env restart <env>

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

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

<env> 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).

mastra env db list
mastra env db list <env>

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

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.

mastra env db show <database>

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

mastra env db delete <database>

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

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, 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 ou une variable d’environnement MASTRA_API_TOKEN.

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 <value> ne correspond à aucun projet existant (par ID ou slug), la CLI considère <value> 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 :

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

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.

mastra studio deploy status <deploy-id>

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

mastra studio deploy logs <deploy-id>

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

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 <name> --yes, 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, 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, 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.

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

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 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, jusqu’à ce que le déploiement atteigne un état final.

Options

Mêmes options que pour mastra server pause : --org, --project et -c / --config, avec les mêmes valeurs par défaut et le même comportement.

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.

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.

mastra server env set <key> <value>

mastra server env unset

Supprime une variable d’environnement.

mastra server env unset <key>

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.

mastra server env import <file>

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

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.

mastra auth tokens create <name>

mastra auth tokens revoke

Révoque un jeton d’API.

mastra auth tokens revoke <token-id>

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.

mastra lint --preflight

Elle accepte les options communes.

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

add

Ajoute un scorer à votre projet. Vous pouvez utiliser une invite interactive :

mastra scorers add

Ou indiquer directement le nom d’un scorer :

mastra scorers add answer-relevancy

Utilisez la commande 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.

npm

npx mastra@latest create

pnpm

pnpm dlx mastra@latest create

Yarn

yarn dlx mastra@latest create

Bun

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

mastra migrate

Consultez le guide de migration du stockage pour savoir dans quels cas les migrations sont nécessaires.

Elle accepte les options communes.

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.

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 <resource> <action> --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 :

{ "data": {} }

Les commandes de liste renvoient un tableau data et des métadonnées de pagination :

{ "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 :

{
  "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 <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 <url>

Cible l’URL d’un serveur Mastra précis.

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

--server-api-prefix <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.

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.

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

--timeout <ms>

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.

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.

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.

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 :

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 :

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 :

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 :

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.

mastra api agent list [input]

mastra api agent get

Récupère les métadonnées d’un agent enregistré.

mastra api agent get <agentId>

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.

mastra api agent run <agentId> <input>

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.

mastra api workflow list [input]

mastra api workflow get

Récupère les métadonnées d’un workflow enregistré.

mastra api workflow get <workflowId>

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.

mastra api workflow run start <workflowId> <input>

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.

mastra api workflow run list <workflowId> [input]

mastra api workflow run get

Récupère une exécution de workflow à partir de son ID.

mastra api workflow run get <workflowId> <runId>

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.

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

mastra api workflow run cancel

Annule une exécution de workflow.

mastra api workflow run cancel <workflowId> <runId>

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.

mastra api tool list [input]

mastra api tool get

Récupère les métadonnées et les schémas d’un outil.

mastra api tool get <toolId>

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.

mastra api tool execute <toolId> <input>

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.

mastra api mcp list [input]

mastra api mcp get

Récupère les métadonnées d’un serveur MCP.

mastra api mcp get <id>

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.

mastra api mcp tool list <serverId> [input]

mastra api mcp tool get

Récupère les métadonnées et les schémas d’un outil MCP.

mastra api mcp tool get <serverId> <toolId>

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.

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

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.

mastra api thread list [input]

mastra api thread get

Récupère un thread de mémoire à partir de son ID.

mastra api thread get <threadId>

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.

mastra api thread create <input>

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.

mastra api thread update <threadId> <input>

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.

mastra api thread delete <threadId> <input>

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.

mastra api thread messages <threadId> [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.

mastra api memory search <input>

mastra api memory current get

Lit la mémoire de travail actuelle d’un thread.

mastra api memory current get <input>

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.

mastra api memory current update <input>

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.

mastra api memory status <input>

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.

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.

mastra api trace get <traceId>
mastra api trace get <traceId> --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.

mastra api trace span <traceId> <spanId>

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.

mastra api log list [input]

mastra api metric aggregate

Récupère une valeur de métrique agrégée unique.

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.

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.

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.

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.

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

mastra api metric label-keys

Répertorie les clés de libellé d’une métrique.

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.

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 :

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 :

curl -sS "https://observability.mastra.ai/api/observability/traces/<trace-id>/light" \
  -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \
  -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" | jq

Récupérez un span précis :

curl -sS "https://observability.mastra.ai/api/observability/traces/<trace-id>/spans/<span-id>" \
  -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \
  -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" | jq

mastra api score create

Crée un score d’observabilité. L’entrée utilise la structure du corps de score du serveur. Examinez-la avec --schema.

mastra api score create <input>

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.

mastra api score list [input]

mastra api score get

Récupère un score d’observabilité à partir de son ID.

mastra api score get <scoreId>

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.

mastra api dataset list [input]

mastra api dataset get

Récupère un jeu de données à partir de son ID.

mastra api dataset get <datasetId>

mastra api dataset create

Crée un jeu de données avec une entrée JSON.

mastra api dataset create <input>

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.

mastra api dataset items <datasetId> [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.

mastra api experiment list <datasetId> [input]

mastra api experiment get

Récupère une expérience à partir de son ID.

mastra api experiment get <datasetId> <experimentId>

mastra api experiment run

Démarre une expérience pour un jeu de données avec une entrée JSON.

mastra api experiment run <datasetId> <input>

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.

mastra api experiment results <datasetId> <experimentId> [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.

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.

mastra api learning snapshots <entityId> '{"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.

mastra api learning flow <entityId> '{"entityType":"agent","signalNames":"goal,outcome","snapshotId":"<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.

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

mastra api learning theme list

Répertorie les thèmes d’un signal de trace dans un instantané.

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

mastra api learning theme get

Récupère un thème dans un instantané à partir de son ID de thème numérique.

mastra api learning theme get <entityId> <themeId> '{"entityType":"agent","signalName":"goal","snapshotId":"<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.

mastra api learning theme examples <entityId> <themeId> '{"entityType":"agent","signalName":"goal","snapshotId":"<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.

mastra api learning theme history <entityId> <themeId> '{"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é.

mastra api learning noise get <entityId> '{"entityType":"agent","signalName":"goal","snapshotId":"<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.

mastra api learning noise examples <entityId> '{"entityType":"agent","signalName":"goal","snapshotId":"<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 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 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 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 :

MASTRA_TELEMETRY_DISABLED=1

Vous pouvez également définir cette variable lorsque vous utilisez d’autres commandes mastra :

MASTRA_TELEMETRY_DISABLED=1 mastra dev