Missions CLI

Run, manage and build missions from a terminal or a script: ask a mission, approve what's waiting, run watchers, change records and settings, install and upgrade missions.

For operators and developers working with one or many Missions installations, and for scripts and CI.

Version 3.1.7 · Oct 19, 2026

Pick the file for your computer from the list below.

All platforms and checksums

Guide

Which tool?

  • Missions CLI (this guide): run, manage and build missions from a terminal or a script.
  • A2A CLI (a separate download on the same page): talk to a mission as an agent.
  • Missions API: call missions from your own code. Guide: https://www.studiox-ai.com/downloads/missions-api

What it is and what you can do

missions is one executable file for macOS, Windows and Linux. It signs in to your StudioX installation and works with the missions you can see there. With it you can:

  • ask a mission a question, in an interactive session or from a script;
  • see what waits for approval, and approve, reject or choose an option;
  • run watchers, read their logs, switch them on or off, and push rows into them;
  • read and change a mission's records;
  • check status and health, pause or activate a mission, and change its settings and credentials;
  • install a mission from a bundle, a blueprint or the prebuilt gallery, upgrade it, and export it;
  • change how a mission works piece by piece: its playbooks, routing and formula rules, procedures, pages, gates and ontologies, with checkpoints to compare against and go back to;
  • keep several installations side by side and switch between them.

List and detail commands print a readable table on a terminal and the server's own JSON with --json.

Install

Download the file for your computer from https://www.studiox-ai.com/downloads:

Computer File
macOS, Apple silicon (M1 and later) missions-darwin-arm64
macOS, Intel missions-darwin-amd64
Windows, x64 missions-windows-amd64.exe
Windows, ARM missions-windows-arm64.exe
Windows, 32-bit missions-windows-386.exe
Linux, x64 missions-linux-amd64
Linux, ARM64 missions-linux-arm64

Verify the download

The downloads page lists a SHA-256 checksum for each file. Compare it with the checksum of the file you downloaded before you run it.

# macOS
shasum -a 256 missions-darwin-arm64

# Linux
sha256sum missions-linux-amd64
# Windows (PowerShell)
Get-FileHash .\missions-windows-amd64.exe -Algorithm SHA256

If the two values differ, delete the file and download it again over HTTPS from the downloads page.

macOS

cd ~/Downloads
mv missions-darwin-arm64 missions          # or missions-darwin-amd64 on Intel
chmod +x missions
xattr -d com.apple.quarantine missions     # clears the "downloaded from the internet" flag
sudo mv missions /usr/local/bin/           # or any folder on your PATH

The file is not signed with an Apple developer certificate. Without the xattr step, macOS stops the first run with "missions" cannot be opened because Apple cannot check it for malicious software, or the terminal prints killed. Instead of xattr you can Control-click the file in Finder, choose Open, then Open again; or, after a blocked run, open System Settings → Privacy & Security and click Open Anyway.

Windows

  1. Find your system type: Settings → System → About → System type.

    • x64-based processor → missions-windows-amd64.exe
    • ARM-based processor → missions-windows-arm64.exe
    • 32-bit operating system, x86-based processor → missions-windows-386.exe
  2. Rename the file to missions.exe and move it to a folder of its own, for example %LOCALAPPDATA%\Programs\missions.

  3. Add that folder to your PATH, then open a new terminal:

    $dir = "$env:LOCALAPPDATA\Programs\missions"
    $userPath = [Environment]::GetEnvironmentVariable("Path", "User")
    [Environment]::SetEnvironmentVariable("Path", "$userPath;$dir", "User")
    
  4. On first run, SmartScreen may show Windows protected your PC. Click More info → Run anyway. If there is no Run anyway, unblock the file first:

    Unblock-File "$env:LOCALAPPDATA\Programs\missions\missions.exe"
    

    (Or right-click the file → Properties → tick Unblock → OK.)

This app can't run on your PC means the file does not match your system type; download the one that does. If every one of them gives that message, Windows is in S mode, which runs only Store apps; switch out of S mode in Settings.

Linux

mv missions-linux-amd64 missions     # or missions-linux-arm64
chmod +x missions
sudo mv missions /usr/local/bin/     # or ~/.local/bin, or any folder on your PATH

Check that it runs

missions help
missions --base https://studiox.example.com version
missions CLI 3.1.7
IRIS 11.2.179  (2026-10-16T16:38:12Z)

version prints the CLI's version and the server's. It needs no token, only an address: before you sign in, give one with --base. After you sign in, missions version uses your installation.

Sign in

Which token to use

The CLI acts with a token. There are two kinds, and the CLI treats them the same way.

Personal token iris_pat_… Service token iris_svc_…
Acts as You A StudioX user made for the integration (a service user)
Made by Anyone, for themselves A business administrator
Made in Missions → Settings → API Access Missions → Settings → Service tokens
Chat, building agents, MCP tools, install, upgrade, export Work while your Studio sign-in is recent Always work; nobody needs to be signed in
Use it for Your own work at the terminal Scripts, CI jobs and anything that runs unattended

A token can be limited to scopes and given an expiry. A token with no scopes may do everything its user may do.

Scope What it allows in the CLI
runtime chat, trace, observations, decisions, decision, approve, reject, choose, watchers, watcher run / logs / push / reset, tables, rows, row (read), health, mcp servers / tools / run, gate trigger (without --pass/--fail), ontology query, ontology traverse
manage pause, activate, settings, set, and changing agents in the interactive session; reading how a mission works (playbooks, playbook get, rules, formula-rules, procedures, procedure get, pages, page get, gates, gate get, ontologies, ontology get / versions / diff / file / links, checkpoints, checkpoint compare); gate override, gate trigger --pass/--fail
build inspect, install, upgrade, export, blueprint; everything manage reads above, and every change to it: playbook / rule / procedure / page / gate / ontology add, set, rm, ontology restore, ontology links set, formula-rules set / test, procedure validate, checkpoint add / restore
data:write row add, row set, row rm

whoami, missions, status, agents, prebuilts, jobs, job, version and openapi work with any scope.

Two more rules come from your installation, not the token:

  • Edit rights. Changing how a mission is set up or built (anything under manage or build) also needs edit rights on that mission: you created it, it is shared with you for editing, or you are a business administrator. Running a mission (chat, approvals, watchers, records) needs only that you can see it.
  • Business administrators. Reading settings and reading or changing records are for business administrators, as on the Missions settings and Database pages.

A service user is usually made a business administrator for these reasons. To set one up, follow Missions → Settings → Service tokens on your installation; the token is shown once, when it is made.

Sign in with your browser

Each installation's Missions → Settings → API Access page shows the sign-in command for that installation, with its address filled in. Copy it and run it:

missions login -p prod --base https://studiox.example.com/missions
Opening your browser to log in…
  https://studiox.example.com/missions/cli-login?port=53122&state=…&device=…
