@qawolf/cli 1.27.0 → 1.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qawolf/cli",
-  "version": "1.27.0",
+  "version": "1.29.0",
   "description": "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
   "keywords": [
     "automation",
@@ -71,7 +71,7 @@
     "@clack/prompts": "1.5.1",
     "@napi-rs/keyring": "1.3.0",
     "@oxc-node/core": "0.1.0",
-    "@qawolf/api-contracts": "0.52.0",
+    "@qawolf/api-contracts": "0.53.0",
     "@qawolf/emails": "1.1.1",
     "@qawolf/flow-targets": "1.0.0",
     "@qawolf/flows": "0.1.4",

package/skills/qawolf-cli/SKILL.md

@@ -125,7 +125,7 @@ that `url`; never guess a route and never send a repository link in its place.
 <!-- prettier-ignore -->
 | Command | Kind | What it does |
 | --- | --- | --- |
-| `qawolf agent get` | read | Monitor a QA Wolf AI session by reading its status and replies. After agent.send, share the returned session URL before monitoring. Wait 30 to 60 seconds between checks; do not call this in a tight loop. Replies accumulate, so compare them with what you have already seen. Continue monitoring silently when the status and replies are unchanged; do not narrate waiting, announce the next check, or ask whether to keep monitoring. Report only substantive new progress, questions, blockers, or the final outcome. A status of "waiting-for-you" means the last reply is a question the work is blocked on, and answering it with agent.send is what unblocks it. Surface an explicit request for user input even if the status still says "working". Include the session URL when reporting a blocker or final outcome. On "completed", stop status checks and verify the requested result before claiming success. For new flows, validation, publication in the target environment, and readiness are separate checks; a Git push or final reply does not prove the flow is active. If every requested result is verified but status remains "working", report the mismatch and stop monitoring. Stop on "failed" or "cancelled" and report any confirmed partial result. |
+| `qawolf agent get` | read | Monitor a QA Wolf AI session by reading its status and replies. After agent.send, share the returned session URL before monitoring. Wait 30 to 60 seconds between checks; do not call this in a tight loop. Pass the nextCursor from one response as the cursor on the next check; it then reads only what is new, and only for the session that minted it. Continue monitoring silently when the status is unchanged and no replies come back; do not narrate waiting, announce the next check, or ask whether to keep monitoring. Report only substantive new progress, questions, blockers, or the final outcome. A status of "waiting-for-you" means the last reply is a question the work is blocked on, and answering it with agent.send is what unblocks it. Surface an explicit request for user input even if the status still says "working". Include the session URL when reporting a blocker or final outcome. On "completed", stop status checks and verify the requested result before claiming success. For new flows, validation, publication in the target environment, and readiness are separate checks; a Git push or final reply does not prove the flow is active. If every requested result is verified but status remains "working", report the mismatch and stop monitoring. Stop on "failed" or "cancelled" and report any confirmed partial result. |
 | `qawolf agent send` | write | Start or continue work with the QA Wolf AI and return a live session URL to share with the user. Use it to cover a user journey, investigate a failing run, or fix a broken flow. This is the one verb that starts work from nothing: every other write acts on a flow, run or issue that already exists. Returns sessionId, status, and url as soon as the request is accepted; work can take minutes to tens of minutes. After each send, make the next action a normal user-visible assistant message containing the exact returned url, before any tool call or wait. Tool output and internal reasoning do not count as sharing the link. Do not run a timer or monitoring call alongside this send. Acceptance does not mean the work is complete. Then monitor the session with agent.get, reporting new progress, blockers, and the final outcome rather than unchanged status. Send here again to answer a question or add context to the same session. |
 | `qawolf auth login` | local | Authenticate with QA Wolf in a browser or with an API key |
 | `qawolf auth logout` | local | Remove stored credentials |
@@ -139,7 +139,7 @@ that `url`; never guess a route and never send a repository link in its place.
 | `qawolf email listAddresses` | read | List the workspace's inbox addresses, alphabetical. A flow can sign up with a plus-suffixed form of any of them, and email.find reads what arrives. |
 | `qawolf email registerAddress` | write | Register an inbox address for the workspace. Registering an address the workspace already has changes nothing. A refusal names the domains the workspace can use. |
 | `qawolf email send` | write | Send an email from one of the workspace's inbox addresses, for example to exercise a flow that reacts to incoming mail. Returns the sent email; read it back with email.get. |
-| `qawolf environment create` | write | Create an environment on the caller's team and return it in the environment.get shape. |
+| `qawolf environment create` | write | Create an environment on the caller's team and return it in the environment.get shape. This can also create a branch on the team's connected Git provider. |
 | `qawolf environment deleteVariable` | write | Remove one environment variable by name. Succeeds whether or not the variable existed. |
 | `qawolf environment find` | read | List the team's environments, newest first. |
 | `qawolf environment get` | read | Read a single environment's name, kind, standing run health, flow-code branch and reconciliation state, run concurrency limit, and termination state. If flowCodeBranch exists, use its syncStatus for Git reconciliation and read lastSyncedCommitHash only when syncStatus is reconciled. |
@@ -147,6 +147,8 @@ that `url`; never guess a route and never send a repository link in its place.
 | `qawolf environment listVariableNames` | read | Use this to answer which QA Wolf environment variables are available to test code. Returns names only; values never leave the server. |
 | `qawolf environment setVariable` | write | Create or replace an environment variable. If the user asks to create one for "my email" without naming it, use DEFAULT_EMAIL. The value is never returned. |
 | `qawolf environment update` | write | Update an environment owned by the caller's team and return it in the environment.get shape. Omitted fields remain unchanged. |
+| `qawolf file requestDownload` | read | Get a URL for reading a file out of the caller's team storage. Answers 404 when nothing is stored at that path. |
+| `qawolf file requestUpload` | write | Get a URL to put a file into team storage: a spreadsheet of journeys, anything too large to paste. PUT with the returned contentType, then name the path in filePaths. |
 | `qawolf flow addTag` | write | Assign an existing tag to the selected flows. Create tags with tag.create. Flows that already carry the tag are reported in skippedFlows. |
 | `qawolf flow removeTag` | write | Remove a tag from the selected flows. Succeeds whether or not each flow carried the tag; the flows that did not are reported in skippedFlows. |
 | `qawolf flow update` | write | Move a flow between draft and active readiness. The other statuses shown in the app are derived and cannot be set. |
@@ -169,7 +171,7 @@ that `url`; never guess a route and never send a repository link in its place.
 | `qawolf run find` | read | List an environment's recent runs, newest first. |
 | `qawolf run get` | read | Get a run's status, per-flow results, and links. |
 | `qawolf run reattempt` | write | Request new attempts for a run's flows, in the same run. A flow is eligible once its result is failed or canceled and QA Wolf's automatic retries have finished. A fully investigated run no longer accepts reattempts. Attempts run with the latest flow code. Poll run.get for results. |
-| `qawolf run stop` | write | Stop a run, including its queued flows and automatic retries. Stopping is asynchronous. Repeated requests are safe, and finished runs keep their results. A run that is still being created returns not found; retry once run.get returns the run. If run.get returns a different runId, use that ID. Poll run.get for results. |
+| `qawolf run stop` | write | Stop a run, including its queued flows and automatic retries. Stopping is asynchronous and can update run-status messages and commit statuses in connected integrations. Repeated requests are safe, and finished runs keep their results. A run that is still being created returns not found; retry once run.get returns the run. If run.get returns a different runId, use that ID. Poll run.get for results. |
 | `qawolf runner act` | write | Perform one raw action on a runner's screen: click, double_click, scroll, move, drag, keypress, navigate or type. Use - to read a whole action as JSON from stdin. On a mobile runner only click (button left), drag and type have a touchscreen equivalent; the rest answer action-not-supported-on-mobile |
 | `qawolf runner events` | read | Print a runner's journal, one entry per line. QA Wolf writes console, recorder, run-events, run-logs, run-status |
 | `qawolf runner exec` | write | Evaluate a snippet against a runner's live page. Use - to read the snippet from stdin |
@@ -177,7 +179,7 @@ that `url`; never guess a route and never send a repository link in its place.
 | `qawolf runner import-package` | write | Install a package into a runner's live run, so a snippet or a selection can import it |
 | `qawolf runner inspect contexts` | read | List the WebView contexts available, and which is current |
 | `qawolf runner inspect element-html` | read | Print the HTML of the first element a selector matches |
-| `qawolf runner inspect elements` | read | Find elements at a screen point, or elements carrying some text |
+| `qawolf runner inspect elements` | read | Find elements at a screen point, carrying some text, or matching a selector |
 | `qawolf runner inspect page-html` | read | Print the page's HTML, simplified for a model to read |
 | `qawolf runner inspect page-source` | read | Print the current context's page source, as a tree |
 | `qawolf runner inspect session` | read | Print the Appium session's status: ready, or why not |
@@ -192,6 +194,13 @@ that `url`; never guess a route and never send a repository link in its place.
 | `qawolf runner terminate` | write | End an interactive runner, and the pod it runs on with it |
 | `qawolf tag create` | write | Create a tag on the caller's team. Tags select flows in run.create. |
 | `qawolf tag list` | read | List the team's tags, alphabetical by name. Tag names select flows in run.create. |
+| `qawolf trigger create` | write | Create a trigger. A schedule trigger runs a named set of flows on a cadence; a deployment trigger runs when a matching deployment is reported. |
+| `qawolf trigger delete` | write | Delete a trigger permanently. The runs it already created are kept. To stop a trigger without losing it, use trigger.pause. |
+| `qawolf trigger find` | read | List the team's triggers, newest first. |
+| `qawolf trigger get` | read | Get one trigger by id. |
+| `qawolf trigger pause` | write | Pause a trigger so it stops firing. Pausing is idempotent. A team whose triggers are all paused reports no trigger activity at all. |
+| `qawolf trigger resume` | write | Resume a paused trigger. A schedule trigger restarts from the next upcoming slot: the slots it missed while paused do not run. |
+| `qawolf trigger update` | write | Replace a trigger's configuration. Every field is written, so read the trigger first and send its configuration back with your changes applied. Pausing is separate: use trigger.pause and trigger.resume. |
 
 <!-- commands-table:end -->
 

package/skills/qawolf-cli/references/runner.md

@@ -232,8 +232,10 @@ qawolf runner inspect session
 qawolf runner inspect contexts
 qawolf runner inspect page-source
 qawolf runner inspect page-source --context WEBVIEW_1     # a specific context, not the current one
-qawolf runner inspect elements --by point --x 240 --y 480
-qawolf runner inspect elements --by text --text "Sign in" --partial
+qawolf runner inspect elements --x 240 --y 480
+qawolf runner inspect elements --text "Sign in" --partial
+qawolf runner inspect elements --selector "//android.widget.Button[@text='Sign in']"
+qawolf runner inspect elements --selector "@label == 'Sign in'" --strategy ios-predicate
 ```
 
 `session` prints one summary line — ready, or why not — because that line is
@@ -253,15 +255,21 @@ runner yet — run a flow that opens one, then inspect again; `screen-not-ready`
 exits `4` and means the session exists but did not answer this instant, or more
 than one is somehow live — retry once, and relaunch the runner if it persists.
 
-`elements` takes one of two ways to search, chosen with `--by`: `point` needs
-whole-pixel `--x`/`--y` on the device's own screen, the same coordinates a
-screenshot is measured in; `text` needs `--text` and matches it exactly unless
-`--partial` is passed. The two do not mix — `--by point` with `--text` set, or
-`--by text` with `--x`/`--y` set, is refused before a runner is addressed
-rather than silently searching by the one it picked, since the schema itself
-just strips whichever field the chosen `by` does not define. `--context` on
-`page-source` or `elements` reads a context other than the current one —
-useful once `contexts` has told you which are available.
+`elements` takes one of three ways to search: whole-pixel `--x`/`--y` on the
+device's own screen, the same coordinates a screenshot is measured in;
+`--text`, which matches exactly unless `--partial` is passed; or `--selector`,
+resolved the same way a screen object's own selector is, with `--strategy`
+naming how (`xpath`, `ios-predicate` or `shadow`; defaults to `xpath`). Prefer
+`--selector` when checking a selector you are about to write: it answers what
+that exact string resolves to, where `--text`/`--x`/`--y` only approximate it.
+The three do not mix — passing flags from more than one at once is refused
+before a runner is addressed rather than silently searching by whichever one
+it picked. An unparseable selector answers `invalid-selector`, exit `2`,
+distinctly from a selector that parsed fine but matched nothing, which answers
+an empty `matches` list, exit `0` — the same distinction `highlight-selector`
+draws on a browser runner. `--context` on `page-source` or `elements` reads a
+context other than the current one — useful once `contexts` has told you which
+are available.
 
 A browser runner answers `runner-is-not-mobile` to all four, exit `2`, since
 retrying never helps: launch with `--name android` or `--name ios` instead.