Overview

Mounts make a service readable as files; CLIs make it actionable as a program. A CLI is a typed program tree (CLISpec) installed on the workspace by name and separate from the mounts: an account CLI initializes from its own config, consults no mount, and takes no operand path. git is the credential-free tier, so it takes no config at all and reads the repository -C names through the mount ops. The shell dispatches a line to a CLI when its first word matches an installed name.

from mirage import Workspace
from mirage.commands.cli.builtin.himalaya import HIMALAYA

ws = Workspace({"/mail": EmailVFS(config)})
ws.register_cli("himalaya", HIMALAYA, config.model_dump())

await ws.execute("himalaya envelope list --unseen --max 5")

In YAML the same install rides the clis: section:

mounts:
  /mail:
    vfs: email
    config: { ... }
clis:
  himalaya:
    cli: himalaya
    config: { ... }

Every level of the tree answers --help, unknown verbs fail with git’s wording (exit 1), and missing required flags fail with argparse’s wording (exit 2). Two installs under different head words are two accounts.

Authoring your own CLI

The custom CLI authoring guide covers the complete lifecycle: a runnable multi-account example, typed and script CLIs, code and YAML registration, constructor validation, snapshots and credentials, the CLISpec / Option / Operand reference, and an agent authoring checklist. Installed CLIs are self-discovering through man, --help, type, and which. Installation remains a host-side API, so an agent can use and inspect the programs it was given but cannot uninstall them.

Builtin CLIs

Program	Acts on	Vocabulary
himalaya	IMAP/SMTP mail	pimalaya/himalaya (`envelope`, `message`)
gws	Google Workspace	official Google Workspace CLI
slack	Slack	OpenClaw Slack actions (`send-message`, …)
discord	Discord	OpenClaw Discord actions (`send`, `poll`, …)
ntn	Notion	official Notion CLI (`pages`, `datasources`)
linear	Linear	noun/verb (`issue create`, `team list`)
gh	GitHub	repositories, issues, pull requests, releases, Actions, API
git	git repositories	git (`status`, `log`, `add`, `commit`)

Reading stays on the mount (cat, grep, jq over the virtual files); acting goes through the CLI. The mounted tree’s <name>__<id> path segments supply the IDs the CLI flags take.

Getting Started

AI Agents

VFS

CLIs

Watch

Runtimes

Authoring your own CLI

Builtin CLIs

​Authoring your own CLI

​Builtin CLIs

Authoring your own CLI

Builtin CLIs