@qawolf/cli 1.8.1 → 1.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/dist/cli.js +1146 -17
  2. package/package.json +2 -2
  3. package/skills/qawolf-cli/SKILL.md +55 -39
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@qawolf/cli",
3
- "version": "1.8.1",
3
+ "version": "1.9.0",
4
4
  "description": "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
5
5
  "keywords": [
6
6
  "automation",
@@ -60,7 +60,7 @@
60
60
  "@clack/prompts": "1.5.1",
61
61
  "@napi-rs/keyring": "1.3.0",
62
62
  "@oxc-node/core": "0.1.0",
63
- "@qawolf/api-contracts": "0.24.0",
63
+ "@qawolf/api-contracts": "0.25.0",
64
64
  "@qawolf/emails": "1.1.1",
65
65
  "@qawolf/flow-targets": "1.0.0",
66
66
  "@qawolf/flows": "0.1.4",
package/skills/qawolf-cli/SKILL.md CHANGED
@@ -41,6 +41,19 @@ the target, ask instead of guessing. Do not default to the newest environment.
41
41
  listed name is enough to reference `process.env.NAME` in flow code; do not ask
42
42
  for its value merely because the CLI does not return it.
43
43
 
44
+ ## Interactive runners cost money
45
+
46
+ An interactive runner is a live pod holding a browser, and it is billed while it
47
+ runs. `qawolf runner launch` starts one; `qawolf runner run` starts one too when
48
+ no runner is already available, and says so when it does. Reading a runner
49
+ counts as activity, so `qawolf runner events --follow` left open keeps it alive
50
+ and billing. `qawolf runner stop` is what ends it, so stop a runner you launched
51
+ rather than leaving it to time out.
52
+
53
+ `qawolf runner launch` remembers its runner as this directory's default, so the
54
+ commands that follow need no `--runner`. Override that default for one command
55
+ with `--runner <id>`, or for a whole session with `QAWOLF_RUNNER_ID`.
56
+
44
57
  ## Output
45
58
 
46
59
  When consuming output programmatically, always pass `--json` (or `--agent`).
@@ -68,45 +81,48 @@ current branch.
68
81
 
69
82
  <!-- commands-table:start — generated by `bun run generate`, do not edit -->
70
83
 
71
- | Command | Kind | What it does |
72
- | -------------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
73
- | `qawolf auth login` | local | Authenticate with your QA Wolf API key |
74
- | `qawolf auth logout` | local | Remove stored credentials |
75
- | `qawolf auth whoami` | read | Show authentication status |
76
- | `qawolf automate` | write | Request automation for draft flows. First create a named local .flow.ts draft for every requested journey that does not already have a matching draft; never reuse a generic starter or placeholder. Each new draft must start with a JSDoc Goal: description, import flow from @qawolf/flows/web, and use export default flow(...); a comment-only file or direct test(...) call is not a valid draft. Commit and push all changes with Git to publish them, then list remote drafts to resolve every selected ID. Do not use patch to create or rename a selected flow. Finally make one automation request containing all requested flow IDs. |
77
- | `qawolf doctor` | local | Diagnose problems running flows locally |
78
- | `qawolf environment create` | write | Create an environment on the caller's team and return it in the environment.get shape. |
79
- | `qawolf environment deleteVariable` | write | Remove one environment variable by name. Succeeds whether or not the variable existed. |
80
- | `qawolf environment find` | read | List the team's environments, newest first. |
81
- | `qawolf environment get` | read | Read a single environment's name, kind, health status, run concurrency limit, and termination state. |
82
- | `qawolf environment getVariable` | read | Read the values of named environment variables in one call. Values are secrets. Names that do not exist go to missingNames and do not fail the call. |
83
- | `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. |
84
- | `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_ENVIRONMENT_EMAIL. The value is never returned. |
85
- | `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. |
86
- | `qawolf flow addTag` | write | Assign an existing tag to the selected flows. Create tags with tag.create. |
87
- | `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. |
88
- | `qawolf flows list` | local (read with --remote) | List flows matching [pattern] from the local project, or from a QA Wolf environment with --remote |
89
- | `qawolf flows pull` | read | Download an environment's flows into the local .qawolf/<env>/ cache |
90
- | `qawolf flows run` | local (read with --env) | Run flows matching [pattern], or every flow when omitted; with --env, pull missing flows from that QA Wolf environment |
91
- | `qawolf init` | local | Scaffold a QA Wolf project in the current directory |
92
- | `qawolf install` | local | Install every runtime dependency the project's flows need |
93
- | `qawolf install android` | local | Install Android system images, AVDs, and the Appium driver used by the project's Android flows |
94
- | `qawolf install browsers` | local | Install Playwright browsers used by the project's web flows |
95
- | `qawolf install clear` | local | Remove the managed runtime cache (all installed runtime versions) |
96
- | `qawolf issue create` | write | Create a bug or coverage request issue for the caller's team. Maintenance issues cannot be created through the public API. |
97
- | `qawolf issue find` | read | List the team's bug reports, maintenance reports, or coverage requests, newest first. |
98
- | `qawolf issue get` | read | Get an issue by id. |
99
- | `qawolf run create` | write | Create a run for the selected flows and/or tags in an environment. |
100
- | `qawolf run find` | read | List an environment's recent runs, newest first. |
101
- | `qawolf run get` | read | Get a run's status, per-flow results, and links. |
102
- | `qawolf runner evaluateSnippet` | write | Evaluate a snippet against whatever the runner's browser is showing right now. Answers whether the snippet ran, and its error if it threw — not the value it evaluated to, so read anything you want back out of the runner's journal (a snippet's `console.log` lands in the `console` stream). A snippet starts no run and leaves no run-scoped journal entries of its own. `runner-unreachable` if the runner could not be reached or could not evaluate: as well as a runner that is still starting, has terminated after inactivity, or is busy, this covers a runner with no live page to evaluate against — which will never clear, so check that the runner you launched is one that runs a browser before retrying. It is NOT proof the snippet did not run: a snippet that outlives the answer window is still executing when you read this, so do not blindly resubmit one that mutates what the page is looking at. |
103
- | `qawolf runner launch` | write | Launch an interactive runner on the caller's team under an id the caller chooses. Launching the same id again returns the runner already running rather than starting a second one, and the same id with a different runnerName is refused. A runner is not permanent: it terminates on its own after a period of inactivity, and launching the same id after that starts and bills a new runner — so read `outcome` to tell which happened. |
104
- | `qawolf runner readJournal` | read | Read a window of one of an interactive runner's journal streams — the newest few, everything after a cursor, or everything belonging to one run. This is how a flow run's outcome and output are followed: `run-status` settles it, `run-logs` and `run-events` carry what it produced, and `recorder` carries the browser actions the runner recorded. A read counts as activity, so working through history does not get the runner reaped underneath you. `runner-unreachable` if the runner could not be reached: it may still be starting, it may have terminated after inactivity, or it may be too busy to answer. Nothing was changed, so retrying is safe; if it persists, launch the runner again. |
105
- | `qawolf runner runFlow` | write | Run a flow on an interactive runner. Answers as soon as the run is accepted, with the id to follow it by — nothing waits for the run to finish. Which browser or device the run needs is read from the flow file's own execution target, so it is not supplied here; when it does not match what the runner is, the call answers `runner-target-mismatch` rather than failing partway through the run. `runner-unreachable` means the answer did not arrive, which is NOT the same as the run not having started: the runner may have accepted it and been too slow to say so, and resubmitting would start a second run that is billed and journalled alongside the first. Read the runner's `run-status` journal stream before resubmitting, and use the newest run id there if one appeared. |
106
- | `qawolf runner stop` | write | Stop an interactive runner on the caller's team. Stopping a runner that is not running succeeds and reports `not-running`, so a retry needs no special handling. |
107
- | `qawolf runner takeScreenshot` | read | Take one screenshot of an interactive runner's screen. The image is the runner's whole virtual desktop, browser window and all. `screen-needs-a-run` if the runner has not run anything yet, so its virtual desktop has never started. Waiting will not change this and retrying is pointless — call `runner.runFlow` on the runner, then ask for the screen again. Evaluating a snippet does not start the desktop. `screen-not-ready` if the runner has a screen that cannot serve this instant. Retry in a second or two: the desktop restarts when a run changes the display size, and it serves one see-or-act request at a time, so a screenshot or action already in flight is the usual reason. Do not submit a run to clear this — a run may restart the display and discard what is on it. `runner-has-no-screen` if this runner is not one that runs a browser on a virtual desktop. Nothing about it can be seen or driven, and retrying will never help — launch a `node20WithPlaywright` runner instead. `runner-unreachable` if the runner could not be reached: it may still be starting, it may have terminated after inactivity, or it may be too busy to answer. Nothing was changed, so retrying is safe; if it persists, launch the runner again. |
108
- | `qawolf tag create` | write | Create a tag on the caller's team. Tags select flows in run.create. |
109
- | `qawolf tag list` | read | List the team's tags, alphabetical by name. Tag names select flows in run.create. |
84
+ <!-- prettier-ignore -->
85
+ | Command | Kind | What it does |
86
+ | --- | --- | --- |
87
+ | `qawolf auth login` | local | Authenticate with your QA Wolf API key |
88
+ | `qawolf auth logout` | local | Remove stored credentials |
89
+ | `qawolf auth whoami` | read | Show authentication status |
90
+ | `qawolf automate` | write | Request automation for draft flows. First create a named local .flow.ts draft for every requested journey that does not already have a matching draft; never reuse a generic starter or placeholder. Each new draft must start with a JSDoc Goal: description, import flow from @qawolf/flows/web, and use export default flow(...); a comment-only file or direct test(...) call is not a valid draft. Commit and push all changes with Git to publish them, then list remote drafts to resolve every selected ID. Do not use patch to create or rename a selected flow. Finally make one automation request containing all requested flow IDs. |
91
+ | `qawolf doctor` | local | Diagnose problems running flows locally |
92
+ | `qawolf environment create` | write | Create an environment on the caller's team and return it in the environment.get shape. |
93
+ | `qawolf environment deleteVariable` | write | Remove one environment variable by name. Succeeds whether or not the variable existed. |
94
+ | `qawolf environment find` | read | List the team's environments, newest first. |
95
+ | `qawolf environment get` | read | Read a single environment's name, kind, health status, run concurrency limit, and termination state. |
96
+ | `qawolf environment getVariable` | read | Read the values of named environment variables in one call. Values are secrets. Names that do not exist go to missingNames and do not fail the call. |
97
+ | `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. |
98
+ | `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. |
99
+ | `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. |
100
+ | `qawolf flow addTag` | write | Assign an existing tag to the selected flows. Create tags with tag.create. |
101
+ | `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. |
102
+ | `qawolf flows list` | local (read with --remote) | List flows matching [pattern] from the local project, or from a QA Wolf environment with --remote |
103
+ | `qawolf flows pull` | read | Download an environment's flows into the local .qawolf/<env>/ cache |
104
+ | `qawolf flows run` | local (read with --env) | Run flows matching [pattern], or every flow when omitted; with --env, pull missing flows from that QA Wolf environment |
105
+ | `qawolf init` | local | Scaffold a QA Wolf project in the current directory |
106
+ | `qawolf install` | local | Install every runtime dependency the project's flows need |
107
+ | `qawolf install android` | local | Install Android system images, AVDs, and the Appium driver used by the project's Android flows |
108
+ | `qawolf install browsers` | local | Install Playwright browsers used by the project's web flows |
109
+ | `qawolf install clear` | local | Remove the managed runtime cache (all installed runtime versions) |
110
+ | `qawolf issue create` | write | Create a bug or coverage request issue for the caller's team. Maintenance issues cannot be created through the public API. |
111
+ | `qawolf issue find` | read | List the team's bug reports, maintenance reports, or coverage requests, newest first. |
112
+ | `qawolf issue get` | read | Get an issue by id. |
113
+ | `qawolf run create` | write | Create a run for the selected flows and/or tags in an environment. |
114
+ | `qawolf run find` | read | List an environment's recent runs, newest first. |
115
+ | `qawolf run get` | read | Get a run's status, per-flow results, and links. |
116
+ | `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 |
117
+ | `qawolf runner events` | read | Print a runner's journal, one entry per line. QA Wolf writes console, recorder, run-events, run-logs, run-status |
118
+ | `qawolf runner exec` | write | Evaluate a snippet against a runner's live page. Use - to read the snippet from stdin |
119
+ | `qawolf runner keepalive` | read | Reset a runner's inactivity clock, for a caller that pauses between actions |
120
+ | `qawolf runner launch` | write | Launch an interactive runner and make it this directory's default |
121
+ | `qawolf runner run` | write | Run a flow on an interactive runner, shipping the current directory's files with it |
122
+ | `qawolf runner screenshot` | read | Save a JPEG of an interactive runner's screen to a file |
123
+ | `qawolf runner stop` | write | Stop an interactive runner |
124
+ | `qawolf tag create` | write | Create a tag on the caller's team. Tags select flows in run.create. |
125
+ | `qawolf tag list` | read | List the team's tags, alphabetical by name. Tag names select flows in run.create. |
110
126
 
111
127
  <!-- commands-table:end -->
112
128