Miilo CLI

See what your agents are doing without opening another dashboard.

Miilo CLI observes selected existing sessions locally, or connects to an optional self-hosted/managed Miilo API. Standalone observation needs no account, CE process, Miilo URL, or listening HTTP service.

miilo local discover /path/to/project
miilo local setup /path/to/project
miilo local run
# In another terminal:
miilo local doctor
miilo local snapshot
miilo local explain PROVIDER/WORK_ID

Local observation adapters cover Codex, Cursor, Claude Code, OpenCode, Devin CLI, Grok CLI and Hermes on Linux/macOS. See the compatibility matrix for version-qualified live validation. See the compatibility and validation boundaries. Discovery does not start or resume work; import is explicit. Bootstrap history appears idle. Only sanitized assistant summaries/tool names are projected, not user messages, reasoning or tool inputs/outputs. This is activity observation, not authoritative execution or approval detection. The CLI remains read-only. Windows supports the remote command set; native local file observation is not yet qualified there.

For remote CE/managed observation, explicitly configure MIILO_URL and a private MIILO_TOKEN_FILE, then use doctor, connections list, work list/show/explain and watch. Watching subscribes before its fresh snapshot; events invalidate state and reconnects always obtain a fresh baseline.

Use Miilo from a phone

Read phone and remote setup before connecting a launcher. Run the observer where the sessions live; configure a reachable Miilo endpoint on the phone. Tailscale provides a route, not Miilo or Codex credentials. A standalone local collector does not automatically expose a remote API. For optional direct read-only pairing without CE, see pair computers.

Install

The native Rust binary is the default:

# macOS and Linux
brew tap miilo-ai/cli
brew install miilo-ai/cli/miilo

# macOS or Linux without Homebrew
curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/miilo-ai/miilo-cli/releases/latest/download/miilo-cli-installer.sh | sh

Windows releases include a PowerShell installer, MSI, and ZIP. A true Node.js implementation is also maintained in packages/miilo-cli-node/ for environments that standardize on Node 20.19 or newer. Both implementations install the same miilo command, so install one globally.

Let your agent help

The miilo-connect skill guides a terminal-capable assistant through version checks, explicit local selection or an optional authenticated remote connection. It never extracts another agent's credentials or starts work to populate a demonstration. Download packaged installers from GitHub Releases.

Remove or reinstall

See removal and retained data before uninstalling a client or collector. Integration removal, package removal and private-data purge have different scopes. Shared observer services must be handled explicitly.

Runtime and state

The public miilo-local library contains small read-only discovery/transcript adapters. miilo invokes it directly; miilo-local is a compatibility executable for native widgets. The Node CLI delegates local commands to that same executable (PATH or MIILO_LOCAL_EXECUTABLE); remote commands remain implemented in Node.

Selected configuration lives at $XDG_CONFIG_HOME/miilo/local.json (or ~/.config/miilo/local.json), overridable with MIILO_LOCAL_CONFIG. Version 2 stores mode: local, snapshotFile, sessions and groups, with no URL/token. The atomic owner-only runtime cache defaults to $XDG_STATE_HOME/miilo/snapshot.json or ~/.local/state/miilo/snapshot.json. It is not durable history. A cache older than 15 seconds is rejected. One collector per configuration is allowed. Native Linux import owns miilo-local-desktop.service; terminal run stops on Ctrl+C without touching agents. Existing version-1 CE configurations stay explicit remote publication mode and are not silently migrated or overwritten.

The SDK runtime owns provider isolation, validation, aggregation, deduplication and bounded event history. CE consumes the same core. The committed SDK dependency pins a full source revision in the public SDK repository; ordinary source reads do not require a private repository token.

Repository map

Path	Purpose
crates/miilo-client	Rust HTTP, authentication, snapshots, explanations, and resumable SSE
crates/miilo-cli	Native miilo and miilo-local executables
crates/miilo-local	Standalone local session adapters and composition
packages/miilo-cli-node	Portable Node.js implementation of the same read-only commands
packaging/aur	Arch Linux and Omarchy package template

Build it

make test
make smoke

Tests include both implementations, a packed npm installation, and an authenticated user journey against a deterministic mock API. Local development next to miilo-sdk uses the sibling checkout; clean releases resolve the pinned SDK commit.

Releases

A v* tag creates GitHub Release artifacts for Apple Silicon and Intel macOS, ARM64 and x86-64 Linux, and x86-64 Windows. The release includes checksums, provenance, shell and PowerShell installers, MSI, and a generated Homebrew formula. The Node package is attached as a tested workflow artifact until npm publishing is explicitly enabled.

See docs/RELEASE.md before tagging.

Apache-2.0. The license does not grant rights to the Miilo name or marks.

Credential files

Prefer MIILO_TOKEN_FILE=/path/to/private/token or --token-file /path/to/private/token over token contents in arguments. Rust and Node accept the same protected-file configuration and reject credential-bearing endpoint URLs and redirects. Legacy MIILO_TOKEN remains supported; do not set both methods. Restart a running client after token rotation. See CE credential operations for provisioning, rotation, transport and current single-operator limits.

For the release-to-VM checklist, see Omarchy acceptance. Commands that depend on public assets remain gated until those assets exist.

Release automation

See .github/RELEASING.md for private-repository rehearsals, manifest-driven tags, credential-missing skips and activation. Publication stays disabled until explicitly requested/configured.

watch --json in version 0.2 emits NDJSON records with type: snapshot, reason: bootstrap|event, and an authoritative snapshot. This replaces the old raw-event watch output. Library consumers needing raw resumable events can still call MiiloClient.stream; observe provides reconciled snapshots.

Architecture checks

The engineering constitution defines the boundaries. Run python3 tools/check_architecture.py and python3 tools/test_architecture.py; CI qualification runs both. These are development checks, not runtime dependencies.

Lossless local artifacts

Use miilo archive export INPUT OUTPUT --codec zstd, archive inspect INPUT, and archive restore INPUT OUTPUT without an API or account. See compression and verified restore for formats, limits, raw streaming commands and Node/native requirements.

Shared user settings

The native CLI supports an explicit migration into ~/.miilo/:

miilo config paths
miilo config migrate
miilo config check

These commands run locally, without endpoint authentication or network access. miilo-local config ... and miilo local config ... expose the same operation. Use an absolute MIILO_HOME to choose another user directory. No project-level configuration is discovered. Close older Miilo UIs before migration and restart updated clients afterward; old binaries continue writing their old stores.

Migration preserves existing endpoint/credential formats, display preferences and originals. The versioned config.json is published last; conflicting or unsafe files stop migration. Existing local collector configuration remains at its original path, referenced by localConfigFile, so enrolled sessions, service configuration and cache locations remain intact. Environment overrides MIILO_LOCAL_CONFIG and MIILO_OWL_CONFIG_DIR continue to take precedence. Keyring conversion is not implemented by this migration.

Release scope and remaining validation: release status.