Docs CLI 0.4.0

The Milagre CLI

milagre runs the same host as the desktop app, without a window. Use it to keep agents running on a server or a spare Mac, pair your phone from a terminal, and script every Chat, Project and Worktree with the operations the app itself uses.

On this page

Install

You need Node.js 24 or newer, Git, and at least one coding agent CLI installed and signed in on the same computer: Claude Code (claude auth login) or Codex (codex login). Milagre uses that login; there is no Milagre account.

Run it once with npx:

npx milagre serve

Or install the command globally:

npm install --global milagre
milagre --version

Quick start

  1. Start the server. It stays in the foreground and prints a pairing link and, in a terminal, a QR code for your phone.

    milagre serve --project /absolute/path/to/project
  2. On your phone, open Milagre's pairing screen and scan the QR. On another desktop, open Settings › Phone & sharing › Add computer and paste the link.

  3. A desktop waits for your approval. From a second terminal on the server:

    milagre devices pending
    milagre devices allow KEY
  4. Check on it, then stop it when you are done. Stopping saves running work.

    milagre status
    milagre stop

Pairing links grant access to your agents. Keep them private: they expire after 10 minutes, and milagre pair opens a new window.

Profiles

Everything the server keeps (Projects, Chats, paired devices) lives in its profile, ~/.milagre/server by default. Pick another with --data-dir /absolute/path or MILAGRE_DATA_DIR, and use the same one for every command: status, devices and the rest talk to the server that owns that profile.

The CLI profile is separate from the desktop app's. Don't open the same Project in two hosts at once. The server runs with your account's permissions and the agent sign-ins on that computer.

Run an always-on server

serve never installs a startup service. Run it from your service manager (launchd, systemd, a tmux session) with --no-pair, so restarts keep paired devices without printing links or opening a pairing window:

milagre serve --no-pair --project /srv/code/api --project /srv/code/web

Ctrl+C or SIGTERM saves and stops the server. Devices you paired before reconnect after a restart. Add --no-qr to print links without terminal QR codes, for logs.

Phones and desktops reach the server through Milagre's encrypted relay, so no public port is needed. On the same network they connect directly.

Pair phones and desktops

milagre pair                 # open a new 10-minute pairing window
milagre devices list         # paired phones and computers
milagre devices pending      # computers waiting for approval
milagre devices allow KEY    # approve one
milagre devices deny KEY     # reject one
milagre devices remove KEY   # unpair and close its connections

While serve runs, it prints each waiting computer with the exact allow command to approve it.

Connect to other computers

A server can pair with other Milagre computers and call them, the way the desktop's Computers list does. Saved credentials are encrypted with a key file you keep outside the profile, so the server reconnects after a restart with no desktop or keychain unlocked.

milagre computers setup-key "$HOME/.config/milagre-secrets/computer.key"
milagre computers enable
milagre computers add 'milagre://pair?...' --name Studio
milagre computers list
milagre computers rename COMPUTER_ID 'Build server'
milagre computers invoke --input '["COMPUTER_ID","project:registry",[]]'
  • add waits until the other computer's owner approves. computers cancel-add cancels it; computers remove ID forgets a computer and disconnects it.
  • setup-key creates a random 32-byte key if the file doesn't exist, or checks an existing one. The file must be private to your account (0600, in a 0700 folder; protected ACLs on Windows). Keep it out of profile backups. MILAGRE_COMPUTER_KEY_FILE selects a provisioned key instead.
  • Credentials are stored with AES-256-GCM in computer-vault.json and never printed. A missing or wrong key fails without touching existing pairings.
  • Desktop pairings migrate when the updated desktop opens. To use a desktop profile unattended, run setup-key while that desktop has it unlocked: it exports the same key to your file.
  • Only a local owner can manage computers. Paired peers and phones can't.

Drive the app from a terminal

Besides the built-in commands, the CLI exposes the 409 operations the desktop and phone use, generated from the app's own types. An operation's name becomes words: project:registry is milagre project registry. See them all under command families.

milagre command list                     # every operation the running host offers
milagre help project                     # one family's operations (works offline)
milagre help chat send                   # one operation's flags and types
milagre command describe chat:send --json