Waiting for the browser to complete login (listening on http://127.0.0.1:53122/callback)…
✓ Logged in to studiox.example.com as you@example.com · profile prod · 6 missions

Your browser opens the installation's sign-in page. Sign in if asked; the page hands a personal token back to the CLI on your own machine (127.0.0.1), and the CLI saves it under the profile name you gave (prod).

--base takes the address in any form you have it: studiox.example.com, https://studiox.example.com, https://studiox.example.com/missions, or a link copied from any Missions page. The CLI keeps the scheme and host and adds /missions itself.

Without --base, missions login asks for the address and offers www.studiox-ai.com (or the address the profile already has) in brackets; press Enter to accept it. Without -p, it signs in the current profile, which is named default until you add others.

Paste a token instead

When no browser can open (for example over SSH), or nothing comes back within 90 seconds, the CLI prints ! Browser login unavailable: … and asks for a token:

Manual login:
  1. Open https://studiox.example.com/missions/settings
  2. Go to API Access -> Create token (a personal token, iris_pat_…)
     — or, for a system that runs on its own, have a business administrator
       make a service token under Service tokens (iris_svc_…; no browser sign-in needed)
  3. Paste the token here.

Token (iris_pat_… or iris_svc_…):

Set the address and token without a browser

configure asks for the address and a token and checks them:

missions configure -p prod --base https://studiox.example.com
Configuring profile prod
Token (personal iris_pat_… or service iris_svc_…): iris_svc_…
✓ Configured profile prod. Logged in as missions-api@example.com · 6 missions

Without --base it asks for the address too. Pressing Enter at either prompt keeps the profile's current value.

Check who you are

missions whoami
Profile  prod
Host     studiox.example.com
Email    you@example.com
Business Example Operations
Token    personal token (iris_pat_…) — acts as you
Scopes   all (no limit)
Role     business-admin
Missions 6
StudioX  ok

StudioX says whether chat, agents, MCP tools, install, upgrade and export will work now. When it is not ok, the line says what to do: sign in to Studio and open Missions once (personal token), or make a new service token with the service user's current API key (service token).

Environment variables for scripts and CI

Variable Effect
MISSIONS_BASE The installation's address, in any of the forms --base accepts. Overrides the profile's address.
MISSIONS_TOKEN A personal or service token. Overrides the profile's token.
NO_COLOR Any value turns off colours and the progress spinner.

With both MISSIONS_BASE and MISSIONS_TOKEN set, the CLI needs no config file and no sign-in:

MISSIONS_BASE=https://studiox.example.com MISSIONS_TOKEN="$TOKEN" missions whoami

Each variable replaces only its own value. MISSIONS_TOKEN on its own is sent to the address of whichever profile is selected, so set MISSIONS_BASE beside it.

Where your sign-in is kept

Profiles and their tokens are saved in .missions.json in your home folder (~/.missions.json on macOS and Linux, %USERPROFILE%\.missions.json on Windows). On macOS and Linux the file is written readable by you only (0600). It holds tokens; treat it as you treat any credential file.

{
  "current": "prod",
  "profiles": {
    "prod": {
      "base": "https://studiox.example.com/missions",
      "token": "iris_pat_…",
      "email": "you@example.com"
    }
  }
}

Local MCP servers you add with missions mcp add, and any headers you give them, are saved in the same file under their profile.

The interactive session keeps its command history in .missions_history in your home folder.

Sign out

missions logout            # the current profile
missions -p dev logout     # another profile

logout deletes the profile's token and keeps its address, so the next missions login -p dev offers the same installation. To revoke the token itself, delete it on the installation's Missions → Settings → API Access (or Service tokens) page. To forget a profile entirely, use missions profile rm (next section).

Several installations

Keep one profile per installation. A profile is a name, an address and a token.

Add your installations

missions login -p prod --base https://studiox.example.com
missions login -p dev  --base https://studiox-dev.example.com

Signing in to a profile also makes it the current one, so after these two commands dev is current.

missions login --base <host> without -p reuses a profile already signed in to that host; when there is none, it creates a profile named after the host (for example studiox-dev.example.com).

See them

missions profiles
   PROFILE  HOST                     EMAIL            TOKEN  SIGNED IN
   prod     studiox.example.com      you@example.com  pat    yes
*  dev      studiox-dev.example.com  you@example.com  pat    yes
* current · switch with: missions use <profile>

missions profiles checks every token against its installation at once, allowing four seconds each. SIGNED IN reads:

Value Meaning
yes The token works.
token rejected The installation answered 401: the token was revoked or has expired. Sign in again.
unreachable No answer within four seconds, for example an installation behind a VPN you are not on.
no token The profile has an address and no token (after logout).
not checked You passed --offline.

TOKEN is pat (personal), svc (service) or — (none). --json prints the same list as JSON.

Choose one

missions use prod                                  # make prod current; no new sign-in
missions -p dev decisions service-desk             # one command against dev
missions --base studiox-dev.example.com decisions service-desk   # the profile signed in to that host

-p and --base can go anywhere on the command line.

Remove one

missions profile rm dev           # asks first
missions profile rm dev --yes     # without asking

If you remove the current profile, the first remaining profile in alphabetical order becomes current.

Which installation a command uses

Exactly as the CLI decides, first match wins:

  1. MISSIONS_BASE and MISSIONS_TOKEN. Each replaces its own value on top of the profile chosen below. When MISSIONS_BASE is set, --base is ignored and the CLI prints MISSIONS_BASE is set, so --base is ignored.
  2. -p <profile> and --base <host>.
    • -p alone: that profile.
    • --base alone: the profile signed in to that host, the current profile first, then the others in alphabetical order. If none is, the command stops with no profile is signed in to <host> — run: missions login --base <host> -p <name>. version, openapi and help run against the host without a profile, and so does any command when MISSIONS_TOKEN is set.
    • -p with --base: the profile must be for that host; otherwise the command stops with profile <name> is for <its host>, not <host>. The CLI never sends a profile's token to a host it was not made for. (With login and configure, --base instead sets or changes the profile's address.)
  3. The current profile, which is the last one you signed in to, configured or chose with missions use; default when there is none.

Worked example: prod and dev

# once
missions login -p prod --base https://studiox.example.com
missions login -p dev  --base https://studiox-dev.example.com
missions use prod

# day to day: prod by default
missions decisions service-desk

# try a change on dev first
missions -p dev upgrade service-desk --blueprint blueprint.json --dry-run
missions -p dev upgrade service-desk --blueprint blueprint.json

# then the same change on prod
missions upgrade service-desk --blueprint blueprint.json --dry-run
missions upgrade service-desk --blueprint blueprint.json

The interactive session

Start it

missions               # the current profile
missions -p dev        # another installation

If the profile has no token, the sign-in runs first. The session then shows who you are and your missions:

StudioX Missions 3.1.7 — you@example.com · 6 missions
Type /help for commands, /quit to exit. Plain text chats with the current mission.

 1. Service Desk  [active]
     Triage and route incoming service requests
     id: 3f2a9c1e-6b4d-4e8a-9f10-2c7d5b8e4a61
 2. Refund Review  [paused]
     id: 8d1e4b7a-2c3f-4a9e-b5d6-0f1e2a3b4c5d
Select one with /use <n>.

[prod] no mission › /use 1
Using mission Service Desk
[prod] Service Desk ›

With one mission, it is selected for you. The prompt always shows the profile in brackets and the selected mission.

Chat

Anything you type that does not start with / goes to the selected mission:

[prod] Service Desk › which requests breached their SLA this week?
⠹ reasoning…
Service Desk: Four requests breached their SLA this week: …

The conversation continues across messages until you type /new. A reply can take minutes when the mission calls several agents and systems; the CLI waits up to five minutes for it. When a conversation has been handed to a person, the CLI prints This conversation is with a person. Your message was passed to them; the mission does not answer it. and does not wait. /trace shows how the last reply was reached: which agents and tools ran, and for how long.

Up and down arrows recall earlier lines. Ctrl-C clears the line; Ctrl-D or /quit ends the session.

Commands

Command What it does
/help, /? Show the command list
/missions List your missions (refreshes the list)
/use <n> Select mission number n
/whoami Profile, host, identity, token kind, scopes, role, StudioX sign-in
/version CLI and server version
/login Sign in again (for example after your Studio sign-in lapsed)
/logout Delete this profile's token and end the session
/agents The selected mission's agents (● on, ○ off)
/agent <n> <message> Chat with agent n directly
/agent-add Add an agent (asks for name, description, type vibe, mcp or knowledgebase, and resource)
/agent-edit <n> Change agent n's description, or switch it on or off
/mcp <n> Agent n's MCP servers
/mcp <n> on|off <id> Switch an MCP server on or off for agent n
/servers MCP servers: [business] and [local]
/tools <n> Tools on server n, read-only ones marked
/run <n> <tool> {json} Run a tool; asks before any tool that is not read-only
/mcp-add Add a local MCP server (asks for name, URL, headers)
/mcp-rm <name> Remove a local MCP server
/yes Turn the run-tool question off or back on
/kb <n> Agent n's knowledge documents
/kb-add <n> Add a knowledge document to agent n (asks for title and text)
/kb-rm <n> <id> Remove a knowledge document from agent n
/trace How the last reply in this session was reached
/observations The mission's watchers and recent agent runs, as JSON
/new Start a new conversation with the selected mission
/quit, /exit, /q End the session (also Ctrl-D)

