CLI - Mirage

The mirage CLI is a thin httpx wrapper over the Mirage daemon. It auto-spawns the daemon on first workspace create, and the daemon auto-exits 30 seconds after the last workspace is deleted. Most users never type a daemon command directly. Output is structured JSON to stdout for every verb — pipe to jq, save to file, or read it directly.

Install

curl -fsSL https://strukto.ai/mirage/install.sh | sh
# or
npm install -g @struktoai/mirage-cli
# or
uvx mirage-ai
# or
npx @struktoai/mirage-cli

Verify:

mirage --help

Define a workspace in YAML

A workspace is a set of prefixed mounts plus some workspace-level settings. Save this as workspace.yaml:

mode: WRITE

mounts:
  /:
    resource: ram
    mode: WRITE
  /s3:
    resource: s3
    mode: READ
    config:
      bucket: ${AWS_S3_BUCKET}
      region: ${AWS_DEFAULT_REGION}
      aws_access_key_id: ${AWS_ACCESS_KEY_ID}
      aws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}

${VAR} placeholders are interpolated from your shell environment at mirage workspace create time. Missing vars fail fast with the full list, not lazily on first use.

Walkthrough

A guided tour from creating a workspace to snapshotting it. Each step builds on the previous one; you can copy them in order. For a runnable end-to-end version against a real multi-mount workspace (/s3, /gdrive, /gmail, /slack, /discord), see examples/python/cross/README.md.

1. Source env and create a workspace

The YAML’s ${...} placeholders resolve from your shell at create time, so source your env first. The daemon auto-spawns on the first create.

set -a && source .env.development && set +a

mirage workspace create workspace.yaml --id demo

2. Inspect

list is one line per workspace; get returns the full mount and session detail.

mirage workspace list
mirage workspace get demo

3. Run commands against your mounts

execute runs a shell command inside the workspace. Paths resolve through the mount registry (/s3/... hits S3, / hits the RAM backing, etc.).

mirage execute --workspace_id demo --command "ls /s3/"
mirage execute --workspace_id demo --command "head -n 1 /s3/data/example.jsonl"

4. Pipe stdin

When stdout isn’t a TTY, the CLI forwards stdin to the command automatically.

echo -e "a\nb\nc" | mirage execute --workspace_id demo --command "wc -l"

5. Dry-run with `provision`

provision returns a ProvisionResult (network bytes, cache hits, estimated cost) without running the command — handy for predicting spend before kicking off an expensive read.

mirage provision --workspace_id demo \
  --command "cat /s3/data/example.jsonl | wc -l"

6. Cache: network → hit after a real read

After a real cat, provision flips that path from a network read to a cache hit (cache_hits=1).

mirage execute  --workspace_id demo --command "cat /s3/data/example.jsonl > /dev/null"
mirage provision --workspace_id demo --command "cat /s3/data/example.jsonl"

7. Command history

Every executed command is recorded by a hidden recorder (the Observer). The history builtin shows the calling session’s commands (GNU bash semantics, history -c clears only that session’s view), and /.bash_history renders the GNU histfile across all sessions, readable with the ordinary file commands.

mirage execute --workspace_id demo --command "history 5"
mirage execute --workspace_id demo --command "tail -n 6 /.bash_history"
mirage execute --workspace_id demo --command "grep cat /.bash_history"

8. Background jobs

Long-running commands take --background and return a job_id immediately. mirage job wait blocks until it’s done.

JOB=$(mirage execute --workspace_id demo --background \
  --command "wc -l /s3/data/example.jsonl" \
  | jq -r .job_id)
mirage job wait $JOB

9. Snapshot to disk

mirage workspace snapshot demo /tmp/demo.tar

10. Restore from snapshot

Snapshots redact cloud creds at save time, so loading needs fresh creds via a config file. The same workspace YAML used for create works.

mirage workspace load /tmp/demo.tar workspace.yaml \
  --id demo_loaded

mirage workspace get demo_loaded --verbose
mirage execute --workspace_id demo_loaded \
  --command "head -n 1 /s3/data/example.jsonl"

