setup
/setup
Set up QaReN in this app: install the qaren CLI onto PATH, write .qaren/config.yaml, pick the simulator and run a first smoke check. Use for /qaren:setup, first use in an app, or when qaren is not found.
- Author
- lykhoyda ↗
- Repository
- qaren ↗
- Licence
- MIT
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 9
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Set up QaReN in this app: install the qaren CLI onto PATH, write .qaren/config.yaml, pick the simulator and run a first smoke check. Use for /qaren:setup, first use in an app, or when qaren is not found.
Original author description
Set up QaReN in this app: install the qaren CLI onto PATH, write .qaren/config.yaml, pick the simulator and run a first smoke check. Use for /qaren:setup, first use in an app, or when qaren is not found.
How it works
- 1. CLI
- 2. App
- 3. Config
- 4. Device
- 5. Smoke plan
- 6. Run
- 7. Sign-in (optional)
SKILL.md preview
---
name: setup
description: "Set up QaReN in this app: install the qaren CLI onto PATH, write .qaren/config.yaml, pick the simulator and run a first smoke check. Use for /qaren:setup, first use in an app, or when qaren is not found."
---
# Set up QaReN
Run these steps in order from the app's root directory. Each step names when to stop; when you stop, tell the user the one reason and the fix.
QaReN 2.0 needs an Apple silicon Mac with Xcode, Node 24 or newer, pnpm, and an Expo app that uses `expo-dev-client`. This setup prepares an iOS simulator; for a booted Android emulator, see the CLI README's [Check a plan](https://github.com/Lykhoyda/QaReN/blob/develop/packages/qaren-cli/README.md#check-a-plan).
## 1. CLI
The plugin root is two directories above this skill's base directory. Resolve one absolute qaren path and use it for every later `qaren` command in this session. Read `version` from `<plugin root>/.claude-plugin/plugin.json`; QaReN home is `$QAREN_HOME` (`~/.qaren` when unset):
1. First check whether the plugin root is `packages/qaren-plugin` of a QaReN checkout (two directories up holds `scripts/install-qaren-from-source.sh`). If so, use the checkout build instead of the release installer: get `<commit>` with `git -C <plugin root> rev-parse --short=12 HEAD`, and resolve `<QaReN home>/runtime/<version>-dev.<commit>/bin/qaren`. If its `--version` prints exactly `qaren <version>-dev.<commit>`, use it and continue to doctor. Otherwise offer to run `bash scripts/install-qaren-from-source.sh` from that checkout; it needs Rust (https://rustup.rs) and prints the binary path to use. Stop until that matching build is installed; then continue to doctor.
2. For a packaged plugin, run `bash <plugin root>/scripts/ensure-qaren.sh --print-bin`. If it prints an absolute path ending in `/bin/qaren`, use that plugin-verified binary and continue to doctor.
3. Otherwise run `bash <plugin root>/scripts/ensure-qaren.sh --install`. Use its printed binary path and pass the user any stderr notice about PATH or an existing command. The [CLI installation guide](https://github.com/Lykhoyda/QaReN/blob/develop/packages/qaren-cli/README.md#plugin-runtime-installation) owns the verification, PATH-linking and fallback contract.
4. If it refuses because this plugin version carries no qaren tarball, use a matching source install. If `command -v qaren` resolves, through links, under `<QaReN home>/runtime/` and prints `qaren <version>-dev.<commit>`, use that resolved path. Otherwise ask for a checkout of `Lykhoyda/QaReN` matching the plugin's version and offer to run `bash scripts/install-qaren-from-source.sh` there; use the path it prints.
5. Any other refusal: stop and quote the installer's message.
Run `<qaren path> doctor` before setup continues. Stop on a `FAIL` and give its fix.
Present `host-memory`, `host-devices`, `simulator-service` and `host-load` warnings
with their next steps before the smoke run; use the conservative lane recommendation
in the [host budget](https://github.com/Lykhoyda/QaReN/blob/develop/packages/qaren-cli/README.md#host-budget).
If memory or CPU is constrained, recommend fewer concurrent lanes and closing
unneeded apps. Ask the owner to shut down an affected borrowed device; restarting
CoreSimulatorService stops every simulator on the machine. Setup never performs
either action. A warning permits setup to continue; an unknown probe is not a healthy host.
## 2. App
- `package.json` must list `expo` and `expo-dev-client`, and `pnpm-lock.yaml` must exist. Otherwise stop: "QaReN supports pnpm Expo dev-client apps."
- If `node_modules` is absent, ask before running `pnpm install`.
- Run `pnpm exec expo config --type public --json`. Take `appId` from `ios.bundleIdentifier` and set `devClientScheme` to `exp+<slug>`, where `<slug>` is the config's `slug`; `expo-dev-client` registers that scheme unless its config plugin sets `addGeneratedScheme: false`, in which case ask. Expo may print status lines before the JSON document; parse that document.
- If the command fails (for example it needs environment variables) or either value is missing, ask the user for the bundle identifier and the dev-client scheme. Never invent environment variables or values.
## 3. Config
If `.qaren/config.yaml` exists, show it next to the detected values and change nothing without the user's consent; if its `appId` or `devClientScheme` differs from the detected values, stop until the user resolves it. Otherwise write exactly:
```yaml
appId: <bundle identifier>
devClientScheme: exp+<slug>
```
The keys and their validation are owned by the CLI's [`config.rs`](https://github.com/Lykhoyda/QaReN/blob/develop/packages/qaren-cli/src/config.rs).
If the operator supplies custom registry credential environment names, optionally
add `registryAuthEnv: [PRIVATE_REGISTRY_TOKEN]` using names only, never values.
Keep the default configuration above minimal; obtain names from the operator
rather than reading auth stores to detect them. The list exposes inherited
variables to install/prebuild descendants and withholds their output; follow the
[CLI registry-auth policy](https://github.com/Lykhoyda/QaReN/blob/develop/packages/qaren-cli/README.md#check-a-plan), including reserved names and the prewarm-fetch exclusion.
## 4. Device
Read the simulator inventory; never boot, shut down or erase a simulator yourself:
```sh
xcrun simctl list devices booted -j
```
- One booted simulator: pass no device flag.
- None booted: choose the newest available iPhone from `xcrun simctl list devices available -j` and pass `--boot-device --device <udid>`; qaren boots it under its device lease.
- Several booted: ask the user which one, then pass `--device <udid>`.
## 5. Smoke plan
Read the app's launch path in source (its root navigator and any auth gate) and pick one static text the user sees on the screen the app opens on; the `✓` check reads visible text, so never use a `testID` there. Never assume the signed-out screen: when a saved sign-in decides where the app opens, an earlier install's session on that simulator survives this run, so pick a text shown on launch both signed in and signed out, or ask the user which screen the app opens on now. Write `.qaren/plans/smoke.md`, quoted targets only:
```markdown
## QA
### First screen
1. Wait for "<text>" to appear
✓ "<text>"
```
This plan needs no `TYPESAFE_API_KEY`.
## 6. Run
The first run builds and installs the app; a cold iOS build needs about 10 GiB free on the home and app volumes (`check` refuses `DISK_BUDGET_EXCEEDED` with less) and can take longer than 10 minutes, and Claude Code stops both foreground and background commands at that limit. Start the check detached from the host, with `sh` staying resident as its parent: qaren cancels a run whose calling process exits, so never background `qaren` itself with `&` or `nohup`.
First create the output directory and note the path it prints as `<dir>`:
```sh
mktemp -d "${TMPDIR:-/tmp}/qaren-setup.XXXXXX"
```
Then start the check; this command returns at once:
```sh
nohup sh -c '<qaren path from step 1> check --plan-file .qaren/plans/smoke.md [device flags from step 4] --json > <dir>/receipt.json 2> <dir>/progress.log; echo $? > <dir>/exit' < /dev/null > /dev/null 2>&1 &
```
Within a minute `<dir>/progress.log` contains `▸ watch live: qaren watch <run-id>`; tell the user they can follow the run live with `qaren watch <run-id>` in their own terminal. If `<dir>/exit` appears first, the check refused before its run started, so go to the receipt, or to `<dir>/progress.log` when the receipt is empty. Otherwise follow the run in short calls that each end well within the host's limit, repeating until `<dir>/exit` exists:
```sh
for i in $(seq 20); do [ -s <dir>/exit ] && break; sleep 5; done; tail -n 3 <dir>/progress.log
```
Stopping a poll never affects the run. If `<dir>/exit` never appears, `<qaren path> status <run-id> --json` reports the run's state and its next action.
Once `<dir>/exit` exists, read `<dir>/receipt.json`; if it is empty, report the exit code and the diagnostic from `<dir>/progress.log` and stop. Otherwise report the receipt's `result`, `run_id` and `next_action`. When `result` is not `pass`, quote `failure.code` and `failure.next_action` verbatim if present and stop. When a `pass` receipt's `next_action` is a `qaren cleanup` command, teardown was incomplete: offer to run it. On `pass`, continue to step 7.
## 7. Sign-in (optional)
If the launch path read in step 5 has no auth gate, setup is complete; use `using-qaren` for a feature plan. Otherwise offer to save a reusable sign-in block. Start it on the sign-in screen; put any sign-out steps in their own block above it. Use visible labels when the app has no testIDs. Write a `### Sign in` block using names only:
```markdown
### Sign in
1. Fill "<username field>" with input USERNAME
2. Fill "<password field>" with input PASSWORD
3. Tap "<sign-in button>"
✓ "<signed-in text>"
```
For input echoes and optional echo declarations, follow the [runtime-input hash protections](https://github.com/Lykhoyda/QaReN/blob/develop/packages/qaren-cli/README.md#runtime-inputs). Ask the user to export `QAREN_INPUT_USERNAME` and `QAREN_INPUT_PASSWORD` from their password manager in their own shell; keep values out of plans, messages and tool output. Ensure the check inherits that shell's inputs. Use the same app configuration and device flags as step 6; for a label-only app, follow the README's [runtime-input prerequisites](https://github.com/Lykhoyda/QaReN/blob/develop/packages/qaren-cli/README.md#runtime-inputs).
Run this plan once using step 6's run-and-wait procedure. Read the receipt's `hints` and stderr: when `LOGIN_BLOCK_CANDIDATE` names a likely login block and prints `loginBlock` and `loginMarker`, ask the user to confirm that block signs in, then show those lines and paste them into `.qaren/config.yaml` only with the user's consent, as in step 3. When `LOGIN_MARKER_MISMATCH` appears, confirm with the user that the configured marker is visible only on the sign-in screen, or switch to the printed first selector. When `LOGIN_BLOCK_NO_INPUTS` appears, re-save the block as it says. When `LOGIN_BLOCK_RUN_ONLY` appears, the block exists only in that PR run's evidence: save it with `qaren check` in the main copy before configuring login. If `LOGIN_BLOCK_SIGNS_OUT` appears, split out the sign-out steps and re-save the sign-in block before configuring it. Follow `CORPUS_NOT_SHARED` when working in a linked worktree. If no block was saved, read `blocks_not_saved` and resolve its reason; do not invent a marker or login configuration.
Confirm `<qaren path> doctor` reports the saved login for the selected platform. Every later run needs the configured login block's `QAREN_INPUT_<NAME>` variables. The [worked example](https://github.com/Lykhoyda/QaReN/blob/develop/packages/qaren-cli/README.md#reusable-sign-in-example) covers setup, replay and worktrees. QaReN is now set up; use `using-qaren` for a feature plan.
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · lykhoyda/qaren | 100 | MIT |
| HwangSlater/harness-fit | 100 | MIT |
| nesquikm/dev-process-toolkit | 100 | MIT |
| userKael/rastro | 100 | MIT |
| als-apg/osprey | 100 | BSD-3-Clause |
| dedujeong/gemba | 100 | Apache-2.0 |
| eigenwise/eigenwise-toolshed | 100 | MIT |
| awrshift/agent-memory-kit | 100 | MIT |
| lifecycle-innovations-limited/claude-ops | 100 | MIT |
Database snapshot: 13.11.2026 · package version e4379074bd5d (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100using-qaren
Entry point for QaReN: QA a React Native app on the simulator with the qaren CLI. Use when the user wants to test a feature, write a QA plan, check the working tree or QA a pull request. - 100feedback
Use when the user wants to report a QaReN bug or request a feature. Drafts a sanitized GitHub issue and files it only after the user confirms. - 100setup-learninghub
Set up the Learning Hub sample after cloning it - copy it into its own folder, install dependencies, sign in with the ms CLI, create the app and its platform-managed git repository with ms app init (writes ms.config.json), hide the host header, add the Office 365 Users… - 100setup-issue-loop
Install issue-loop into a target repository, collect and validate its config, check the tracker, intake, runner, and app-control skill, hand off the two automations, and run the thread-safety test. Use for first install or any config change. - 100coderabbit-config
Create, update, or validate CodeRabbit repository configuration through the official CLI. Use for .coderabbit.yaml or .coderabbit.yml setup, review-style changes, path guidance, and configuration validation requests. - 100installing-cli-tools
Install, upgrade, configure, and verify developer CLI tools safely. Use when a user asks to install a new CLI, command-line app, SDK tool, package-manager binary, GitHub release binary, language runtime tool, or AI/vendor CLI; configure shell PATH/completions; run first login;…