You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The `login` command opens a browser and logs in according to the settings. It accepts the following parameters:
83
+
The `action-runner` command executes one action flow from `actionRunner`, which can include browser automation, API requests, and shell commands. It accepts the following parameters:
84
84
85
-
| Long Parameter | Short Parameter | Required | Description |
| --action | -a | YES | Indicates the action the action-runner will perform |
88
+
| --verbose | -v | NO | Indicates whether to display logs during execution |
89
+
| --arg.\<name\>=value | — | NO | Passes a custom argument into the action's context |
90
+
91
+
**Custom arguments** let you pass values from the CLI into any action. For example:
92
+
93
+
```powershell
94
+
action-runner --action=perform-api-request "--arg.message=Hello from CLI"
95
+
```
96
+
97
+
Inside the action, `{{context.message}}` resolves to `"Hello from CLI"` (after a `getArguments` step maps it).
89
98
90
99
#### 3.1.2 Configuration
91
100
92
-
Before using the `login` command, you need to configure the desired actions. To do this, you need to create the `config.json` file in the `./config/` directory. There is an example of how this config should look in the same folder, and it is structured like this:
101
+
Before using the `action-runner` command, you need to configure the desired actions. To do this, you need to create the `config.json` file in the `./config/` directory. There is an example of how this config should look in the same folder (`config-example.json`).
102
+
103
+
Each action under `actionRunner` supports one of two formats:
104
+
105
+
**Simple login (legacy flat fields)** — username, password, then submit:
93
106
94
107
```json
95
108
{
96
-
"browseAndLogin": {
97
-
"[actions]": {
98
-
"url": "",
99
-
"usernameInput": "",
100
-
"usernameValue": "",
101
-
"passwordInput": "",
102
-
"passwordValue": "",
103
-
"loginButton": ""
109
+
"actionRunner": {
110
+
"simple-login": {
111
+
"url": "https://example.com/login",
112
+
"usernameInput": "#email",
113
+
"usernameValue": "user@example.com",
114
+
"passwordInput": "#password",
115
+
"passwordValue": "your-password",
116
+
"loginButton": "#submit"
104
117
}
105
118
}
106
119
}
107
120
```
108
121
109
-
Let's say you want to create a command that logs into your email. To do this, just replace "[action]" with "log-email" and fill in the other fields according to the access form IDs and your data.
122
+
**Multi-step login (`steps` array)** — use when you need extra clicks, waits, or a custom order (e.g. click "Next" after username):
110
123
111
-
> **_TIP:_** as browseAndLogin is an object of objects, you can have `n` login actions for different sites, as long as you add them to the config file properly.
**`setWebStorage`** injects data into the browser's web storage or cookies. This is useful for pre-authenticating sessions that require complex login flows (e.g. OTP codes). Values that are objects or arrays are automatically `JSON.stringify`-ed before being stored. Cookies use Puppeteer's native `page.setCookie()` format.
119
163
120
-
Function log-email {
121
-
param (
122
-
[string[]]$ExtraArgs
123
-
)
124
-
$loginCommand = "login"
125
-
$loginCommand += " --action=log-email"
126
-
echo $ExtraArgs
127
-
foreach ($arg in $ExtraArgs) {
128
-
echo $arg
129
-
if ($arg.StartsWith("--")) {
130
-
$loginCommand += " $arg"
131
-
} elseif ($arg.StartsWith("-")) {
132
-
$loginCommand += " $arg"
133
-
} else {
134
-
$loginCommand += " '$arg'"
164
+
Example:
165
+
166
+
```json
167
+
{
168
+
"action": "setWebStorage",
169
+
"localStorage": {
170
+
"token": "your-jwt-token",
171
+
"user": { "id": "123", "name": "john" }
172
+
}
173
+
}
174
+
```
175
+
176
+
> **_NOTE:_**`setWebStorage` must be used **after** a `navigate` step to the target domain, since localStorage/sessionStorage is bound to the page origin. To apply the injected session, add another `navigate` step after `setWebStorage` to reload the page.
177
+
178
+
**`closeBrowser`** gracefully closes the browser instance. Typically used as the last step in an action.
179
+
180
+
**`apiRequest`** calls HTTP endpoints directly. You can persist response data into runtime context with `storeAs`, then reuse it in later steps.
181
+
182
+
**`extractVariable`** stores a resolved value into context. Useful to assign short names such as the first task id.
183
+
184
+
**`shell`** executes shell commands (PowerShell by default) and can store command output in context.
185
+
186
+
**`getArguments`** validates and maps CLI arguments (passed via `--arg.<name>=<value>`) or parent-action arguments (via `invokeAction`) into the runtime context. Use `required` to list mandatory arguments (throws if missing), `optional` to list arguments that are mapped only when present, and `defaults` to provide fallback values for missing ones.
187
+
188
+
**`invokeAction`** calls another action defined in `actionRunner` config by name. The child action runs with an isolated context seeded from `args`. Use `storeAs` to copy the child's final context back into the parent. `continueOnError: true` prevents child failures from aborting the parent action. Recursion is capped at 5 levels.
What this configuration does is define an alias called login that runs the browse-and-login.bat file in this repository, then creates a function that executes the newly created "login" command, passing by default the argument `--action=log-email`. So, the following commands are equivalent:
226
+
**`tryCatch`** wraps steps in try/catch/finally semantics. If any step in `try` throws, the error message is stored in `context.errorMessage` and the `catch` steps run. `finally` steps always run regardless of success or failure. If no `catch` is defined, the error re-throws to the parent flow.
The `scheduler` command opens a browser and shows the list of scheduled jobs of the computer, it allows the CRUD actions for scheduled jobs. The command saves the scheduled jobs in a temporary file and starts a node server to serve the html files and routes, by default the command starts in a separated
310
+
The `scheduled-tasks/` folder contains an example PowerShell script that creates a Windows Scheduled Task to run any custom command on a recurring schedule. It uses `Register-ScheduledTask` to create a task with configurable weekly triggers. The task loads your `$PROFILE` before executing so that custom functions and aliases are available.
188
311
189
-
It accepts the following parameters:
190
-
191
-
| Long Parameter | Short Parameter | Required | Description |
|\_start\_|| NO | Starts the server in the same terminal that ran the command |
194
-
| --verbose | -v | NO | Indicates whether to display logs during execution |
312
+
You can find the example at `scheduled-tasks/setup-scheduled-task.example.ps1`.
195
313
196
314
#### 3.4.2 Configuration
197
315
198
-
Before using the `scheduler` command, you need to configure the server port that should be used (the default is 3002) and to insert the computer user password because this is needed to update scheduled tasks. To do this, you need to create/update the `config.json` file in the `./config/` directory. There is an example of how this config should look in the same folder, and it is structured like this:
316
+
1. Copy the example file and rename it (e.g. `setup-my-task.ps1`).
317
+
2. Open the copy and replace the placeholders:
318
+
-`$TaskName` — set a unique name for your scheduled task.
319
+
-`$triggerTimes` — set the times you want it to trigger (24h format).
320
+
-`$weekdays` — set the days of the week.
321
+
-`{{YOUR_COMMAND_HERE}}` — replace with the command or function you want to run (e.g. a function defined in your `$PROFILE`).
199
322
200
-
```json
201
-
{
202
-
"scheduler": {
203
-
"serverPort": 3002,
204
-
"userPassword": ""
205
-
}
206
-
}
323
+
3. Run the script once from an **elevated** (Administrator) PowerShell terminal:
324
+
325
+
```powershell
326
+
.\scheduled-tasks\setup-my-task.ps1
207
327
```
208
328
209
-
Similarly to the previous command and as mentioned in section 1.2 of this README, you need to configure the command in `$PROFILE`. Once the profile is open, the command looks like this:
> **_NOTE:_** make sure the command you reference is already defined in your `$PROFILE` before running the setup script, since the scheduled task depends on it.
0 commit comments