A config file is required for any mount whose snapshot config contains redacted secrets (S3 with inline keys, GDrive, Slack, Discord, Redis, …). The snapshot stores "<REDACTED>" in place of those secrets at save time. Loading without the config 400s with the list of prefixes that need fresh creds. Local resources (RAM, Disk) restore as-is with no extra config needed.

11. Clean up

The daemon exits ~30s after the last workspace is deleted.

mirage workspace delete demo
mirage workspace delete demo_loaded

Versioning

Every workspace has its own git-backed history kept by the daemon (under ~/.mirage/repos/<workspace-id> by default; set MIRAGE_VERSION_ROOT to relocate). You commit the live state as a version, then log, diff, branch, and restore in place. The verbs follow git.

Commit and log

mirage execute --workspace_id demo --command "echo v1 > /notes.txt"
mirage workspace commit demo -m "first"

mirage execute --workspace_id demo --command "echo v2 > /notes.txt"
mirage workspace commit demo -m "second"

mirage workspace log demo          # newest first: "second", then "first"

Diff

diff reports changed paths (added / modified / deleted), git-style. No refs compares live state to the branch HEAD; one ref compares live to that ref; two refs compare two versions.

mirage workspace diff demo                # live vs HEAD
mirage workspace diff demo <v1>           # live vs <v1>
mirage workspace diff demo <v1> <v2>      # <v1> vs <v2>

Branch

branch forks at another branch’s current version; commit onto it with -b.

mirage workspace branch demo exp                  # fork exp from main
mirage workspace branch demo exp2 --from exp      # fork from a non-main branch
mirage workspace commit demo -b exp -m "on exp"   # commit onto exp
mirage workspace log demo -b exp                  # log a specific branch

Checkout

checkout restores the live state to a past version or branch, in place. It overwrites uncommitted live state.

mirage workspace checkout demo <version>     # by version id
mirage workspace checkout demo main          # by branch name

Clone from a version

clone --at makes a new workspace from one of the source’s past versions (omit --at to clone the live state).

mirage workspace clone demo --at <version> --id demo_at_v1

Verbs at a glance

Verb	What it does
`mirage workspace create FILE [--id NAME]`	Build resources from YAML, register a workspace, return its id.
`mirage workspace list`	Brief one-line summary per active workspace.
`mirage workspace get ID [--verbose]`	Full detail (mounts, sessions, optionally cache / dirty / history internals).
`mirage workspace delete ID`	Stop the workspace; daemon may exit on the idle timer.
`mirage workspace clone SRC_ID [--id NAME] [--at REF]`	New workspace from the source; `--at REF` clones a past version, otherwise the live state.
`mirage workspace commit ID [-m MSG] [-b BRANCH]`	Commit the live state as a version; returns the version id.
`mirage workspace log ID [-b BRANCH]`	List versions on a branch, newest first.
`mirage workspace diff ID [A] [B] [-b BRANCH]`	Changed paths (added/modified/deleted). No refs: live vs HEAD; one ref: live vs A; two: A vs B.
`mirage workspace branch ID NAME [--from BRANCH]`	Fork a branch at another branch’s current version.
`mirage workspace checkout ID REF`	Restore the live state in place to a version id or branch.
`mirage workspace snapshot ID PATH.tar`	Snapshot to a tar file.
`mirage workspace load PATH.tar [CONFIG] [--id NAME]`	Restore from tar; optional config re-supplies redacted creds.
`mirage session create WS [--id NAME]`	Add a named session (own cwd + env).
`mirage session list WS`	List sessions for a workspace.
`mirage session delete WS SESSION`	Close a session.
`mirage execute --workspace_id WS [--session_id S] [--background] --command "..."`	Run a command. Pipes stdin automatically when stdout is not a TTY.
`mirage provision --workspace_id WS [--session_id S] --command "..."`	Dry-run / cost estimate — returns a `ProvisionResult` shape (network bytes, cache hits, estimated cost) without running the command.
`mirage job list [--workspace_id WS]`	List jobs the daemon has run, plus their status.
`mirage job get JOB`	Detail for one job.
`mirage job wait JOB [--timeout SECS]`	Block until the job is done; returns the result.
`mirage job cancel JOB`	Cancel a running job.