For the selected mission (each runs the command of the same name described under Everyday tasks):

Command What it does
/status Status, agents, settings, what blocks activation
/health Is it working right now
/pause, /activate Pause or activate it
/settings Settings, values, integrations
/decisions [pending|resolved|all] Decisions (pending by default)
/decision <id> One decision, and who may approve it
/approve <id> [notes…] Approve; any words after the id are the notes
/reject <id> [notes…] Reject
/choose <id> <option> [notes…] Choose one of a decision's options
/watchers Watchers, on or off, last run
/watcher-run <w> [--reset] Run a watcher now
/watcher-logs <w> A watcher's log
/watcher-on <w>, /watcher-off <w> Switch a watcher on or off
/tables The mission's tables
/rows <table> [flags] Rows of a table; takes the same flags as missions rows
/row <table> <key> One row
/playbooks, /playbook <playbook> Playbooks; one playbook and its text (-o file saves it)
/rules, /formula-rules Routing rules; formula rules across its watchers
/procedures, /procedure <procedure> Procedures; one procedure and its checks
/pages, /page <page> Pages; one page and its spec as JSON (-o file saves it)
/gates, /gate <gate> Gates; one gate and the targets it has judged
/ontologies, /ontology <ontology> Ontologies; one ontology and sample triples
/checkpoints Checkpoints, and changes since the last one
/jobs Your install and upgrade jobs
/profiles Your profiles
/profile <name> Switch installation

Deleting a row and clearing a watcher's rows ask for confirmation, so they are available as commands outside the session only (missions row rm, missions watcher reset --clear-rows). Changes to how a mission works (playbook set, page set, checkpoint restore, …) are also run outside the session.

Switch installation inside the session

[prod] Service Desk › /profile dev
✓ Switched to dev — studiox-dev.example.com · 3 missions
Select one with /use <n> (see /missions).
[dev] no mission ›

Switching opens a new connection, clears the selected mission and starts new conversations. If MISSIONS_BASE or MISSIONS_TOKEN is set, the CLI warns that they still override the profile.

Everyday tasks

A <mission> is the mission's id, its slug, or its name when only one mission has that name (in quotes if it has spaces). When several missions share a name, the CLI lists their ids and slugs and asks for one of them. missions missions lists the missions you can see.

A <watcher> is its id, or its name when only one watcher in the mission has it.

Ask a mission a question

missions chat service-desk "Which requests breached their SLA this week?"

The reply goes to standard output and the conversation id to standard error, so a script can keep the reply alone:

reply=$(missions chat service-desk "Summarise today's open requests")

Each chat command starts a new conversation. To see how a reply was reached:

missions trace service-desk <conversationId>

Approvals

missions decisions service-desk                         # pending, 25 a page
missions decisions service-desk --status resolved --page 2
missions decisions service-desk --status all --page-size 100
 1. [pending] Refund over limit — Refund 4,200.00 for order SO-88121
     Damaged on delivery; the amount is above the automatic refund limit
     id: 6b0d2f4e-91a7-4c3b-8e52-7d4f0a1c9e33 · 2026-10-16 09:12 PDT · from watcher Refund sweep · options: approve, reject
1–1 of 1 · your role: approver

Inspect one before you answer it:

missions decision service-desk 6b0d2f4e-91a7-4c3b-8e52-7d4f0a1c9e33
Decision   Refund 4,200.00 for order SO-88121
Event      Refund over limit
Why        Damaged on delivery; the amount is above the automatic refund limit
Status     pending
Id         6b0d2f4e-91a7-4c3b-8e52-7d4f0a1c9e33
Requested  2026-10-16 09:12 PDT
From       watcher Refund sweep
Options    approve, reject
Amount     4200
Approvers  approver, finance-lead
Your role  approver — within your limit

Answer it, with notes that are kept in the mission's history:

missions approve service-desk 6b0d2f4e-… --notes "Photos confirm the damage"
missions reject  service-desk 6b0d2f4e-… --notes "Outside the return window"
missions choose  service-desk 6b0d2f4e-… escalate --notes "Needs the account manager"

choose takes an option id from the Options line. Decisions that carry their own options are answered with choose; the others with approve or reject.

The mission's approval limits apply exactly as in the approvals queue:

  • A decision above your limit shows above your approval limit — route to … in the list, and approving it is refused with the limit named.

  • A decision that needs a second approver records yours and says what is still needed:

    ✓ Your approval is recorded. Approval 1 of 2 recorded. A different person must approve before it runs.
    
  • A decision you prepared, or one you have already approved, is refused for you with the reason (You prepared this; someone else must approve it.).

Watchers

missions watchers service-desk
 1. ● Refund sweep  (poll · every 15m · tool list_refunds)
       last run 2026-10-16 09:00 PDT · ok · 2 findings · 40 rows
       id: 0a4c7e19-5d2b-4f86-a3c1-9e7b6d5f4a20
 2. ○ Ticket intake  (webhook)
       not run yet
       id: 5e93b1d0-7c4a-4a2e-8f6b-1d0c3e2a9b84

Run one now, and follow its log:

missions watcher run  service-desk "Refund sweep"
missions watcher logs service-desk "Refund sweep"
missions watcher logs service-desk "Refund sweep" --level warn --since 2026-10-16T16:00:00Z --limit 200

A run's results land in decisions, the mission's tables and its activity feed. Log lines at info and debug are kept for an hour, warn and error for a day.

Make a watcher look at everything again (it forgets its checkpoint):

missions watcher run   service-desk "Refund sweep" --reset    # clear the checkpoint and run now
missions watcher reset service-desk "Refund sweep"            # clear it; the next scheduled run starts over
missions watcher reset service-desk "Refund sweep" --clear-rows

--clear-rows also deletes every row in the watcher's table and cancels the pending decisions on them. It asks first; --yes skips the question.

Switch a watcher on or off:

missions watcher enable  service-desk "Ticket intake"
missions watcher disable service-desk "Ticket intake"

Push rows from a file or another program

A watcher triggered by a webhook takes rows you send it:

missions watcher push service-desk "Ticket intake" tickets.json
your-export-command | missions watcher push service-desk "Ticket intake" -

The JSON is an array of rows, an object holding them under the watcher's rows key, or a single row. Up to 500 rows a call; a row sent twice is stored once. The CLI prints the server's answer.

[
  { "ticket_id": "T-1042", "site": "Plant 2", "severity": "major", "raised_at": "2026-10-16T16:05:00Z" }
]

Records

Reading and changing records needs a business administrator. Changing them also needs a token with data:write. A mission marked sensitive, or one whose design does not allow its data to leave it, does not open its records to the CLI.

missions tables service-desk
 1. requests  212 rows · 6 columns
     request_id text, status text, priority text, opened_at timestamptz, owner text, notes text

List rows, with filters, sorting, search and paging:

missions rows service-desk requests
missions rows service-desk requests --filter status=open --filter priority=high
missions rows service-desk requests --sort opened_at --desc --page-size 100
missions rows service-desk requests --search "Plant 2" --page 3
request_id  status  priority  opened_at                  owner
REQ-1188    open    high      2026-10-16T15:41:00.000Z  j.rivera
REQ-1187    open    high      2026-10-16T14:02:00.000Z
rows 1–2 of 2 · --json for full values

Each cell is cut at 32 characters in the table and an empty value prints as nothing; --json gives full values. Pages hold 50 rows unless you set --page-size.

Read, add, change and delete single rows. The JSON can be given inline, as a file path, or as - for standard input:

missions row     service-desk requests REQ-1188
missions row add service-desk requests '{"request_id":"REQ-1200","status":"open","priority":"low"}'
missions row set service-desk requests REQ-1188 '{"status":"closed"}'
missions row set service-desk requests REQ-1188 changes.json
missions row rm  service-desk requests REQ-1188
Delete the row REQ-1188 from requests? [y/N] y
✓ Deleted REQ-1188 from requests (rows deleted: 1).

