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
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
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.
A desktop waits for your approval. From a second terminal on the server:
milagre devices pending
milagre devices allow KEY
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.
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.
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.
Show the running server's status as JSON.
milagre status [flags]
milagre status
Save running work and stop the server.
milagre stop [flags]
milagre stop
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
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.
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.
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
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.
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.
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.
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.
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.
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.