milagre project registry
milagre project open --folder /absolute/path/to/project
milagre chat patch --project-path /absolute/path/to/project --session-id 1 --patch '{"title":"Review"}'
  • Pass inputs as named flags, or the whole input with --input: inline JSON, @/path/to/input.json, or - for standard input. Older positional arrays still work.
  • Numbers, booleans, arrays and objects take JSON values in flags. Fields that clash with a global flag use --arg-input, --arg-chat, --arg-channel or --arg-version.
  • Unknown flags and invalid inputs fail before anything runs. Results print as JSON.
  • A timeout can leave a change still running. Check the state before you retry.

milagre request METHOD '[...]' calls a daemon method with a raw JSON argument array, for methods the named commands don't cover:

milagre request project:open '["/absolute/path/to/project"]'
milagre request chat:runs

Run commands as a Chat

Agents in Milagre call tools such as tasks_set and delegate. The CLI runs those same commands, through the same dispatcher MCP uses, when you name an existing Chat with --chat. They keep that Chat's identity, its Project grants, approvals and permission mode.

milagre command list --chat '/absolute/path/to/project#1'
milagre command describe tasks_set --chat '/absolute/path/to/project#1'
milagre command run tasks_read --chat '/absolute/path/to/project#1'
milagre tasks read --chat '/absolute/path/to/project#1'

A Chat's identity is its Project path and number, projectPath#id. What command list --chat returns depends on the Chat and your settings; these are the groups:

Tasks

tasks_readtasks_settask_updatephase_set

Chats

chat_listchat_readchat_searchchat_createchat_startchat_stopchat_updatechat_respondchat_set_mode

Delegation and Links

delegatedelegation_detachconclude_negotiationlinked_overviewlinked_gitread_linked_chatread_linked_filesearch_linked_files

Projects and Worktrees

project_listproject_addproject_accountsproject_set_accountworktree_listworktree_createworktree_removeworktree_linkworktree_unlink

Designs and artifacts

design_listdesign_readdesign_showdesign_applydesign_validatedesign_inspectdesign_exportdesign_deletedesign_kit_readdesign_kit_saveartifact_showartifact_readartifact_listartifact_commentsartifact_resolve_commenthtml_previewhtml_render

Browser

browser_listbrowser_openbrowser_navigatebrowser_snapshotbrowser_clickbrowser_fillbrowser_typebrowser_pressbrowser_selectbrowser_hoverbrowser_scrollbrowser_waitbrowser_screenshotbrowser_evaluatebrowser_consolebrowser_uploadbrowser_attachbrowser_detachbrowser_commentsbrowser_resolve_comment

Simulators and desktop apps

simulator_listsimulator_attachsimulator_detachdesktop_appsdesktop_snapshotdesktop_finddesktop_actdesktop_pressdesktop_launchdesktop_waitdesktop_screenshot

Routines and Linear

heartbeat_createroutine_listroutine_createroutine_updateroutine_run_nowroutine_deletelinear_searchlinear_issuelinear_filelinear_commentlinear_create_issuelinear_update_issue

Advisors and secrets

create_advisoradvisor_readadvisor_followupadvisor_stopadvisor_providersrequest_secret

Watch events and script sessions

milagre watch prints a snapshot, then live events, as newline-delimited JSON. It subscribes before it reads the snapshot and drops events the snapshot already covers, so you miss nothing in between.

milagre watch
milagre watch --chat '/absolute/path/to/project#1' --channel agent:event

Ctrl+C disconnects the viewer; agents keep running. If the connection drops, run it again for a fresh snapshot.

milagre session keeps one owner connection open for a script. Write one request per line and read results and events back:

$ milagre session
{"id":1,"method":"project:registry","args":[]}
{"id":1,"result":[...]}
{"type":"event","channel":"...","payload":{...}}

Failures come back as {id, error}. At end of input it waits for the requests it accepted. Browser and simulator viewer controls last as long as the connection. Session is owner access: agents use mcp serve --stdio and never this transport, and never to reach your Terminals.

Connect an MCP client

Create a connection in the desktop's MCP settings, then point any MCP client at:

milagre mcp serve --stdio

It reads MILAGRE_MCP_URL and MILAGRE_MCP_TOKEN from that connection, forwards JSON-RPC over standard input and output to the host already running on this computer, and grants only that connection's scope. It never starts a host or grants owner access.

Desktop actions