row rm asks first; --yes skips the question. Writes follow the same rules as the mission's own agents: only the mission's columns, never a credential column, and every change recorded in the mission's history.

On Windows, quoting JSON on the command line differs between PowerShell and Command Prompt. Put the JSON in a file and pass the file's path.

Status, health, pause and activate

missions status service-desk
Mission  Service Desk
Status   paused
Id       3f2a9c1e-6b4d-4e8a-9f10-2c7d5b8e4a61
Slug     service-desk
Agents   4 (4 on)
Settings 5 defined · 3 required · 2 set
Timezone America/Los_Angeles
Changed  2026-10-16 08:55 PDT
Ready    no
  • setting Escalation inbox (escalation_inbox) → missions set service-desk escalation_inbox=…

Ready lists what blocks activation, each with the command that fixes it.

missions health service-desk

health prints an overall green, amber or red, the live checks and readiness checks behind it, and anything it could not measure.

missions pause    service-desk
missions activate service-desk

Activation is refused while a required setting is empty:

✗ Some required settings are still empty. [HTTP 400 invalid_request]
  missing settings: Escalation inbox (escalation_inbox)
  fill them with: missions set service-desk escalation_inbox=…

Fill them with missions set and activate again.

Settings and secrets

missions settings service-desk

This lists every setting with its key, label, type, value and whether it is required, the integrations with whether their credentials are set, and what blocks activation.

Save settings with key=value. A value that is a number, a true/false or a list goes after := as JSON:

missions set service-desk escalation_inbox=service-escalations@example.com
missions set service-desk escalate_after_minutes:=30 notify_on_close:=true
missions set service-desk sites:='["Plant 1","Plant 2"]'

Credentials for an integration go in --secret integration.key=value, repeated as needed:

missions set service-desk --secret ticketing.username=svc-missions --secret ticketing.password='…'

Secrets can be written but are never shown back. When the mission sends settings changes to review, the CLI prints the change request it filed instead, and nothing changes until it is approved:

→ Sent for review as change request #12. Nothing has changed yet.

Install a mission

Look at a bundle first. inspect lists the connections and settings it asks for, each with the flag that answers it:

missions inspect service-desk.sxm
Bundle   Service Desk (service-desk)
About    Triage and route incoming service requests
Contents 4 agents · 2 watchers · 5 settings · bundle v3 · exported 2026-10-10 11:20 PDT
Connections to answer
  • Ticketing · needs credentials → --bind ticketing=<MCP serve URL>
Settings to answer before it can be activated
  • escalation_inbox (Escalation inbox, email) → --set escalation_inbox=…

If a mission from this bundle is already installed, inspect names it and, when the bundle carries a blueprint, prints the upgrade command that updates it in place.

Install it, connect it, fill its settings and credentials, and switch it on, in one job:

missions install service-desk.sxm --name "Service Desk" \
  --bind ticketing=https://mcp.example.com/ticketing/mcp \
  --set escalation_inbox=service-escalations@example.com \
  --secret ticketing.password='…' \
  --enable-watchers --activate

Other sources:

missions prebuilts                                    # the Prebuilt Missions gallery, with each install command
missions install --prebuilt <id>
missions install --blueprint blueprint.json

The CLI follows the job and prints each step as it finishes, then the result: the new mission's id and status, the settings and credentials still empty (with the missions set command for each), and any findings.

  ✓ Read the bundle
  ✓ Create the mission from the bundle  service-desk: 1 table(s)
  ✓ Write settings  1 setting(s)
  ✓ Create the integration servers  1 server(s), 2 watcher(s) wired
  ✓ Build the agents' bots and wiring
  ✓ Turn watchers on  Refund sweep, Ticket intake
  ✗ Activate the mission  Required settings are empty: escalation_inbox
✓ Installed Service Desk [draft]
  id: 3f2a9c1e-6b4d-4e8a-9f10-2c7d5b8e4a61  slug: service-desk
Settings to fill before it can be activated:
  • Escalation inbox (escalation_inbox) → missions set 3f2a9c1e-… escalation_inbox=…

If activation is refused for an empty setting, the mission is still installed; fill the setting and run missions activate.

Flag Meaning
--name N Name of the new mission
--slug S Slug of the new mission
--bind slug=URL Point the bundle's connection slug at an MCP server URL (repeatable)
--set key=value A setting; key:=<json> for a typed value (repeatable)
--secret integration.key=value A credential (repeatable)
--enable-watchers Switch the watchers on
--activate Activate the mission when nothing blocks it
--no-wait Print the job id and return at once
--allow-duplicate Install even though a mission of the same name is already installed. Without it, install stops and names the missions upgrade that updates the one you have
--json Print the job's result as JSON

Upgrade a mission

Always run a dry run first. It shows what would change and changes nothing:

missions upgrade service-desk newer.sxm --dry-run
missions upgrade service-desk newer.sxm

Other sources:

missions upgrade service-desk --dry-run                          # to the newer listed bundle it came from
missions upgrade service-desk
missions upgrade service-desk --blueprint blueprint.json --dry-run
missions upgrade service-desk --blueprint blueprint.json

An upgrade only adds: new tables, columns, settings, watchers, agents and knowledge; pages are rebuilt. Your records, decisions and setting values are never touched. Anything the new design no longer has is reported under findings and left in place. New watchers arrive switched off; switch them on with missions watcher enable.

--no-finalize leaves out the step that builds the agents' bots and wiring.

Export a mission and its blueprint

missions export service-desk                       # service-desk.sxm, without records
missions export service-desk --data -o service-desk-with-data.sxm
missions blueprint service-desk -o blueprint.json  # without -o it prints the blueprint

A bundle installs on another installation with missions install. A blueprint is the mission's design as JSON; edit it and feed it back with missions upgrade <mission> --blueprint blueprint.json, or install a new mission from it with missions install --blueprint. Both accept the file exactly as blueprint -o saved it.

Change how a mission works

These commands change a mission's design one piece at a time, without editing and upgrading the whole blueprint:

  • playbooks — the policy text its watchers follow;
  • routing rules — which agent a message goes to, by keyword, before the reasoning model decides;
  • formula rules — the fn:classify and fn:formula steps in its watchers;
  • procedures — step-by-step work its agents carry out;
  • pages — the pages of its portals;
  • gates — status checks it posts on pull requests and commits;
  • ontologies — vocabularies its agents read;
  • checkpoints — its configuration at a moment, to compare against and go back to.

Reading them needs a token with manage or build; changing them needs build and edit rights on the mission. A locked mission refuses changes with locked; its business super-admin can unlock it. Every change is recorded in the mission's history, as one made in Missions is.

A <playbook>, <procedure>, <gate> or <ontology> is its id, or its name when only one has it. A <page> is its key (portal/page, as missions pages shows it), its id, or its label. A routing rule has no name: give its id from missions rules.

The JSON for add and set is given inline, as a file path, or as - for standard input; with nothing given and something piped in, standard input is read.

Take a checkpoint before a change

missions checkpoint add service-desk --label "before the escalation change"
✓ Took checkpoint 5 (before the escalation change).
Compare later: missions checkpoint compare service-desk --from 5 · go back: missions checkpoint restore service-desk 5

A checkpoint holds the mission's configuration: agents, watchers, playbooks, pages, gates and knowledge. It does not hold records or decisions, and restoring one never touches them.

Export a playbook, edit it, set it back

missions playbooks service-desk
missions playbook get service-desk "Escalation policy" -o escalation.json
# change "content" (or "name", "description") in escalation.json
missions playbook set service-desk "Escalation policy" escalation.json
 1. Escalation policy  (used by 2 watchers · changed 2026-10-10 03:00 PDT)
     When to page the on-call engineer
     id: 22222222-2222-4222-8222-222222222222
✓ Wrote escalation.json (365 bytes)
✓ Saved the playbook Escalation policy. Watchers that link it follow the new text on their next run.

