Overview

Mirage includes twelve command-line programs for working with services, Git repositories and search mounts inside a workspace. Each program’s --help describes the commands and flags implemented by Mirage. The host mirage CLI connects to and manages workspaces. The programs on this page run in those workspaces through ws.shell(...), mirage shell, or another access method.

Supported CLIs

Program	Supported operations	Commands
airtable	Query bases and tables; read, create, update and delete records; add comments	10
discord	Read and send messages; edit, react, create threads and polls; inspect guilds	10
gh	Manage repositories, issues, pull requests, releases and Actions; call GitHub APIs	44
git	Inspect history, stage and commit files, manage branches and tags, clone and fetch	38
gws	Call Drive, Sheets, Docs, Slides, Calendar, Forms and Gmail APIs	54
hf	Download and upload Hub files; create repositories; manage tags and delete files	11
himalaya	List and search mail; read, compose, reply, forward and send messages	7
linear	Query teams, issues, projects and documents; update issues and comments	26
ntn	Read and edit Markdown pages, query data sources and call Notion APIs	9
search	Rank the records of Dify, Chroma, mem0, Qdrant and LanceDB mounts for a query	1
slack	Read and send messages; manage reactions and pins; find members and search	12
trello	Read boards, lists, labels and cards; create, update, move, assign, label and comment on cards	16

All twelve are available in Python and TypeScript on Node. The TypeScript Node package provides hf and himalaya; the other ten live in core. These are Mirage implementations of the listed command trees, not installed copies of the upstream binaries. Each reference links its upstream project or service API and documents its supported subset, limits and relevant licenses. See compatibility and licenses for the distinction between matching behavior and reusing code.

Register a CLI

Account CLIs need credentials but do not need a service mount:

from mirage import Workspace
from mirage.commands.cli.builtin.slack import SLACK
from mirage.core.slack.config import SlackConfig

ws = Workspace({})
ws.register_cli("slack", SLACK, SlackConfig(token="xoxb-..."))
await ws.shell("slack --help")

register_cli(name, spec, config) validates a config mapping or accepts an instance of the declared model. git and search have no account config; register their GIT and SEARCH specs without the third argument. Two installations of the same spec under different names can use different accounts. Registration is a host operation, not an agent shell command. The equivalent YAML entry is:

clis:
  slack:
    cli: slack
    config:
      token: ${SLACK_TOKEN}

YAML config fields use snake_case in both languages. Setup pages cover credentials and imports for every program.

Discover functionality

man
slack --help
slack send-message --help
man slack send-message
type -t slack
which slack

man and --help render the registered spec. Unknown commands and flags are refused; wording and exit codes follow the program’s declared style. Use each reference for command-specific errors rather than assuming one exit code for all CLIs. Visible installed programs have read-only stubs under /usr/bin, so which slack returns /usr/bin/slack. The stub describes the command without exposing its config or credentials. Executing that path uses the same command and policy checks. Changing PATH does not change Mirage’s virtual command lookup; host and remote runtimes use their own executable paths.

Use CLIs with the VFS

Operation	Where it goes
`cat`, `find`, `grep`, `jq` on mounted files	The selected VFS through workspace operations
Account commands such as `slack send-message`	The service configured for that CLI installation
File arguments such as `gh --body-file`, `ntn --filter-file`, `himalaya --attach` and `hf upload` paths	Workspace files through `ctx.vfs`
`git -C /repo ...`	The repository and working tree on workspace mounts

Credentials may be shared between a CLI and a VFS, but neither registers or locates the other. A CLI write uses service IDs, while file arguments resolve against the session’s working directory and retain PathSpec semantics. After an account CLI write, Mirage expires the caches of every mount the CLI’s client may reach, including answers a mount’s client keeps itself (a vector store’s search results), so later reads can observe the change. A client that names what it reaches narrows this: gh reaches only GitHub mounts on its API base. Mount modes and path policy govern workspace file operations. A read-only Slack mount does not disable slack send-message; use command policy to restrict service actions. The service’s own credentials and permissions still apply to its API calls.

Add a custom CLI

Use the authoring guide to define a typed command tree, register multiple accounts, work with VFS paths, or run a script CLI. It also covers config validation, snapshots and the shared command grammar.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Supported CLIs

Register a CLI

Discover functionality

Use CLIs with the VFS

Add a custom CLI

​Supported CLIs

​Register a CLI

​Discover functionality

​Use CLIs with the VFS

​Add a custom CLI

Supported CLIs

Register a CLI

Discover functionality

Use CLIs with the VFS

Add a custom CLI