When the desktop app is running on the same profile, the CLI can reach its native actions too: editors, windows, updates and notifications. They are listed under desktop in command list.

milagre desktop editor list
milagre desktop update state

Without a connected desktop they return CAPABILITY_UNAVAILABLE. They are never replayed after a disconnect.

Triage a problem

When the desktop app won't start, or its own Triage an issue entry doesn't work:

npx milagre triage
milagre triage --agent codex

It starts Claude Code or Codex in your terminal with a triage playbook and a file of machine facts: OS, Node, agent CLIs, and each Milagre profile's host status, log and lock. The agent reads the logs and the Milagre source for your version, searches known issues, and can help you write a GitHub issue. It asks before it changes anything or posts.

The files go in triage/ inside the profile. With no agent CLI installed, it prints their paths so you can paste them into any agent.

Built-in commands

The same text as milagre help COMMAND.

serve

Run the server without a desktop UI and print pairing details.

milagre serve [flags]

Flags

--project <path>
Open a Project on startup. Can be repeated.
--no-pair
Keep existing device access without opening a pairing window.
--no-qr
Print pairing links without terminal QR codes.
milagre serve
milagre serve --project /path/to/project
milagre serve --no-pair

Runs in the foreground. Ctrl+C or SIGTERM saves and stops the server.

pair

Open a new pairing window for phones and other desktops.

milagre pair [flags]

Flags

--no-qr
Print pairing links without terminal QR codes.
milagre pair
milagre pair --no-qr

Pairing lasts 10 minutes. Approve computers with milagre devices allow KEY.

status

Show the running server's status as JSON.

milagre status [flags]
milagre status

stop

Save running work and stop the server.

milagre stop [flags]
milagre stop

devices

List, approve and remove paired devices.

milagre devices <command> [key] [flags]

Commands

list
List paired devices.
pending
List computers waiting for approval.
allow <key>
Approve a waiting computer.
deny <key>
Reject a waiting computer.
remove <key>
Remove a paired device and close its connections.
milagre devices pending
milagre devices allow KEY
milagre devices list

computers

Manage connections to other Milagre computers from the owning daemon.

milagre computers <command> [arguments] [flags]

Commands

list
List saved computers and their connection state.
setup-key <file>
Create or select a private 32-byte key file for unattended access.
add <link> [--name NAME]
Pair with a computer. Its owner must approve.
rename <id> <name>
Change a saved computer's local label.
remove <id>
Remove a saved computer and disconnect it.
enable | disable
Persist whether the daemon connects to saved computers.
cancel-add
Cancel the pending pairing request.
invoke --input JSON
Call a remote method with [computerId, method, args].
milagre computers setup-key /private/path/milagre-computer.key
milagre computers enable
milagre computers add 'milagre://pair?...' --name Studio
milagre computers list

Keep the key file separate from profile backups. A desktop can unlock its existing OS-sealed key; setup-key exports that unlocked key for unattended use. Existing pairings migrate when the updated desktop opens. Paired remote clients cannot manage this owner's computer connections.

command

Discover product operations or run the same scoped commands as MCP.

milagre command <list|describe NAME|run NAME> [flags]

Commands

list
List owner operations, or scoped commands with --chat.
describe <name>
Describe a command and its input schema with --chat.
run <name>
Run a scoped command. Requires --chat.
milagre command list
milagre project registry
milagre command list --chat '/project#1'
milagre command run tasks_read --chat '/project#1'
milagre chat patch --input '["/project",1,{"title":"Review"}]'

Product RPC names map to words: designs:enabled:read becomes milagre designs enabled read. Inputs use the existing positional JSON contract. Scoped commands use their published object schema and preserve agent permissions.

request

Call a daemon method and print its result as JSON.

milagre request <method> [JSON_ARGS] [flags]

Arguments

method
Daemon method to call, such as project:open or chat:runs.
JSON_ARGS
Arguments as a JSON array. Defaults to [].
milagre request project:open '["/path/to/project"]'
milagre request chat:runs

watch

Stream a snapshot followed by live events as newline-delimited JSON.

milagre watch [flags]

Flags

--chat <chat>
Filter events to one Chat.
--channel <name>
Filter event channels. Can be repeated.
milagre watch
milagre watch --chat '/project#1' --channel agent:event

