# CLI
URL: /docs/reference/cli
LLM index: /llms.txt
Description: Look up every lim command, the flags they share, and the environment variables the CLI reads.

# CLI reference

The `lim` CLI drives every Limrun instance type from Linux, Windows, or macOS. This page lists every command in `lim` 0.35.1 and the behavior they share. For a command's full flag list, run it with `--help`:

```bash
lim ios create --help
```

## Install and update

Install the `lim` package globally with npm, pnpm, or bun. The CLI needs Node.js 20 LTS or newer:

```bash
npm install --global lim
```

Run the same command again to update, and `lim version` to print the installed version.

## Authenticate

Every command that talks to Limrun resolves an API key in this order:

1. The `--api-key` flag.
2. The `LIM_API_KEY` environment variable. The CLI also reads it from a `.env` file in the working directory.
3. The key stored in `~/.lim/config.yaml` by `lim login` (browser sign-in) or `lim set-api-key`.

`lim logout` removes the stored key. Headless hosts such as CI runners and cloud agents should set `LIM_API_KEY` from a secret. A command pinned to a single instance through `set-instance` or the `LIM_<TYPE>_INSTANCE_*` variables needs no API key at all; see [Sandboxed agents](/docs/agents/sandboxed-agents).

## Target an instance

Device and build commands accept `--id <instance-id>`; `get` and `delete` take the ID as a positional argument instead (`lim ios delete <instance-id>`). Without an ID, they use the instance of that type you created last in the current workspace. The CLI records these per workspace in `~/.lim/last-instances.json`; a workspace is the current git repository or worktree unless you assign one with `lim set-workspace-dir`, `--workspace`, or `LIM_WORKSPACE`. See [The CLI's default instance](/docs/concepts#the-clis-default-instance).

Pass `--id` explicitly in scripts, CI, and agents that create more than one instance.

When the targeted instance no longer exists, device and build commands create a replacement automatically; pass `--no-create` to fail instead. `create`, `delete`, `list`, `get`, `logs`, `tools`, and `version` never create a replacement; they fail with not-found instead.

## Shared flags

Commands that act on instances share these flags. Account commands such as `lim login` and `lim skills install` take only some of them.

| Flag | What it does |
|---|---|
| `--api-key <value>` | API key for this command. Overrides the stored login and `LIM_API_KEY`. |
| `--json` | Print structured JSON instead of tables or plain text, where the command supports it. |
| `--quiet` | Suppress intermediate logs and print only the final result. |
| `--workspace <value>` | Workspace used to find the most recent instance when no ID is given. Defaults to the current git repository or worktree. On `lim xcode build` and `lim xcode test`, `--workspace` is the `.xcworkspace` passed to `xcodebuild`; use `LIM_WORKSPACE` there. |
| `--[no-]create` | Create a replacement instance when the target is not found. On by default. |
| `--[no-]daemon` | Route device commands through a background WebSocket daemon that starts on first use, so repeated commands reuse one connection. On by default; disable with `--no-daemon` or `LIM_DAEMON=false`. |

`lim session start` starts the same background connection explicitly for one instance, `lim session status` lists running sessions, and `lim session stop` stops one or all of them.

## Environment variables

| Variable | Read by | Meaning |
|---|---|---|
| `LIM_API_KEY` | Every command | Organization API key. |
| `LIM_WORKSPACE` | Every command | Workspace for resolving the default instance. |
| `LIM_DAEMON` | Every command | Set to `false` to disable the background connection daemon. |
| `LIM_DISABLE_TELEMETRY` | Every command | Set to any value, such as `1`, to disable CLI usage telemetry. |
| `LIM_IOS_INSTANCE_URL`, `LIM_IOS_INSTANCE_TOKEN` | `lim ios` | Drive one simulator by its API URL and instance token, without an API key. |
| `LIM_ANDROID_INSTANCE_URL`, `LIM_ANDROID_INSTANCE_TOKEN`, `LIM_ANDROID_INSTANCE_ADB_URL` | `lim android` | The same for an emulator; the ADB URL enables `lim android connect`. |
| `LIM_XCODE_INSTANCE_URL`, `LIM_XCODE_INSTANCE_TOKEN` | `lim xcode` | The same for an Xcode sandbox. |
| `LIM_GRADLE_INSTANCE_URL`, `LIM_GRADLE_INSTANCE_TOKEN` | `lim gradle` | The same for a Gradle sandbox. |
| `LIM_WEBHOOK_URL`, `LIM_WEBHOOK_HEADERS`, `LIM_WEBHOOK_LABELS` | `lim xcode build`, `lim gradle build` | Defaults for `--webhook-url`, `--webhook-header`, and `--webhook-label`. See [Build logs and webhooks](/docs/ci/build-logs-and-webhooks). |
| `LIM_SIGNED_UPLOAD_URL` | `lim xcode build`, `lim gradle build` | Default for `--signed-upload-url` when `--upload` is not set. |
| `LIM_KEYSTORE_PASSWORD`, `LIM_KEY_PASSWORD` | `lim gradle build` | Passwords for `--keystore`. See [Sign and publish](/docs/android/sign-and-publish). |
| `LIM_PLAYSTORE_ACCESS_TOKEN` | `lim gradle build` | Google access token for `--upload-to-playstore`. |

## Commands

The Guide column links to the page that explains a command in context. Commands without a guide are covered by their `--help` output.

### iOS simulators

| Command | What it does | Guide |
|---|---|---|
| `lim ios app-log` | Stream or tail app logs from a running iOS instance | [Run a simulator](/docs/ios/run-simulator#read-app-logs) |
| `lim ios app-logs` | List persisted app log captures of an iOS instance | [Run a simulator](/docs/ios/run-simulator#keep-captures-after-the-session) |
| `lim ios attach-xcode` | Attach an Xcode instance to an iOS simulator |  |
| `lim ios camera` | Control the simulated camera of a running iOS instance | [Run a simulator](/docs/ios/run-simulator#simulate-the-camera) |
| `lim ios create` | Create a new iOS instance | [Run a simulator](/docs/ios/run-simulator#create-a-simulator) |
| `lim ios delete` | Delete an iOS instance | [Run a simulator](/docs/ios/run-simulator#reuse-and-clean-up) |
| `lim ios delete-file` | Delete a file or folder on the iOS simulator | [Run a simulator](/docs/ios/run-simulator#transfer-files) |
| `lim ios element-tree` | Get the UI element tree from a running iOS instance | [Run a simulator](/docs/ios/run-simulator#read-the-screen) |
| `lim ios events` | List persisted event log captures of an iOS instance | [Run a simulator](/docs/ios/run-simulator#keep-captures-after-the-session) |
| `lim ios fold` | Read or change the native iPhone Duo fold state | [Run a simulator](/docs/ios/run-simulator#fold-an-iphone-duo) |
| `lim ios get` | Get details for a specific iOS instance | [Per-instance MCP server](/docs/agents/mcp#get-the-mcp-url-and-token) |
| `lim ios info` | Get device information from a running iOS instance |  |
| `lim ios install-app` | Install an app on a running iOS instance | [Run a simulator](/docs/ios/run-simulator#manage-apps) |
| `lim ios keychain generate-key` | Generate an iOS keychain encryption key | [Run a simulator](/docs/ios/run-simulator#save-and-restore-the-keychain) |
| `lim ios keychain restore` | Restore iOS keychain state from asset storage | [Run a simulator](/docs/ios/run-simulator#save-and-restore-the-keychain) |
| `lim ios keychain save` | Save iOS keychain state to asset storage | [Run a simulator](/docs/ios/run-simulator#save-and-restore-the-keychain) |
| `lim ios launch-app` | Launch an app on a running iOS instance | [Run a simulator](/docs/ios/run-simulator#manage-apps) |
| `lim ios list` | List iOS instances | [Run a simulator](/docs/ios/run-simulator#reuse-and-clean-up) |
| `lim ios list-apps` | List installed apps on a running iOS instance | [Run a simulator](/docs/ios/run-simulator#manage-apps) |
| `lim ios ls` | List files in the iOS simulator or an app container | [Run a simulator](/docs/ios/run-simulator#transfer-files) |
| `lim ios lsof` | List open files on a running iOS instance | [Run a simulator](/docs/ios/run-simulator#use-macos-dev-tools) |
| `lim ios maestro` | Run Maestro flows against a running iOS instance | [Maestro](/docs/testing/maestro) |
| `lim ios microphone` | Control the simulated microphone of a running iOS instance | [Run a simulator](/docs/ios/run-simulator#simulate-the-microphone) |
| `lim ios open-url` | Open a URL on a running iOS instance | [Run a simulator](/docs/ios/run-simulator#open-urls-and-deep-links) |
| `lim ios perform` | Perform multiple iOS actions in a single batch | [Run a simulator](/docs/ios/run-simulator#run-a-batch-of-actions) |
| `lim ios press-key` | Press a key on a running iOS instance | [Run a simulator](/docs/ios/run-simulator#type-and-press-keys) |
| `lim ios pull-file` | Pull a file from the iOS simulator | [Run a simulator](/docs/ios/run-simulator#transfer-files) |
| `lim ios push-file` | Push a local file to the iOS simulator | [Run a simulator](/docs/ios/run-simulator#transfer-files) |
| `lim ios record` | Start or stop video recording on a running iOS instance | [Run a simulator](/docs/ios/run-simulator#record-a-video) |
| `lim ios recordings` | List persisted session recordings of an iOS instance | [Run a simulator](/docs/ios/run-simulator#keep-captures-after-the-session) |
| `lim ios reverse` | Expose a local client-first service to the simulator | [Connect to local services](/docs/ios/local-services#use-the-legacy-fixed-port-reverse-tunnel) |
| `lim ios screenshot` | Capture a screenshot from a running iOS instance | [Run a simulator](/docs/ios/run-simulator#connect-a-device-client) |
| `lim ios scroll` | Scroll on a running iOS instance | [Run a simulator](/docs/ios/run-simulator#scroll-and-swipe) |
| `lim ios set-instance` | Set the iOS instance targeted by subsequent commands | [Sandboxed agents](/docs/agents/sandboxed-agents#point-the-sandboxed-cli-at-the-instance) |
| `lim ios set-text` | Set text on an iOS element directly via accessibility | [Run a simulator](/docs/ios/run-simulator#adjust-values) |
| `lim ios simctl` | Run simctl on a running iOS instance | [Run a simulator](/docs/ios/run-simulator#use-macos-dev-tools) |
| `lim ios swipe` | Swipe between two points on a running iOS instance | [Run a simulator](/docs/ios/run-simulator#scroll-and-swipe) |
| `lim ios sync` | Sync a built app bundle to a running iOS instance |  |
| `lim ios syslog` | Stream syslog from a running iOS instance | [Run a simulator](/docs/ios/run-simulator#read-app-logs) |
| `lim ios tap` | Tap at coordinates on a running iOS instance | [Run a simulator](/docs/ios/run-simulator#tap-an-element) |
| `lim ios tap-element` | Tap an iOS element by accessibility selector | [Run a simulator](/docs/ios/run-simulator#tap-an-element) |
| `lim ios terminate-app` | Terminate an app on a running iOS instance | [Run a simulator](/docs/ios/run-simulator#manage-apps) |
| `lim ios toggle-keyboard` | Toggle the iOS software keyboard | [Run a simulator](/docs/ios/run-simulator#type-and-press-keys) |
| `lim ios tunnel` | Expose declared local TCP destinations to the simulator | [Connect to local services](/docs/ios/local-services#start-a-tunnel-from-an-ios-simulator) |
| `lim ios tunnel status` | Show the active destination tunnel | [Connect to local services](/docs/ios/local-services#start-a-tunnel-from-an-ios-simulator) |
| `lim ios tunnel stop` | Stop the active destination tunnel | [Connect to local services](/docs/ios/local-services#start-a-tunnel-from-an-ios-simulator) |
| `lim ios type` | Type text into the focused iOS input field | [Run a simulator](/docs/ios/run-simulator#type-and-press-keys) |
| `lim ios xcodebuild` | Run xcodebuild on a running iOS instance | [Run a simulator](/docs/ios/run-simulator#use-macos-dev-tools) |
| `lim ios xcrun` | Run xcrun on a running iOS instance | [Run a simulator](/docs/ios/run-simulator#use-macos-dev-tools) |

### Android emulators

| Command | What it does | Guide |
|---|---|---|
| `lim android adb-shell` | Run a shell command on a running Android instance (like adb shell) | [Run an emulator](/docs/android/run-emulator#run-shell-commands-and-move-files-without-a-tunnel) |
| `lim android app-log` | Stream or tail app logs from a running Android instance | [Run an emulator](/docs/android/run-emulator#read-logs) |
| `lim android app-logs` | List persisted app log captures of an Android instance | [Run an emulator](/docs/android/run-emulator#create-options) |
| `lim android camera` | Control the virtual camera of a running Android instance | [Run an emulator](/docs/android/run-emulator#simulate-the-camera-microphone-and-network) |
| `lim android connect` | Connect to an existing Android instance via ADB tunnel | [Run an emulator](/docs/android/run-emulator#choose-a-connection-sdk-client-or-adb-tunnel) |
| `lim android create` | Create a new Android instance | [Run an emulator](/docs/android/run-emulator#create-an-emulator) |
| `lim android delete` | Delete an Android instance | [Run an emulator](/docs/android/run-emulator#delete-the-emulator) |
| `lim android element-tree` | Get the UI element tree from a running Android instance | [Run an emulator](/docs/android/run-emulator#get-the-element-tree) |
| `lim android events` | List persisted event log captures of an Android instance | [Run an emulator](/docs/android/run-emulator#create-options) |
| `lim android find-element` | Find Android elements by selector | [Run an emulator](/docs/android/run-emulator#find-elements) |
| `lim android get` | Get details for a specific Android instance |  |
| `lim android install-app` | Install an app on a running Android instance | [Run an emulator](/docs/android/run-emulator#install-on-a-running-instance) |
| `lim android launch-app` | Launch an app on a running Android instance | [Run an emulator](/docs/android/run-emulator#launch-and-stop-apps) |
| `lim android list` | List Android instances | [Run an emulator](/docs/android/run-emulator#delete-the-emulator) |
| `lim android logcat` | Run logcat on a running Android instance | [Run an emulator](/docs/android/run-emulator#read-logs) |
| `lim android open-url` | Open a URL on a running Android instance | [Run an emulator](/docs/android/run-emulator#open-urls) |
| `lim android play-on-microphone` | Play a local audio file as microphone input on a running Android instance | [Run an emulator](/docs/android/run-emulator#simulate-the-camera-microphone-and-network) |
| `lim android press-key` | Press a key on a running Android instance | [Run an emulator](/docs/android/run-emulator#tap-type-and-press-keys) |
| `lim android pull-file` | Pull a file from a running Android instance | [Run an emulator](/docs/android/run-emulator#run-shell-commands-and-move-files-without-a-tunnel) |
| `lim android push-file` | Push a local file to a running Android instance | [Run an emulator](/docs/android/run-emulator#run-shell-commands-and-move-files-without-a-tunnel) |
| `lim android record` | Start or stop video recording on a running Android instance | [Run an emulator](/docs/android/run-emulator#record-the-screen) |
| `lim android recordings` | List persisted session recordings of an Android instance | [Run an emulator](/docs/android/run-emulator#create-options) |
| `lim android screenshot` | Capture a screenshot from a running Android instance | [Run an emulator](/docs/android/run-emulator#take-a-screenshot) |
| `lim android scroll` | Scroll on a running Android instance | [Run an emulator](/docs/android/run-emulator#scroll) |
| `lim android set-instance` | Set the Android instance targeted by subsequent commands | [Sandboxed agents](/docs/agents/sandboxed-agents#point-the-sandboxed-cli-at-the-instance) |
| `lim android set-wifi-bandwidth` | Set Wi-Fi bandwidth limits on a running Android instance | [Run an emulator](/docs/android/run-emulator#simulate-the-camera-microphone-and-network) |
| `lim android sync` | Sync an APK to a running Android instance | [Run an emulator](/docs/android/run-emulator#sync-apk-rebuilds) |
| `lim android tap` | Tap at coordinates on a running Android instance | [Run an emulator](/docs/android/run-emulator#tap-type-and-press-keys) |
| `lim android tap-element` | Tap an Android element by selector | [Run an emulator](/docs/android/run-emulator#tap-type-and-press-keys) |
| `lim android terminate-app` | Terminate an app on a running Android instance | [Run an emulator](/docs/android/run-emulator#launch-and-stop-apps) |
| `lim android tunnel` | Send selected Android TCP destinations through this machine | [Connect to local services](/docs/android/local-services) |
| `lim android tunnel status` | Show the active destination tunnel | [Connect to local services](/docs/android/local-services#start-a-tunnel) |
| `lim android tunnel stop` | Stop the active destination tunnel | [Connect to local services](/docs/android/local-services#start-a-tunnel) |
| `lim android type` | Type text into an Android input field | [Run an emulator](/docs/android/run-emulator#tap-type-and-press-keys) |

### Xcode sandboxes

| Command | What it does | Guide |
|---|---|---|
| `lim xcode attach-simulator` | Attach an iOS simulator to an Xcode instance | [Build with Xcode](/docs/ios/build-with-xcode#install-on-a-simulator) |
| `lim xcode build` | Run xcodebuild on an Xcode sandbox | [Build with Xcode](/docs/ios/build-with-xcode) |
| `lim xcode create` | Create a new Xcode instance | [Build with Xcode](/docs/ios/build-with-xcode#pick-your-interface) |
| `lim xcode delete` | Delete an Xcode instance | [GitHub Actions recipes](/docs/ci/github-actions#build-a-signed-ipa-on-every-pull-request) |
| `lim xcode get` | Get details for a specific Xcode instance |  |
| `lim xcode list` | List Xcode instances | [PR previews](/docs/ci/pr-previews#clean-up-when-a-pr-closes) |
| `lim xcode logs` | Fetch logs for an active, recent, or specific Xcode build | [Build logs and webhooks](/docs/ci/build-logs-and-webhooks#read-build-logs) |
| `lim xcode rbe` | Serve a local Bazel remote-execution endpoint backed by a Limrun Xcode instance | [Build with Bazel](/docs/ios/build-with-bazel) |
| `lim xcode rbe upload` | Upload the latest successful remote build as an asset | [Build with Bazel](/docs/ios/build-with-bazel#upload-builds-as-assets) |
| `lim xcode run` | Run a command on a xcode sandbox | [Build with Xcode](/docs/ios/build-with-xcode#run-project-commands) |
| `lim xcode set-instance` | Set the Xcode instance targeted by subsequent commands | [Sandboxed agents](/docs/agents/sandboxed-agents#point-the-sandboxed-cli-at-the-instance) |
| `lim xcode sync` | Continuously sync local source code to an Xcode sandbox | [Build with Xcode](/docs/ios/build-with-xcode#sync-your-source) |
| `lim xcode test` | Build a scheme's test targets on an Xcode sandbox and run them on an attached iOS simulator, streaming per-case results. Exits non-zero when tests fail. Creates and attaches the instances it needs unless --id points at an existing target | [XCTest](/docs/testing/xctest) |
| `lim xcode tools` | Show the selected developer tools in a xcode sandbox | [Xcode and tool versions](/docs/ios/xcode-and-tools#select-developer-tools) |
| `lim xcode tools install` | Install selected tools in a xcode sandbox | [Xcode and tool versions](/docs/ios/xcode-and-tools#select-developer-tools) |
| `lim xcode use` | Select developer tool versions for a xcode sandbox | [Xcode and tool versions](/docs/ios/xcode-and-tools#pin-a-version-for-the-workspace) |
| `lim xcode version` | Show the Xcode version the sandbox builds with | [Xcode and tool versions](/docs/ios/xcode-and-tools#list-the-installed-versions) |
| `lim xcode version list` | List the Xcode versions the sandbox can build with | [Xcode and tool versions](/docs/ios/xcode-and-tools#list-the-installed-versions) |
| `lim xcode version set` | Pick the Xcode version this workspace builds with | [Xcode and tool versions](/docs/ios/xcode-and-tools#pin-a-version-for-the-workspace) |
| `lim xcode version unset` | Forget the Xcode version preference of this workspace | [Xcode and tool versions](/docs/ios/xcode-and-tools#forget-the-preference) |

### Gradle sandboxes

| Command | What it does | Guide |
|---|---|---|
| `lim gradle build` | Build an Android project on a gradle instance | [Build with Gradle](/docs/android/build-with-gradle#build-a-project) |
| `lim gradle create` | Create a new gradle instance | [Build with Gradle](/docs/android/build-with-gradle#build-a-project) |
| `lim gradle delete` | Delete a gradle instance | [GitHub Actions recipes](/docs/ci/github-actions#build-a-signed-aab-on-every-push) |
| `lim gradle get` | Get a gradle instance |  |
| `lim gradle list` | List gradle instances |  |
| `lim gradle logs` | Fetch logs for an active, recent, or specific Gradle build | [Build logs and webhooks](/docs/ci/build-logs-and-webhooks#read-build-logs) |
| `lim gradle run` | Run a command on a gradle sandbox | [Build with Gradle](/docs/android/build-with-gradle#select-tools) |
| `lim gradle set-instance` | Set the gradle instance targeted by subsequent commands | [Sandboxed agents](/docs/agents/sandboxed-agents#point-the-sandboxed-cli-at-the-instance) |
| `lim gradle sync` | Sync local source code to a Gradle sandbox |  |
| `lim gradle tools` | Show the selected developer tools in a gradle sandbox | [Build with Gradle](/docs/android/build-with-gradle#select-tools) |
| `lim gradle tools install` | Install selected tools in a gradle sandbox | [Build with Gradle](/docs/android/build-with-gradle#select-tools) |
| `lim gradle use` | Select developer tool versions for a gradle sandbox | [Build with Gradle](/docs/android/build-with-gradle#select-tools) |

### Assets

| Command | What it does | Guide |
|---|---|---|
| `lim asset delete` | Delete an asset | [Asset Storage](/docs/platform/asset-storage#list-get-and-delete-assets) |
| `lim asset get` | List assets or get a specific one |  |
| `lim asset list` | List assets or get a specific one | [Asset Storage](/docs/platform/asset-storage#use-expo-go-and-other-catalog-apps) |
| `lim asset pull` | Download an asset file | [Asset Storage](/docs/platform/asset-storage#list-get-and-delete-assets) |
| `lim asset push` | Upload an asset file | [Asset Storage](/docs/platform/asset-storage#upload-an-asset) |

### Skills, sessions, and account

| Command | What it does | Guide |
|---|---|---|
| `lim login` | Log in to Limrun |  |
| `lim logout` | Log out of Limrun |  |
| `lim run` | Get started with Limrun |  |
| `lim session start` | Start a persistent session that keeps one connection open to an instance |  |
| `lim session status` | Show active sessions |  |
| `lim session stop` | Stop one or all active sessions |  |
| `lim set-api-key` | Set the stored Limrun API key |  |
| `lim set-workspace-dir` | Assign a directory to an isolated lim workspace |  |
| `lim skills install` | Install Limrun skills for AI coding agents | [Set up a coding agent](/docs/agents/cli#install-the-limrun-skills) |
| `lim version` | Print the installed CLI version |  |