The file keeps the updatedAt the playbook had when you exported it, and set sends it back. When someone changed the playbook in between, nothing is saved:

✗ The playbook was not saved: someone changed it since you read it (…).
  Read it again with `missions playbook get service-desk 22222222-… -o playbook.json`, make your change on that copy, and set it again —
  or pass --force to overwrite their change.

Inline JSON sends only the fields you give ('{"content":"…"}'); the CLI reads the playbook first so the same check applies. --force saves without the check.

missions playbook add service-desk '{"name":"Refund policy","content":"Refund orders under 50 without approval."}'
missions playbook rm  service-desk "Refund policy"

playbook rm asks first, and is refused while any watcher still links the playbook; nothing is deleted then.

Add a routing rule

missions rule add service-desk '{"keywords":["refund","chargeback"],"agent_name":"Billing"}' --priority 10
missions rules service-desk
✓ Added the rule "refund", "chargeback" → Billing (any)
 1. ● "refund", "chargeback" → Billing (any)  (keyword_route · priority 10)
       id: 33333333-3333-4333-8333-333333333333
Higher priority is tried first; the first rule that matches picks the agent.

match_mode is any (the default: one keyword is enough), all, or regex (each keyword is a regular expression). A message no rule matches is routed by the reasoning model, as before.

missions rule set     service-desk 33333333-… '{"keywords":["refund"],"agent_name":"Billing","match_mode":"all"}'
missions rule set     service-desk 33333333-… --priority 20
missions rule disable service-desk 33333333-…
missions rule rm      service-desk 33333333-…

Change a formula rule

missions formula-rules service-desk
missions formula-rules service-desk --json > rules.json
# keep the one entry you want to change, and change its "expr"
missions formula-rules test service-desk rules.json
missions formula-rules set  service-desk rules.json
 1. Risk → risk  (fn:formula · watcher Tickets step 2 · table tickets)
     IF(amount > threshold, 'high', 'low')
     reads threshold=500
row   would get  holds now  error
Acme  high       low
Beta                        unknown column x
Result works · 1 of 2 rows failed

test shows what each current row would get and saves nothing. set runs the same test first and saves nothing when the expression works for none of the rows. It is refused when the watcher's step has changed since you read it (the entry's into is the check); read the rules again, or pass --force. Saving needs a business administrator.

Edit a page's spec

missions pages service-desk
missions page get service-desk ops/overview -o overview.json
# change "spec" in overview.json
missions page set service-desk ops/overview overview.json
✓ Saved the page ops/overview. Everyone who opens it sees the new version.

As with playbooks, the file keeps the page's updatedAt, and set refuses to overwrite a page someone saved since you read it (--force does). set also takes the spec alone ({"title": …, "blocks": […]}). --mine reads and saves your own copy of the page and leaves the shared page as it is.

missions page add service-desk --label "Open cases" --id open-cases --portal ops
missions page add service-desk page.json      # { pageLabel, pageId?, portalSlug?, portalLabel?, spec? }
missions page rm  service-desk ops/open-cases

A page added without a spec starts with the mission chat.

Procedures

missions procedures service-desk
missions procedure get      service-desk "Refund request" -o refund.json
# change "definition" (roles, steps) or the wiring in refund.json
missions procedure validate service-desk "Refund request" refund.json
missions procedure set      service-desk "Refund request" refund.json
missions procedure set      service-desk "Refund request" --enable

validate checks the edited copy against the mission's agents before you save it, and --ai adds an advisory review. set --enable is refused while something stands between the procedure and going live, and lists what. Changing the steps of a procedure copied from the library stops it following library updates; set says so. The server has no "changed since you read it" check for procedures: a save replaces what is there.

procedure get and validate reach the mission's agents, so a personal token needs a recent Studio sign-in (a service token always works).

missions procedure add service-desk '{"procedureId":"<library procedure id>","version":null}'   # copy from the library; null follows its updates
missions procedure add service-desk '{"name":"Warranty claim","description":"warranty and repair requests"}'   # a draft written here
missions procedure rm  service-desk "Warranty claim"

Gates

missions gates service-desk
missions gate get service-desk "Impact gate"
missions gate add service-desk '{"name":"Impact gate","statusCheckContext":"ci/impact","sourceMcpSlug":"gitlab"}'
missions gate set service-desk "Impact gate" '{"triggerEvent":"pr.synchronize"}'

Run a gate against a pull request, or override it:

missions gate trigger  service-desk "Impact gate" 42 --sha 3f9c2e1 --pass --summary "No impacted tests"
missions gate override service-desk "Impact gate" 42 --reason "Hotfix approved by the release manager"

trigger without --pass or --fail applies the default verdict, which fails the target. With --sha the status check is posted on that commit; without it only the gate's record of the target changes. override asks first, then posts a passing status check naming you and the reason.

Ontologies

missions ontology add   service-desk sid.ttl --name "TM Forum SID"
missions ontologies     service-desk
missions ontology get   service-desk "TM Forum SID"
missions ontology query service-desk "TM Forum SID" subclasses tmf:Resource --depth 2
missions ontology query service-desk "TM Forum SID" predicate rdfs:label --limit 50
missions ontology rm    service-desk "TM Forum SID"

The format (ttl, owl, owlxml, rdfxml, jsonld, nt, trig) comes from the file name unless --format says otherwise, and an .owl file is read as what it holds (RDF/XML, OWL/XML or Turtle); files up to 25 MB. A JSON-LD file carries its own @context: a context at a web address is refused, never fetched. A file that does not parse is refused with the parser's message, line number included. query asks subject <uri>, predicate <uri> [<object>], subclasses <classUri> or properties <classUri>.

Adding a file under a name the mission already has makes the next version of that ontology; the mission reads the newest from its next question, and the file you uploaded is kept:

missions ontology add      service-desk sid-2026-10.owl --name "TM Forum SID"   # → version 2
missions ontology versions service-desk "TM Forum SID"
missions ontology diff     service-desk "TM Forum SID" --from 1                  # classes and properties added, removed, changed
missions ontology file     service-desk "TM Forum SID" -o sid.owl                # the file as uploaded
missions ontology restore  service-desk <version-id>                             # an earlier version, current again as a new one

Tables linked to the model, and how records are connected

Say which of the mission's tables holds which kind of thing, and which columns point at another record. Save the links as a list:

[
  { "table": "routers", "class": "Router", "key": "router_id", "label": "hostname",
    "columns": [{ "column": "site_id", "property": "located at", "link": "sites" }] },
  { "table": "sites", "class": "Site", "key": "site_id", "label": "name" }
]
missions ontology links service-desk                           # the links, and what no longer fits
missions ontology links service-desk set links.json --dry-run  # check without saving
missions ontology links service-desk set links.json
missions ontology links service-desk --json > links.json       # edit and set it back

A class, property, table or column that does not exist, or a link to a table that is not linked, refuses the save with every problem listed; a property the model defines for another class is saved with a warning.

Then ask how records are connected. With a question, the AI plans the walk and code runs it; the plan it ran is printed so you can run the same walk again with no AI:

missions ontology traverse network-impact "Which customers are affected if router PE-SEA-01 goes down?"
missions ontology traverse network-impact --plan '{"start":{"table":"routers","key":"PE-SEA-01"},
  "path":[{"via":"dependsOn","direction":"in","maxHops":3},{"via":"serves","direction":"out"}],"target":"Customer"}'

Each thing reached is printed with its path, for example pe1.sea1 (PE-SEA-01) ⟵ depends on ⟵ Northwind internet access (SVC-1001) ⟶ serves ⟶ Northwind Traders (CUST-01). out follows the record's own link column; in finds the records whose link names it. A walk reads only.

Compare and restore a checkpoint

missions checkpoints service-desk
missions checkpoint compare service-desk --from 5            # checkpoint 5 against the mission now
missions checkpoint compare service-desk --from 4 --to 5
missions checkpoint restore service-desk 5
3 configuration changes since checkpoint 5 (2026-10-16 06:10 PDT).
#  label                         kind    by        taken
5  before the escalation change  manual  j.rivera  2026-10-16 06:10 PDT
4  Checkpoint 4                  daily   system    2026-10-16 00:00 PDT
Compare 5 before the escalation change → now
playbooks:
  ~ Escalation policy
      content: Page on P1. → Page on P1 and P2.