Per-mount safeguards

Per-mount command_safeguards are Python CLI only today. The TypeScript CLI config schema does not carry them yet.

Cap what a command may stream back per mount with command_safeguards, so a runaway cat/grep/rg can’t flood the agent or hang. Each entry sets max_lines / max_bytes (output cap) and/or timeout_seconds (deadline), with on_exceed: truncate (stop, exit 0, add a stderr notice) or on_exceed: error (stop, exit 1):

mounts:
  /data:
    resource: ram
    mode: WRITE
    command_safeguards:
      head:                  # cap output, keep going
        max_lines: 100
        on_exceed: truncate
      grep:                  # cap output, fail hard
        max_lines: 50
        on_exceed: error
      rg:                    # deadline in seconds
        timeout_seconds: 30

Caps fire on the terminal command of a pipeline only, so cat big.txt | head -n 30 still shows 30 lines. Truncation exits 0, error exits 1, and a timeout exits 124 — each with a stderr notice. Without a command_safeguards block, cat/grep/rg/head/tail still cap at 2000 lines by default. See Output Safeguards for the SDK form and the same fields.

Daemon control

Most users never run these directly — the daemon auto-spawns on first workspace create and auto-exits after the idle timer fires (default 30s after the last workspace is deleted). When you need to intervene — typically during development, when you want code changes to take effect:

mirage daemon status              # health, PID, uptime, workspace count
mirage daemon stop                # graceful: trip exit event, falls back to SIGTERM after --timeout (default 5s)
mirage daemon restart             # stop + lazy respawn (add --eager to spawn now)
mirage daemon kill                # SIGKILL via PID file -- last resort

Verb	What it does
`mirage daemon status`	Daemon health, PID, uptime, workspace count. Exit 1 if daemon not reachable.
`mirage daemon stop`	`POST /v1/shutdown` to trip the daemon’s exit event. Daemon closes active workspaces and exits. Falls back to SIGTERM on `--timeout`.
`mirage daemon restart`	Stop, then either wait for next `workspace create` to auto-spawn (default) or `--eager` to spawn immediately. Workspaces are LOST on restart — save any you want to keep first with `mirage workspace snapshot <id> <path>` and reload with `mirage workspace load <path>`.
`mirage daemon kill`	SIGKILL via PID file at `~/.mirage/daemon.pid`. Skips graceful shutdown — use only when `stop` hangs.

When you change Mirage’s source code (commands, providers, etc.), the running daemon won’t see your changes — it loaded the old code at startup. Run mirage daemon restart to pick up new code. Same situation as dockerd after recompiling Docker.

Where the daemon lives

Most users never need to think about the daemon. If you do:

It listens on http://127.0.0.1:8765 by default.

Override via MIRAGE_DAEMON_URL env var or ~/.mirage/config.toml:

[daemon]
url                = "http://127.0.0.1:8765"
idle_grace_seconds = 30

Logs go to ~/.mirage/daemon.log when the CLI auto-spawns it.
It exits 30 seconds after the workspace count hits zero (configurable).

​Install

​Define a workspace in YAML

​Walkthrough

​1. Source env and create a workspace

​2. Inspect

​3. Run commands against your mounts

​4. Pipe stdin

​5. Dry-run with provision

​6. Cache: network → hit after a real read

​7. Command history

​8. Background jobs

​9. Snapshot to disk

​10. Restore from snapshot

​11. Clean up

​Versioning

​Commit and log

​Diff

​Branch

​Checkout

​Clone from a version

​Verbs at a glance

​Per-mount safeguards

​Daemon control

​Where the daemon lives

Install

Define a workspace in YAML

Walkthrough

1. Source env and create a workspace

2. Inspect

3. Run commands against your mounts

4. Pipe stdin

5. Dry-run with `provision`

6. Cache: network → hit after a real read

7. Command history

8. Background jobs

9. Snapshot to disk

10. Restore from snapshot

11. Clean up

Versioning

Commit and log

Diff

Branch

Checkout

Clone from a version

Verbs at a glance

Per-mount safeguards

Daemon control

Where the daemon lives