Skip to documentation
MMirageDocs

Reference

Use the CLI

Manage routing settings, accounts, and connected machines from your terminal.

Install the CLI

The CLI manages Mirage settings on macOS, Linux, and Windows. Commands beginning with mirage host manage the host service on the Mac where you run them; mirage remote manages your account through the hosted service.

On macOS, install Mirage to get the bundled CLI. If mirage is not already on your PATH, use it in your current terminal with:

macOS · use the bundled CLI
alias mirage='/Applications/Mirage.app/Contents/MacOS/mirage-cli'
mirage --version

The alias lasts for this shell session. In scripts, use the full executable path or a standalone CLI installed on your PATH.

Standalone x64 and ARM64 archives for macOS, Linux, and Windows are distributed through Mirage’s GitHub releases under cli-v tags, with installers and SHA-256 checksums. That release repository currently requires access. If you have not been given access, use the bundled Mac CLI; the source repository is not a prerequisite for the Mac setup above.

Sign in

Terminal · authorize account access
mirage auth login
mirage auth status

The login command opens Mirage in your browser. Check that the displayed code matches the terminal and approve access with your GitHub-linked Mirage account. Use mirage auth login --no-open to open the page yourself, or --read-only to request read-only settings access.

The default server is https://mirageci.com. Login credentials are stored in your operating system’s credential store. Run mirage auth logout to revoke the stored login and remove it from this computer.

Browser sign-in authorizes remote settings. Pairing a Mac separately authorizes that machine to run jobs.

Manage this Mac

These commands require the installed Mac host service. They do not require a remote CLI login.

Terminal · inspect the local host
mirage host status
mirage host doctor
mirage host diagnostics --lines 80

status reports the host’s current state. doctor checks prerequisites and runner profiles and includes the reason and remedy for unavailable profiles. diagnostics returns the host service’s redacted log tail.

Use mirage host configure --help for pause, battery, concurrency, and runner resource settings. See Set up a Mac for examples. To pair from the CLI, run mirage host pair, enter the one-time code when prompted, and press Return. Never put the code in a command argument.

Manage account settings

Terminal · inspect your accounts
mirage remote get
mirage remote audit

Use the returned target and repository IDs when changing settings. In this example, replace 12345 with your target’s ID and 67890 with your repository’s ID:

Terminal · enable a repository
mirage remote target 12345 --mode enabled
mirage remote repository 67890 --local true

These are the same controls as the account and local-infrastructure switches in Settings. Remote changes obey your Mirage team role. Use mirage remote --help for invitations, machine access, scheduling, transfers, and Cloudflare settings.

Use in scripts

Successful commands write one versioned JSON value to standard output and exit with status zero. Prompts and JSON errors go to standard error; failures exit nonzero. Inspect the response version when building an integration, and use a JSON parser such as jq instead of matching display text.

Shell script · list enabled repositories (requires jq)
mirage remote get | jq '.targets[].repositories[] | select(.localRoutingEnabled)'

Interactive login needs the native credential store: Keychain on macOS, Secret Service on Linux, or Credential Manager on Windows. In a headless environment without one, an existing short-lived access token can be supplied through MIRAGE_ACCESS_TOKEN. Mirage does not store or refresh that environment token; unset it to stop using it. There is no long-lived token file fallback.