1 changes
Put the configuration of service-desk back to checkpoint 5? A checkpoint of the configuration now is taken first. [y/N] y
✓ Restored the configuration to checkpoint 5.
  • playbooks Escalation policy content put back
Undo it with: missions checkpoint restore service-desk 6

Restoring needs a business administrator and asks first. It takes a checkpoint of the configuration as it is now, so the restore can be undone with the number it prints, and it lists anything it did not put back and why.

Jobs

Install and upgrade run as jobs on the server. The CLI follows a job until it ends, for up to 60 minutes.

missions jobs                                 # your jobs, newest first
missions jobs --mission service-desk
missions job <jobId>                          # status, steps, result
missions job <jobId> --wait                   # follow it to the end
STARTED               KIND             STATUS     MISSION                               JOB
2026-10-16 09:30 PDT  upgrade-mission  succeeded  3f2a9c1e-6b4d-4e8a-9f10-2c7d5b8e4a61  5e0c8a12-…
2026-10-15 17:02 PDT  create-mission   succeeded  3f2a9c1e-6b4d-4e8a-9f10-2c7d5b8e4a61  91b4d7e0-…

A job's status is queued, running, succeeded or failed.

Scripts and CI

Output for programs

--json prints the server's own JSON, in the server's key order, on these commands: profiles, decisions, decision, watchers, watcher logs, tables, rows, row, status, health, settings, prebuilts, inspect, install, upgrade, jobs, job, playbooks, playbook get, rules, formula-rules, formula-rules test, procedures, procedure get, procedure validate, pages, gates, gate get, gate trigger, gate override, ontologies, ontology get, ontology query, ontology versions, ontology diff, ontology links, ontology traverse, checkpoints, checkpoint compare, checkpoint restore. observations, blueprint and page get always print JSON; playbook get, procedure get and page get save it to a file with -o. chat prints the reply alone on standard output.

Messages such as ✓ Wrote … and the conversation id of chat go to standard error. Colours and the spinner are off when output is not a terminal, or when NO_COLOR is set.

Exit codes

Code When
0 The command succeeded. Also when you answered no to a confirmation (cancelled is printed).
1 Anything failed: the server refused the request (any HTTP error), the network failed, a job ended failed or ran past 60 minutes, an argument or flag was wrong, or a confirmation was needed with no terminal and no --yes. The message is on standard error.
2 Unknown command, or unknown mcp subcommand.

Confirmations

row rm, watcher reset --clear-rows, profile rm, the rm of every part (playbook, rule, procedure, page, gate, ontology), gate override, ontology restore and checkpoint restore ask before they act. With no terminal they refuse with this needs confirmation: run it in a terminal, or pass --yes and exit 1; pass --yes in scripts.

mcp run asks before any tool that is not read-only. Without a terminal it reads the answer from standard input; no y means the tool does not run and the command exits 0. Pass --yes in scripts.

Long operations

By default install and upgrade wait for their job and exit 0 on success, 1 on failure, with --json printing the job's result. To start a job and check on it later:

missions install --prebuilt "$PREBUILT_ID" --no-wait
# ✓ Job 5e0c8a12-… (create-mission) is queued.
# Follow it with: missions job 5e0c8a12-… --wait

missions job 5e0c8a12-… --json        # {"job": {"status": "running", "steps": [...], ...}}
missions job 5e0c8a12-… --wait        # blocks until it ends; exit 1 if it failed

Rate limit

Each token may make 600 requests a minute. Above that, the server answers rate_limited and the CLI prints how long to wait:

✗ Too many requests: 600 a minute. Retry after 23s. [HTTP 429 rate_limited]
  hint: over 600 requests a minute for this token — wait 23s and retry

The CLI does not retry on its own; a script that loops over many missions or rows should pause and retry on exit code 1 when this message appears. Commands that take a mission name or slug look the mission up first (one extra request); passing the mission's id saves it.

A sample CI job

Keep a service token in your CI system's secret store (here STUDIOX_SERVICE_TOKEN). Make it with only the scopes the job needs, for example build and runtime for the job below.

#!/bin/sh
set -eu

export MISSIONS_BASE="https://studiox.example.com"
export MISSIONS_TOKEN="$STUDIOX_SERVICE_TOKEN"
export NO_COLOR=1

missions whoami

# show what would change, then apply the change
missions upgrade service-desk --blueprint blueprint.json --dry-run
missions upgrade service-desk --blueprint blueprint.json --json > upgrade-result.json

# fail the job unless the mission is healthy afterwards
missions health service-desk --json > health.json
overall=$(python3 -c 'import json; print(json.load(open("health.json"))["overall"])')
[ "$overall" = "green" ] || { echo "health is $overall"; exit 1; }

The same commands run in a scheduled job; chat and decisions --json let a scheduler ask a mission a question or report what waits for approval.

MCP servers from the CLI

missions mcp lists and runs tools on two kinds of MCP server, in one numbered list:

  • [business] servers are the ones connected to your business on the installation. The installation holds their credentials and makes the call. These need the runtime scope and a usable StudioX sign-in.
  • [local] servers are MCP endpoints you add yourself. The CLI talks to them directly over HTTP; their URL and any headers you give are saved in your profile in .missions.json.
missions mcp servers                                   # numbered; also: mcp ls, mcp list
missions mcp tools 2                                   # by number or by name
missions mcp run 2 search_orders --args '{"q":"refund"}'
missions mcp run ticketing close_ticket --args '{"id":"T-1042"}' --yes
missions mcp add localtools https://mcp.internal.example.com/mcp --header 'Authorization: Bearer …'
missions mcp rm localtools
 1. [business] Ticketing  [active]
 2. [local] localtools  https://mcp.internal.example.com/mcp

A tool marked (read-only) runs at once. Any other tool prints the server, tool and arguments and asks Run this tool? [y/N]; --yes skips the question. Results print as text when the tool returns text, otherwise as JSON. --header (or -H) can be repeated. mcp add and mcp rm work without signing in.

Troubleshooting

Every error starts with ✗, gives the server's message, the HTTP status and the error code in brackets, and a hint: line on what to do.

Errors from the server

Code What the CLI prints What to do
HTTP 401 Unauthorized — please log in [HTTP 401]
hint: the token is missing, unknown, revoked or expired — run `missions login`, or make a new one (Missions → Settings → API Access for a personal token, Service tokens for a service token)
Sign in again with missions login, or replace the token in MISSIONS_TOKEN. A revoked token stops working within a minute.
studiox_session_stale Personal token: The StudioX session behind this personal token has expired. Sign in to Studio and open Missions once, or use a service token. (or There is no StudioX session behind this personal token yet. …)
Service token: This service token has no usable StudioX credential. Make a new service token with the service user's current API key.
See Expired Studio sign-in.
scope_missing This token is not allowed "build". Make a token with that scope. [HTTP 403 scope_missing]
hint: make a token with scope build (Missions → Settings → API Access or Service tokens)
Make a token that includes the named scope; the scope table shows which commands need which.
forbidden You can see this mission but not change it: ask its creator or a business administrator to share it with you for editing. [HTTP 403 forbidden] or Business administrators only. [HTTP 403 forbidden]
hint: your role does not allow this — ask a business administrator, or use a token whose user holds the role
For the first, ask the mission's creator or a business administrator to share the mission with you for editing. For the second, have a business administrator run it, or use a service token whose user is one.
locked This app is locked: only a business super-admin can change how it works. You can still use it, change its settings and connections, and assign people to roles. [HTTP 403 locked]
hint: the mission is locked against this kind of change — a business super-admin can unlock it
Settings, connections and people still work. For a change to how it works, ask a business super-admin to unlock it.
conflict … [HTTP 409 conflict]
hint: someone changed it since you read it, or it is in a state that refuses this — read it again, then retry
Read it again (status, decision, row), check what changed, and retry. For playbook set and page set the CLI says so in its own words: read the playbook or page again, make your change on that copy, and set it again, or pass --force.
invalid_request The server's message, then missing settings: or setting errors: when it names them; otherwise hint: the request was refused as written; `missions openapi` has every request shape Fix what the message names. For activation, fill the settings listed.
not_found hint: check the id or name — `missions missions` lists the missions this token can see Check the id, slug or name. A service token sees only its own business's missions.
rate_limited Too many requests: 600 a minute. Retry after 23s. [HTTP 429 rate_limited] Wait the seconds shown, then retry.
upstream_error hint: a connected system (an MCP server) refused or failed — check the mission's connections Check the connected system and the mission's connections (missions health).
internal hint: the server failed — retry, and report it with the time if it repeats Retry. If it repeats, report it with the time and the command.

