Die masaic CLI

masaic ist der Weg über die Kommandozeile in deinen Workspace. Greif danach, wenn eine Änderung wiederholbar sein soll — dieselbe Änderung erst nach Staging, dann nach Production; vorher von einer Kollegin reviewt; oder von einer Pipeline ausgeführt statt von einem Menschen.

Die prägende Idee der CLI: Ein Agent, Prompt, Modell, Skill oder Channel kann als YAML-Datei in deinem eigenen Repository liegen. Diese Datei anzuwenden, veröffentlicht sie. Eine Änderung an einem Agent wird also so reviewt wie eine Änderung an Code — und nichts daran hängt davon ab, dass sich jemand erinnert, welche Buttons er geklickt hat.

CLI installieren

bash install.sh

Das holt das neueste Release und legt masaic in deinen PATH (Node 22 oder neuer). Unter Windows nimm stattdessen .\install.ps1. Es gibt außerdem Optionen für einen bestimmten Build oder den neuesten Entwicklungs-Snapshot — die vollständige Liste steht unter MASAIC ohne Clone betreiben.

Prüfen:

masaic --version
masaic --help

masaic --help ist danach gruppiert, was du vorhast, und jeder Befehl hat sein eigenes --help. Es wird aus dem Programm selbst erzeugt und kann daher nie veralten — vertraue ihm mehr als jeder Liste, auch dieser Seite.

Anmelden

masaic login

Für eine lokale Instanz nutzt masaic login --dev den geseedeten Entwickler-Account. In CI gibst du stattdessen ein Token mit: masaic login --with-token liest es von Standard-Input, nie von der Kommandozeile — so bleibt es aus deiner Shell-History und aus der Prozessliste heraus.

Prüfen, wer du bist:

masaic whoami
masaic config view     # aufgelöste URL, Projekt und Auth

masaic config view ist das Erste, was du ausführst, wenn die CLI mit der falschen Stelle zu sprechen scheint. Eine exportierte Umgebungsvariable schlägt deine gespeicherten Einstellungen — und genau das zeigt dir dieser Befehl.

Projekte und Contexts

Ein Projekt ist ein Team-Workspace — es besitzt seine eigenen Agents, Prompts, Modelle und Deployments. Zwei Projekte können jeweils einen Agent namens support haben, und das sind verschiedene Agents.

masaic get projects                       # in welchem Projekt bin ich?
masaic --project billing get agents       # einen Befehl in einem anderen Projekt ausführen

Es gibt bewusst kein Default-Projekt: Ein geratenes würde eine Änderung in den falschen Tenant schicken.

Ein Context bündelt eine Instanz-URL mit den Credentials dafür — lokal, Staging, Production — sodass du zwischen ihnen wechselst, ohne sich neu anzumelden:

masaic context list
masaic --context staging get agents       # ein Befehl gegen Staging

Die YAML-Schleife

Das ist der Haupt-Workflow der CLI.

1. Scaffolding — einen ./masaic/-Ordner mit Startdateien erzeugen:

masaic init

2. Bearbeiten — die Dateien sind Kubernetes-förmig: Jede deklariert, um welche Art Ding es sich handelt, und beschreibt es dann:

apiVersion: agent.masaic.dev/v1
kind: Agent
metadata:
  name: billing-support
spec:
  # ... Modell, Prompt, Skills, Execution-Einstellungen

3. Validieren — die Datei lokal prüfen, ohne Änderungen und ohne Netzwerkaufrufe:

masaic validate -f ./masaic/agent.runtime.yaml

4. Anwenden — veröffentlichen:

masaic apply -f ./masaic/agent.runtime.yaml
masaic apply -f ./masaic/combined.runtime.yaml --dry-run   # was passieren würde, ohne es zu tun

Eine Datei kann mehrere Definitionen enthalten — ein Modell, ein Prompt und der Agent, der sie nutzt, werden so gemeinsam angewendet.

Anwenden erzeugt oder aktualisiert die veröffentlichte Version, die dein Workspace ausführt. Das ist getrennt vom Bearbeiten eines Entwurfs in der Console, und die Beförderung zwischen Environments folgt weiterhin deinem Release-Prozess (Sichere Rollouts).

Lesen und löschen

masaic get agents
masaic get modelconfigs        # `masaic get models` geht auch
masaic get prompts
masaic get skills
masaic get resources
masaic get channels
masaic get testcases
masaic get testruns

masaic delete agent <id>

Die meisten Ressourcen akzeptieren einen freundlichen Alias, du musst die genaue Schreibweise also selten kennen. delete identifiziert die Zeile über die id — den Wert, den get ausgegeben hat — nicht über den Anzeigenamen.

Mit einem deployten Agent sprechen

Diese Befehle erreichen die Agent-Runtime statt der Control-Plane — sie führen einen Agent aus, statt ihn zu beschreiben:

masaic invoke --agent billing-support "Wie hoch ist meine aktuelle Rechnung?"
masaic invoke --agent billing-support "..." --stream    # Antwort ausgeben, während sie entsteht
masaic agentcard billing-support                        # was der Agent über sich deklariert
masaic task <taskId> --agent billing-support            # zurücklesen, was ein Lauf erzeugt hat

invoke gibt eine Task-id aus; masaic task liest diesen Lauf später zurück.

Allen dreien muss gesagt werden, welcher Agent gemeint ist: agentcard nimmt den Namen als Argument, invoke und task nehmen --agent <name>. Alle akzeptieren stattdessen --agent-version <id>, um eine bestimmte Version festzulegen, und --env, wenn der Agent in mehrere Environments deployt ist. Eine Task-id allein genügt nicht — sie sagt nicht, wo zu suchen ist.

Es heißt --agent-version, nie --version. --version gehört der CLI selbst — es würde deren Version ausgeben und nichts aufrufen.

Befehlsgruppen

masaic --help ordnet die Oberfläche nach Zielen:

In einer Pipeline

Alles oben funktioniert unbeaufsichtigt. Ein typischer Job meldet sich mit einem Token aus deinem Secret-Store an, validiert und wendet dann an:

masaic login --with-token < "$MASAIC_TOKEN_FILE"
masaic validate -f ./masaic/
masaic apply -f ./masaic/

Behalte validate als eigenen Schritt: Er schlägt bei einer fehlerhaften Definition fehl, bevor etwas veröffentlicht wird.

Wenn etwas falsch aussieht

Verwandt

• MASAIC aus deinem Coding-Agent steuern — dieselben Operationen, in normaler Sprache erfragt.
• Wege, MASAIC zu steuern — wie Console, MCP und CLI sich vergleichen.
• Testen und Release — eine Änderung prüfen, bevor sie ausgeliefert wird.

← MASAIC aus deinem Coding-Agent steuern · Teams und Zugriff →