Ctrl+C disconnects the viewer. Running agents keep working. Reconnect after a dropped connection for a fresh snapshot.

session

Keep an owner connection open for scripted commands and viewer controls.

milagre session

Read newline-delimited {"id":1,"method":"project:registry","args":[]} from stdin. Writes {id,result}, {id,error} and live {type:"event",...} records. EOF waits for accepted commands. Viewer capabilities last for this connection. Owner access only; MCP clients use mcp serve --stdio.

mcp

Connect an MCP client to an existing scoped connection.

milagre mcp serve --stdio

Flags

--stdio
Forward JSON-RPC over standard input and output.

Uses MILAGRE_MCP_URL and MILAGRE_MCP_TOKEN from the connection created in MCP settings. Never grants owner access or starts another host.

desktop

Run a native command in a connected desktop using the same profile.

milagre desktop <family> <action> [flags]
milagre desktop editor list
milagre desktop computers list
milagre desktop update state

Desktop entries appear in command list while connected. Headless hosts return CAPABILITY_UNAVAILABLE. Native handlers, encrypted credentials and user settings stay in their owning desktop.

triage

Investigate a Milagre problem on this computer with claude or codex, and help file a good issue.

milagre triage [flags]

Flags

--agent <claude|codex>
Agent CLI to use. Default: ask when both are installed.
npx milagre triage
milagre triage --agent codex
milagre triage --data-dir /absolute/profile

Works when the desktop app won't start. Writes the playbook and machine facts to a triage folder in the profile, then starts the agent there. It asks before it changes anything or posts an issue.

help

Show all commands or help for a specific command.

milagre help [command]

Arguments

command
Command to describe. Omit it to show all commands.
milagre help
milagre help serve
milagre serve --help

Command families

409 operations in 75 families. Run milagre help FAMILY COMMAND for one operation's flags and types; it works without a running server. Families under desktop need the desktop app connected.

milagre accounts9

scopesscopeassignlistaddselectlogincancelremove

milagre advisor2

stopretry

milagre agent11

modelscli-statusprovider-updatesupdate-cliinterruptrespond-permissionanswer-questiondismiss-suggestionset-permission-modeportsstop-port

milagre app2

versionset-keep-awake

milagre app-update6

auto readauto savestatecheckinstallactivity

milagre artifact12

sharing-statusall-page-sharesrevoke-saved-page-sharepage-sharesshare-pagerevoke-page-sharegetassetlistdeleteadd-commentscomments

milagre attachment3

previewreadupload

milagre babysit2

settings readsettings save

milagre browser16

listattachdetachopenframestatuscontrolinputcloseopen-pagepage-urlrelease-page-urlkeep-page-urlpanel-pagessign-inssign-ins clear

milagre browser-comments3

addlistsend-from-page

milagre canvas8

snapshotlink-addlink-removechat-modelink-restorelinksworktree-positionopen-project

milagre chat25

sendsend-statusresumereloadqueue-sendqueue-removelimit-switchlimit-resumelimit-resume cancelpatchdeletedetacharchive-subagentarchive-finished-subagentsgit-noteset-openrunsmessagemessagessearchsubagenttask-outputportsinboxall-messages

milagre chats2

homeensure

milagre checkpoint3

listpreviewrestore

milagre command3

listdescriberun

milagre computer1

resources read

milagre computer-use5

settings readsettings savestatusguideframe

milagre computers17

invokelistpreviewaddcancel-addrenameremoveset-enabledrememberrecallnotevault-statusbrowser-proxybrowser-pagesunlocksetup-keyimport-keys

milagre context2

settings readsettings save

milagre daemon8

statussnapshotsnapshot-pageresult-pageflushstopfocusstate-patches

milagre delegation5

targetspreparereceivereportscollected

milagre designs2

enabled readenabled save

milagre desktop3

registerrespondinvoke

milagre device-notes2

readsave

milagre devices8

listremoveacknowledgependingallowdenytake-noticesconfirm-notices

milagre dictation2

contextpolish

milagre done2

settings readsettings save

milagre files-to-copy3

readpreviewsave

milagre folder-repos2

detect readdetect save

milagre fs1

list-dirs

milagre git8

changeshistorydiff-filesdiff-filegeneratecommitpushopen-pr

milagre keybindings4

readset-commandreset-commandreset

milagre limits4