The CLI also names missions and watchers it cannot find before it calls the server: no mission matches "…" — `missions missions` lists the ones this token can see, no watcher matches "…" — `missions watchers <mission>` lists them.

Expired Studio sign-in

A personal token acts as you, and chat, agent changes, MCP tools, install, upgrade and export reach StudioX with your Studio sign-in. When that sign-in lapses, these commands stop with studiox_session_stale; everything else keeps working. missions whoami shows it on the StudioX line, and the interactive session warns when it starts.

  • Personal token: sign in to Studio in your browser and open Missions once, then run the command again.
  • For work that runs unattended, use a service token; it needs no browser sign-in.
  • Service token: its service user's API key was generated again in Studio, which retires the old one. Have a business administrator make a new service token with the current key.

Sign-in problems

What you see What to do
! Browser login unavailable: could not open a browser … No browser on this machine (for example over SSH). Paste a token at the prompt, or use missions configure.
! Browser login unavailable: no callback within 1m30s The browser sign-in did not finish within 90 seconds. Paste a token at the prompt, or run missions login again.
state nonce mismatch (possible CSRF) — aborting The answer that reached the CLI was not from the sign-in it started. Run missions login again.
token saved, but verification failed: … The token was saved, but the installation refused it or could not be reached. Read the error after the colon.
profile prod is not signed in (run `missions login -p prod`, or see `missions profiles`) Sign in that profile.
no base URL configured (run `missions login` or set MISSIONS_BASE) version or openapi with no profile yet; add --base <host> or sign in.
missions profiles shows unreachable The installation did not answer within four seconds: connect to its network or VPN, or check the address.

Proxies and certificates

  • Proxy. The CLI uses the proxy named in HTTPS_PROXY (and HTTP_PROXY for plain HTTP addresses), and skips it for hosts listed in NO_PROXY. This applies to the installation and to local MCP servers.
  • Company certificate authority. The CLI trusts the certificates your operating system trusts. On macOS, add your company's root certificate to the System keychain and mark it trusted; on Windows, import it into Trusted Root Certification Authorities. On Linux, add it to the system certificate bundle, or point SSL_CERT_FILE at a bundle file (or SSL_CERT_DIR at a folder) that includes it.
  • There is no option to turn certificate checking off. A certificate the CLI does not trust shows as an error ending in x509: certificate signed by unknown authority.
  • Each request gives up after 120 seconds. A chat reply is awaited for up to five minutes; past that the CLI stops with timed out waiting for the mission to reply (300s). Ask again, or break the question into smaller ones.

Warnings about an unsigned file

The CLI is not code-signed.

  • macOS: cannot be opened because Apple cannot check it for malicious software, or killed in the terminal: run xattr -d com.apple.quarantine <path to missions>, or Control-click → Open → Open, or System Settings → Privacy & Security → Open Anyway.
  • Windows: Windows protected your PC: More info → Run anyway; if that button is missing, Unblock-File <path to missions.exe>.
  • Windows: This app can't run on your PC: download the file for your system type; if every file gives it, switch Windows out of S mode.

Command reference

Usage: missions [-p <profile>] [--base <host>] [command] [args…]. With no command, the interactive session starts (after sign-in if the profile has none).

Value flags also take the form --flag=value. -- ends the flags; everything after it is an argument. An unknown flag is an error.

Global flags

Flag Meaning
-p, --profile <name> Use this profile for the command. With login and configure, the profile to create or change.
--base <host> Use the profile signed in to this host. With login and configure, the address of the profile.

Environment

Variable Meaning
MISSIONS_BASE Address of the installation; overrides --base and the profile
MISSIONS_TOKEN Token (iris_pat_… or iris_svc_…); overrides the profile's token
NO_COLOR Turn off colours and the spinner
HTTPS_PROXY, HTTP_PROXY, NO_PROXY Proxy settings
SSL_CERT_FILE, SSL_CERT_DIR Linux: extra trusted certificates

Sign-in and installations

Command Flags What it does
login Sign in with the browser, or paste a token
logout Delete the profile's token, keep its address
configure Set the address and a token at prompts, then check them
whoami (also me) Profile, host, email, business, token kind, scopes, role, mission count, StudioX sign-in
profiles --offline, --json Your profiles: host, email, token kind, signed in, current
use <profile> Make a profile current
profile rm <profile> (also remove, delete) --yes, -y Remove a profile and its token
version CLI and server version; needs no token
help (also -h, --help) The command list

Missions and chat

Command Flags What it does
missions List your missions
chat <mission> "<message>" Send a message, wait, print the reply
agents <mission> A mission's agents
observations <mission> The mission's watchers and recent agent runs, as JSON
trace <mission> <conversationId> How a reply was reached
mcp <subcommand> MCP servers and tools (below)

Run a mission

Command Flags What it does
decisions <mission> --status, -s pending|resolved|all (default pending); --page N; --page-size N (default 25); --json What waits for a person
decision <mission> <decisionId> --json One decision, and who may approve it
approve <mission> <decisionId> --notes, -n "…" Approve
reject <mission> <decisionId> --notes, -n "…" Reject
choose <mission> <decisionId> <optionId> --notes, -n "…" Choose one of a decision's options
watchers <mission> --json Watchers, on or off, last run
watcher run <mission> <watcher> --reset Run now; --reset clears its checkpoint first
watcher reset <mission> <watcher> --clear-rows; --yes, -y Clear its checkpoint; --clear-rows also deletes its rows (asks first)
watcher logs <mission> <watcher> (also log) --level L; --phase P; --since ISO-time; --limit N; --json Its log, oldest first
watcher enable <mission> <watcher> (also on) Switch it on
watcher disable <mission> <watcher> (also off) Switch it off
watcher push <mission> <watcher> [file.json | -] (also events) Push rows into a webhook watcher; reads standard input when no file is given
tables <mission> --json Tables, columns, row counts
rows <mission> <table> --filter, -f col=value (repeatable); --sort col; --desc; --search text; --page N; --page-size N (default 50); --json Rows of a table
row <mission> <table> <key> --json One row by its key
row add <mission> <table> <json|file|-> Add a row
row set <mission> <table> <key> <json|file|-> Change a row
row rm <mission> <table> <key> (also delete, remove) --yes, -y Delete a row (asks first)

Manage a mission

Command Flags What it does
status <mission> --json Status, agents, settings, what blocks activation
health <mission> --json Green, amber or red checks
pause <mission> Pause it
activate <mission> Activate it; refused while a required setting is empty
settings <mission> --json Settings, values, integrations, readiness
set <mission> key=value… --secret integration.key=value (repeatable) Save settings; key:=<json> for a number, true/false or list

Change how a mission works

