> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Every mirage command, the same in the Python and TypeScript packages.

`mirage` is a client of the server's [HTTP routes](/home/access/http), with the same commands in Python and TypeScript. When its `url` is on this machine, it starts a server on first use; a remote `url` is never started.

## Install

<CodeGroup>
  ```bash script theme={null}
  curl -fsSL https://strukto.ai/mirage/install.sh | sh
  ```

  ```bash pip theme={null}
  pip install mirage-ai
  ```

  ```bash uv theme={null}
  uv tool install mirage-ai
  ```

  ```bash npm theme={null}
  npm install -g @struktoai/mirage-cli
  ```
</CodeGroup>

## Quickstart

```bash theme={null}
mirage workspace create workspace.yaml --id demo   # starts the server
mirage shell -w demo -c 'ls / | head'
mirage grep -w demo -i error /
mirage workspace delete demo
```

`workspace.yaml` is a [workspace config](/home/yaml).

## Exit codes

| Code | Meaning |
| - | - |
| `0` | Success. |
| `1` | A tool command's tool failed, or the server could not be reached. |
| `2` | A usage error, a bad config, or a refusal from the server. |
| `130` | The line was interrupted with Ctrl-C or canceled. |
| `N` | `shell`, `job wait` and `job get` exit with the line's own status. |

## Run lines and tools

`-w` names the workspace and `-s` the session, the default one when absent.

| Command | Does |
| - | - |
| `mirage shell -w ID -c LINE [--cwd PATH] [--bg]` | Run a line. Piped stdin streams to it, Ctrl-C cancels it, and `--bg` returns a job id at once. |
| `mirage read -w ID PATH [--offset N] [--limit N]` | Read a file. |
| `mirage write -w ID PATH [--content TEXT]` | Write a file, from stdin without `--content`. |
| `mirage edit -w ID PATH OLD NEW [--replace-all]` | Replace a string in a file. |
| `mirage ls -w ID PATH` | List a directory. |
| `mirage grep -w ID PATTERN PATH [-i] [-F] [-l] [-c] [-m N] [-C N] [--include GLOB]` | Search file contents. |
| `mirage glob -w ID PATTERN [PATH]` | Find paths by pattern. |

### `mirage mcp`

`mirage mcp [CONFIG] [-w ID] [-s SESSION]` serves a session's [MCP](/home/access/mcp) tools on stdio. `mirage rpc` takes the same arguments and serves [RPC](/home/access/rpc).

With `-w`, it serves a workspace the server already holds. Otherwise it creates one from `CONFIG`, from `MIRAGE_MCP_CONFIG` (`MIRAGE_RPC_CONFIG`) or `MIRAGE_CONFIG`, or from a `workspace.yaml` found walking up from the working directory. It deletes that workspace when the client disconnects, unless the config names a `workspace_id`.

## Workspaces

| Command | Does |
| - | - |
| `mirage workspace create CONFIG [--id ID]` | Create a workspace from a YAML or JSON config. |
| `mirage workspace list` | List workspaces. |
| `mirage workspace get ID [--verbose]` | Show mounts and sessions. |
| `mirage workspace delete ID` | Close a workspace and delete its state. |
| `mirage workspace clone SRC [--id ID]` | Copy a workspace. |
| `mirage workspace snapshot ID FILE.tar` | Save it to a tar here: the server sends the tar back, on this machine or another. |
| `mirage workspace snapshot ID --key KEY` | Save it to the server's [snapshot store](/home/snapshot#an-s3-like-store) instead. |
| `mirage workspace load FILE.tar [CONFIG] [--id ID]` | Restore a tar from here, uploading it. `CONFIG` gives back the credentials the snapshot left out. |
| `mirage workspace load --key KEY [CONFIG] [--id ID]` | Restore one from the server's snapshot store. |

### Asks

| Command | Does |
| - | - |
| `mirage workspace list-asks ID [--session S] [--all]` | List pending [asks](/home/permissions#asks). |
| `mirage workspace allow ID ASK [--scope once\|session]` | Allow one. |
| `mirage workspace deny ID ASK` | Deny one. |

## Sessions

| Command | Does |
| - | - |
| `mirage session create ID [--id S] [-p PROFILE] [-m /prefix:mode]...` | Add a session under a [profile](/home/permissions), with mounts narrowed to `r`, `rw` or `rwx`. |
| `mirage session list ID` | List sessions. |
| `mirage session delete ID S` | Close a session. |

## Jobs

| Command | Does |
| - | - |
| `mirage job list [-w ID]` | List jobs. |
| `mirage job get JOB` | Show one job and its result. |
| `mirage job wait JOB [--timeout SECONDS]` | Wait for a job to finish. |
| `mirage job cancel JOB` | Cancel a job. |

## Daemon

The server the CLI starts. It exits 30 seconds after its last workspace is deleted, and logs to `~/.mirage/daemon.log`.

| Command | Does |
| - | - |
| `mirage daemon status` | Show PID, uptime and workspace count. |
| `mirage daemon stop` | Close its workspaces and exit. |
| `mirage daemon restart [--eager]` | Stop it; the next command, or `--eager`, starts a new one. Workspaces are lost. |
| `mirage daemon kill` | Kill it. A last resort. |

## Config

`mirage config set|get|unset|list` edits `~/.mirage/config.toml`. An environment variable wins over the file. Changes apply on the next start.

| Key | Env var | Default |
| - | - | - |
| `url` | `MIRAGE_DAEMON_URL` | `http://127.0.0.1:8765` |
| `port` | `MIRAGE_DAEMON_PORT` | the `url`'s port |
| `auth_token` | `MIRAGE_TOKEN` | `~/.mirage/auth_token`, for a local `url` only |
| `auth_mode` | `MIRAGE_AUTH_MODE` | `local` |
| `allowed_hosts` | `MIRAGE_ALLOWED_HOSTS` | `127.0.0.1,localhost,::1` |
| `idle_grace_seconds` | `MIRAGE_IDLE_GRACE_SECONDS` | `30` |
| `ssh_*` | `MIRAGE_SSH_*` | see [SSH](/home/access/ssh#settings) |
| `jwt_*` | `MIRAGE_JWT_*` | see [Auth](/home/access/http#auth) |

`MIRAGE_HOME` moves everything under `~/.mirage`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.