auto-switch readauto-switch saveresume-at-reset readresume-at-reset save

milagre linear9

statusconnectdisconnectenabled readenabled savemove-to-started saveissuesworktree-issuescancel

milagre link9

listcreateupdatedelete-checkdeleteopensnapshotsendworkspace-roots

milagre linked5

grantsnapshotremote-enabled readremote-enabled savestop-negotiation

milagre live-activity4

stateopenanswerforget

milagre local-mcp7

statuscreateupdaterotaterevokeenableClientdisableClient

milagre main-sync4

readsavedefault readdefault save

milagre mcp9

accountscheckdefinitionsavesaveUrlremovetogglesignIncancelSignIn

milagre media1

read

milagre onboarding4

agent-folderscreatecloneinit-git

milagre peer1

routes

milagre phone5

statusset-enabledset-lanresetopen-pairing

milagre pr15

detaildiff-filesdiff-filecommentreplydelete-commentsubmit-reviewresolve-threadmergereadyimagelabelsset-labelsreviewer-candidatesrequest-reviewers

milagre project20

filesbranchesimageset-iconcurrentopenrecentscan-childrenknownset-hiddenreadregistrypositionswitchforgetplain-rootsnapshotchat-imageworktree-pathsfind

milagre project-git2

readsave

milagre pull-requests2

snapshotopen

milagre push3

registerunregisterfocus

milagre routines13

enabled readlistupdatedeleterun-nowflow-actflow-testcreatetargetslinear-optionshookrotate-hookenabled save

milagre scope1

retry-save

milagre simlock6

settings readsettings saveidentitymodelsleaserelease

milagre simulator11

listattachdetachopenframeofferstatuscontrolinputrepairclose

milagre skills2

listread

milagre state1

read

milagre storage2

worktreesremove-worktree

milagre terminal8

profilessetShelllistopenreadinputresizeclose

milagre token-usage1

read

milagre triage1

prepare

milagre usage4

readcachedaccounts readaccounts cached

milagre worktree9

createlink-issueunlink-issuerootsstatusremoverefresh-diffspull-requestpull-requests

milagre worktree-setup2

readsave

milagre desktop app10

dictation-canceldictation-downloaddictation-open-settingsdictation-preparedictation-removedictation-statusdictation-transcribeopen-keybindings-fileretry-quitversion

milagre desktop app-icon2

getset

milagre desktop artifact-preview2

registerrelease

milagre desktop browser-panel4

captureclear-sign-inspagesremote-partition

milagre desktop editor2

listopen

milagre desktop floating-inbox18

closecountdock-expandeddrag-begindrag-enddrag-movedrag-overlayheightis-openopen-chatplacementpreviewpreview-keyselectselectedsettingssnapshottoggle

milagre desktop image3

copymenusave

milagre desktop notification2

completedstate

milagre desktop project4

choose-folderopenopen-atreveal

milagre desktop runtime2

connectionrestart-host

milagre desktop settings5

floating-inboxnotification-chimenotification-schedulenotify-when-waitingwindow-background

milagre desktop skills2

openreveal

milagre desktop update6

channelcheckinstallrelease-notesset-channelstate

Global flags

--data-dir <path>
Absolute profile path. Defaults to MILAGRE_DATA_DIR, then ~/.milagre/server.
--input <JSON|@file|->
The command's whole input: inline JSON, a JSON file, or standard input.
--chat <projectPath#id>
An existing Chat, for scoped commands and watch.
--json
Machine-readable output, including errors.
--help, -h
Help for the command.
--version, -v
The CLI version.

Environment

MILAGRE_DATA_DIR
Profile path when --data-dir is not given. Must be absolute.
MILAGRE_COMPUTER_KEY_FILE
Private key file for saved computer credentials, instead of the one setup-key saved.
MILAGRE_MCP_URL, MILAGRE_MCP_TOKEN
The scoped connection mcp serve --stdio uses. Set by the MCP connection you create.
NO_COLOR
Plain help text. Help is also plain when piped or when TERM=dumb.

Output and errors

Results print as JSON on standard output. A failure prints its message on standard error and exits with status 1. With --json, the failure prints as JSON instead, so scripts can read it:

{"error":{"code":"COMMAND_FAILED","message":"..."}}

Something not covered here? Run milagre help, read the CLI source, or open an issue.