The masaic CLI

masaic is the command-line way into your workspace. Reach for it when a change should be repeatable — the same change applied to staging and then production, reviewed by a colleague first, or run by a pipeline instead of a person.

The CLI's defining idea: an agent, prompt, model, skill, or channel can live as a YAML file in your own repository. Applying that file publishes it. So a change to an agent gets reviewed the way a change to code does, and nothing about it depends on someone remembering which buttons they clicked.

Install the CLI

bash install.sh

That fetches the newest release and puts masaic on your PATH (Node 22 or newer). On Windows, run .\install.ps1 instead. There are also options for installing a specific build or the newest development snapshot — see running MASAIC without a clone for the full set.

Check it:

masaic --version
masaic --help

masaic --help is grouped by what you are trying to do, and each command has its own --help. It is generated from the program itself, so it can never be out of date — trust it over any list, including this page.

Sign in

masaic login

For a local instance, masaic login --dev uses the seeded developer account. In CI, supply a token instead — masaic login --with-token reads it from standard input, never from the command line, so it stays out of your shell history and out of the process list.

Confirm who you are:

masaic whoami
masaic config view     # the resolved URL, project, and auth

masaic config view is the first thing to run whenever the CLI seems to be talking to the wrong place. An exported environment variable beats your saved settings, and this is what shows you that.

Projects and contexts

A project is a team workspace — it owns its own agents, prompts, models, and deployments. Two projects can each have an agent called support, and they are different agents.

masaic get projects                       # which project am I in?
masaic --project billing get agents       # run one command in another project

There is deliberately no default project: a guessed one would send a change into the wrong tenant.

A context bundles an instance URL with the credentials for it — local, staging, production — so you can move between them without signing in again:

masaic context list
masaic --context staging get agents       # one command against staging

The YAML loop

This is the CLI's main workflow.

1. Scaffold — create a ./masaic/ folder with starter files:

masaic init

2. Edit — the files are Kubernetes-shaped, which is to say every one declares what kind of thing it is and then describes it:

apiVersion: agent.masaic.dev/v1
kind: Agent
metadata:
  name: billing-support
spec:
  # ... model, prompt, skills, execution settings

3. Validate — check the file locally, with no changes and no network calls:

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

4. Apply — publish it:

masaic apply -f ./masaic/agent.runtime.yaml
masaic apply -f ./masaic/combined.runtime.yaml --dry-run   # what would happen, without doing it

One file can carry several definitions, so a model, a prompt, and the agent that uses them apply together.

Applying creates or updates the published version your workspace runs. That is separate from editing a draft in the console, and promotion between environments still follows your release process (Safe rollouts).

Reading and removing

masaic get agents
masaic get modelconfigs        # `masaic get models` works too
masaic get prompts
masaic get skills
masaic get resources
masaic get channels
masaic get testcases
masaic get testruns

masaic delete agent <id>

Most resources accept a friendly alias, so you rarely have to remember the exact spelling. delete identifies the row by id — the value get printed — not by the display name.

Talking to a deployed agent

These reach the agent runtime rather than the control plane — they exercise an agent instead of describing one:

masaic invoke --agent billing-support "What is my current bill?"
masaic invoke --agent billing-support "..." --stream    # print the answer as it arrives
masaic agentcard billing-support                        # what the agent declares about itself
masaic task <taskId> --agent billing-support            # read back what a run produced

invoke prints a task id; masaic task reads that run back later.

All three must be told which agent: agentcard takes the name as its argument, while invoke and task take --agent <name>. Any of them accepts --agent-version <id> instead, to pin one specific version, and --env when the agent is deployed to several environments. A task id on its own is not enough — it does not say where to look.

It is --agent-version, never --version. --version belongs to the CLI itself, so it would print the CLI's version and invoke nothing.

Command groups

masaic --help organises the surface by goal:

In a pipeline

Everything above works unattended. A typical job signs in with a token from your secret store, validates, then applies:

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

Keep validate as its own step: it fails on a malformed definition before anything is published.

If something looks wrong

Related

• Control MASAIC from your coding agent — the same operations, asked for in plain language.
• Ways to control MASAIC — how the console, MCP, and CLI compare.
• Testing and release — validating a change before it ships.

← Control MASAIC from your coding agent · Teams and access →