Command Flags What it does
playbooks <mission> --json Playbooks, how many watchers use each
playbook get <mission> <playbook> --output, -o file.json; --json One playbook and its text; -o saves it to edit
playbook add <mission> [json|file|-] Create one: { name, description?, content }
playbook set <mission> <playbook> [json|file|-] --force Change it; refused when someone changed it since you read it, unless --force
playbook rm <mission> <playbook> --yes, -y Delete it (asks first); refused while a watcher links it
rules <mission> --json Routing rules, on or off, by priority
rule add <mission> [json|file|-] --priority N Add one: a rule, or just its params { keywords, agent_name, match_mode? }
rule set <mission> <ruleId> [json|file|-] --priority N Change one
rule enable|disable <mission> <ruleId> (also on, off) Switch one on or off
rule rm <mission> <ruleId> --yes, -y Delete one (asks first)
formula-rules <mission> --json Every fn:classify / fn:formula step and the settings it reads
formula-rules set <mission> [json|file|-] --force Change one rule's expression; tested on the current rows first
formula-rules test <mission> [json|file|-] --json What each current row would get; saves nothing
procedures <mission> --json Procedures, state, origin, steps
procedure get <mission> <procedure> --output, -o file.json; --json One procedure, its checks, what blocks it going live
procedure add <mission> [json|file|-] Copy one from the library { procedureId, version? }, or write one { name, … }
procedure set <mission> <procedure> [json|file|-] --enable, --disable; --track-latest, --no-track-latest Save the mission's copy, switch it, or follow library updates
procedure validate <mission> <procedure> [json|file|-] (also check) --ai; --json Check it, or an edited copy of it, against the mission's agents
procedure rm <mission> <procedure> --yes, -y Remove it (asks first)
pages <mission> --json Pages you can see, with their keys
page get <mission> <page> --output, -o file.json; --mine The page and its spec, as JSON
page add <mission> [json|file|-] --label L; --id ID; --portal slug; --portal-label L; --spec spec.json Add a page
page set <mission> <page> [json|file|-] --mine; --force Replace its spec; refused when someone saved it since you read it, unless --force
page rm <mission> <page> --yes, -y Delete it (asks first)
gates <mission> --json Gates, on or off, how many targets each blocks
gate get <mission> <gate> --json One gate and every target it has judged
gate add <mission> [json|file|-] Add one: { name, statusCheckContext, sourceMcpSlug, verdictTool?, triggerEvent?, descriptionTemplate?, active? }
gate set <mission> <gate> [json|file|-] Change one
gate rm <mission> <gate> --yes, -y Delete one and its target states (asks first)
gate trigger <mission> <gate> <target> (also run) --sha SHA; --pass, --fail; --summary "…"; --json Run it against a pull request or reference
gate override <mission> <gate> <target> --reason "…" (required); --yes, -y; --json Mark the target overridden and post a passing check (asks first)
ontologies <mission> --json Ontologies and their sizes
ontology get <mission> <ontology> --json One ontology, its prefixes and 20 sample triples
ontology add <mission> <file> (also upload) --name N; --format F; --description "…" Upload and parse one (up to 25 MB)
ontology rm <mission> <ontology> --yes, -y Delete it and its triples (asks first)
ontology query <mission> <ontology> subject|predicate|subclasses|properties <uri> [<object>] --limit N; --depth N; --json Ask it one question
ontology versions <mission> <ontology> (also history) --json Every kept version, newest first
ontology diff <mission> <ontology> (also compare) --from N; --to N; --json What changed between two versions (default: the one before the current)
ontology restore <mission> <version-id> --yes, -y Make an earlier version current again, as a new version (asks first)
ontology file <mission> <ontology> (also download) -o file (- for standard output) The file as uploaded
ontology links <mission> (also mappings) --json The tables linked to the model
ontology links <mission> set <file.json|-> --dry-run Replace the links (checked first)
ontology traverse <mission> "<question>" (also connected) --plan <json|file|->; --json How records are connected, each with its path
checkpoints <mission> --json Checkpoints, newest first, and changes since the last
checkpoint add <mission> (also take) "label", or --label, -l "…" Take one now. The label can follow the mission name or come with --label; give one, not both
checkpoint compare <mission> (also diff) --from N (required); --to M|live (default live); --json What changed between two, or since one
checkpoint restore <mission> <N> --yes, -y; --json Put the configuration back (asks first; takes a checkpoint of now first)

Build and move missions

Command Flags What it does
prebuilts --json The Prebuilt Missions gallery
inspect <bundle.sxm> --json What a bundle asks before install
install <bundle.sxm> | --blueprint file.json | --prebuilt id --name N; --slug S; --bind slug=URL; --set key=value; --secret integration.key=value; --activate; --enable-watchers; --no-wait; --json; --allow-duplicate Install a mission (one source only). Stops when a mission of the same name is already installed and names the upgrade to run; --allow-duplicate installs a second copy
upgrade <mission> [bundle.sxm | --blueprint file.json] --dry-run; --no-finalize; --no-wait; --json Upgrade; with no source, to the listed bundle it came from
export <mission> --data; --output, -o file.sxm (- for standard output) Download the mission as a bundle
blueprint <mission> --output, -o file.json The mission's blueprint; printed when no file is given
openapi --output, -o file.json The installation's API description (OpenAPI 3.1); needs no token
jobs --mission, -m <mission>; --page N; --page-size N (default 25); --json Your jobs, newest first
job <jobId> --wait, -w; --json One job: status, steps, result

MCP

Command Flags What it does
mcp servers (also ls, list) Business and local MCP servers, numbered
mcp tools <server> A server's tools; <server> is its number or name
mcp run <server> <tool> --args '<json>'; --yes, -y Run a tool; asks before tools that are not read-only
mcp add <name> <url> --header, -H 'Key: Value' (repeatable) Add a local MCP server to the profile
mcp rm <name> (also remove) Remove a local MCP server
mcp help The MCP command list

Version history

3.1.7 · Oct 19, 2026

Ontologies: upload in more formats and keep versions (list, compare, restore, download the file), link your tables to the model, and ask how records connect with missions ontology traverse.

3.1.6 · Oct 19, 2026 · Maintained

Install stops when a mission of the same name already exists and names the upgrade to run (--allow-duplicate installs a copy). checkpoint add takes the label after the mission name. A refused watcher push no longer says someone changed it.

3.1.5 · Oct 16, 2026 · Maintained
  • Run, manage and build missions from a terminal or a script; several installations under named profiles; personal and service tokens.
  • Change how a mission works: playbooks, rules, formula rules, procedures, pages, gates, ontologies and checkpoints.
  • Every earlier version is out of support: update to 3.1.5.
2.x · Apr 1, 2026 · End of support

The Missions CLI 2 line, released April 2026. End of support — update to 3.1.5.

1.x · Nov 1, 2025 · End of support

The first Missions CLI line, released November 2025. End of support — update to 3.1.5.

All platforms

PlatformFileSizeSHA-256
macOS (Intel)missions-darwin-amd648.2 MBc3f309fd95cf4d2e8824e7dbac438c46ceca3826ee1324e2ac4f5b14ad7d31a2
macOS (Apple silicon)missions-darwin-arm647.6 MB45a82ba9e9cd662e1aa8e9d14c0be930dbb609547f7cc0b684591c558b985c99
Linux x64missions-linux-amd648.1 MBba2c00e046788f081f43dd06b82d9a8371ec069014432d533a4022ab7ee54343
Linux arm64missions-linux-arm647.5 MBa9bb8ca0e4a1348141a04707e56fd0e37de4bb9741fbb947b5086a3503194e26
Windows 32-bitmissions-windows-386.exe8.1 MB6a67a4f46b79a5b9897d7946a716fb8a9b6e18f928f1854ead9fcb8341423523
Windows x64missions-windows-amd64.exe8.3 MB2255ce1f0361968caec0c7377d1acda37aeb1d63e7984f435aa93b0f33975aca
Windows arm64missions-windows-arm64.exe7.6 MBa59d16820d38243f9752b547e428952077e839fd54256220ca23cdd309d32e9d

SHA256SUMS

Check the file is ours

Compare the file's SHA-256 with the one listed for it before you run it.

# macOS / Linux
shasum -a 256 <file>

# Windows (PowerShell)
Get-FileHash <file> -Algorithm SHA256

Related

  • A2A CLI — Talk to a mission — or any A2A (Agent2Agent) agent — from a terminal: read its card, send messages, stream answers.
  • Missions API — Run, manage and build missions from your own code over HTTP: tokens, every endpoint, errors, jobs, worked examples.