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
-[Passing input from stdin](#passing-input-from-stdin)
22
+
-[Overriding Task and Wait states](#overriding-task-and-wait-states)
23
+
-[Task state override](#task-state-override)
24
+
-[Wait state override](#wait-state-override)
25
+
-[Disabling ASL validations](#disabling-asl-validations)
26
+
-[Exit codes](#exit-codes)
19
27
-[Examples](#examples)
20
28
-[License](#license)
21
29
@@ -49,7 +57,7 @@ import { StateMachine } from 'aws-local-stepfunctions';
49
57
50
58
You can import the bundled package directly into a browser script as an ES module, from one of the following CDNs:
51
59
52
-
> NOTE: The following examples will import the latest package version. Refer to the CDNs websites to know about other ways in which you can specify the package URL (for example, to import a specific version).
60
+
> NOTE: The following examples will import the latest package version. Refer to the CDNs websites to know about other ways in which you can specify the package URL (for example, to import a specific version or a minified version).
53
61
54
62
#### [unpkg](https://unpkg.com/)
55
63
@@ -122,7 +130,7 @@ Each execution is independent of all others, meaning that you can concurrently c
122
130
-`options?`:
123
131
-`overrides?`: An object to override the behavior of certain states:
124
132
-`taskResourceLocalHandlers?`: An [object that overrides](/docs/feature-support.md#task-state-resource-override) the resource of the specified `Task` states to run a local function.
125
-
-`waitTimeOverrides?`: An [object that overrides](/docs/feature-support.md#wait-state-duration-override) the wait duration of the specified `Wait` states. The specifed override duration should be in milliseconds.
133
+
-`waitTimeOverrides?`: An [object that overrides](/docs/feature-support.md#wait-state-duration-override) the wait duration of the specified `Wait` states. The specified override duration should be in milliseconds.
126
134
-`noThrowOnAbort?`: If this option is set to `true`, aborting the execution will simply return `null` as result instead of throwing.
127
135
128
136
#### Basic example:
@@ -149,6 +157,167 @@ const result = await execution.result; // wait until the execution finishes to g
149
157
console.log(result); // log the result of the execution
150
158
```
151
159
160
+
## CLI
161
+
162
+
In addition to the JavaScript API, `aws-local-stepfunctions` also provides a command-line interface. The CLI allows you to run one or several executions without having to create a Node.js script.
163
+
164
+
To use the CLI as a global shell command, you need to install the package globally:
165
+
166
+
```sh
167
+
npm install -g aws-local-stepfunctions
168
+
```
169
+
170
+
After installing the package, the command `local-sfn` will be available in your shell.
171
+
172
+
### Basic usage
173
+
174
+
The simplest way to use the CLI is by passing either the `-d, --definition` or the `-f, --definition-file` option, along with the input(s) for the state machine. For example:
175
+
176
+
```sh
177
+
local-sfn \
178
+
-f state-machine.json \
179
+
'{ "num1": 1, "num2": 2 }' \
180
+
'{ "num1": 3, "num2": 4 }' \
181
+
'{ "num1": 5, "num2": 6 }'
182
+
```
183
+
184
+
This command would execute the state machine defined in file `state-machine.json` with `'{ "num1": 1, "num2": 2 }'`, `'{ "num1": 3, "num2": 4 }'`, and `'{ "num1": 5, "num2": 6 }'` as inputs. Each input corresponds to a state machine execution, and each execution is run independently, so the failure of one execution doesn't mean the failure of all of the other executions.
185
+
186
+
Now, suppose the state machine in file `state-machine.json` is defined as a single `Task` state that calls a Lambda function that adds `num1` and `num2`:
Then, the output of the `local-sfn` command above may look something like this:
204
+
205
+
```sh
206
+
3
207
+
7
208
+
11
209
+
```
210
+
211
+
Note that each line of the output corresponds to the result of each input, in the same order that the inputs were given to the command.
212
+
213
+
### Passing input from stdin
214
+
215
+
`local-sfn` can also read the execution input from the standard input. For example, assume you have the following text file, called `inputs.txt`, and you want to pass the contents of the file as inputs to `local-sfn`:
216
+
217
+
```txt
218
+
{ "num1": 1, "num2": 2 }
219
+
{ "num1": 3, "num2": 4 }
220
+
{ "num1": 5, "num2": 6 }
221
+
```
222
+
223
+
You can then run the following command to pass the inputs of the text file to `local-sfn`:
224
+
225
+
```sh
226
+
cat inputs.txt | local-sfn -f state-machine.json
227
+
```
228
+
229
+
Alternatively, using input redirection:
230
+
231
+
```sh
232
+
local-sfn -f state-machine.json < inputs.txt
233
+
```
234
+
235
+
When reading from stdin, `local-sfn` will take each line and use it as an input. Hence, to avoid any parsing errors, make sure the output of the command you're piping into `local-sfn` prints each input in a new line.
236
+
237
+
### Overriding Task and Wait states
238
+
239
+
As explained in the Feature support document, it's possible to override the default actions of [`Task` states](/docs/feature-support.md#task-state-resource-override) and [`Wait` states](/docs/feature-support.md#wait-state-duration-override).
240
+
241
+
#### Task state override
242
+
243
+
To override a `Task` state, pass the `-t, --override-task` option. This option takes as value the name of the `Task` state you want to override, and a path to a script or program that will be executed instead of the resource specified in the state definition. The state name and the path must be separated by a colon `:`.
244
+
245
+
Using the same [state machine definition](#cli-state-machine) as before, if you wanted to override the `AddNumbers` state to run a custom script, you can do it like this:
This command would run the state machine, but instead of invoking the Lambda function specified in the `Resource` field of the `AddNumbers` state, the `override.sh` script would be executed.
252
+
253
+
Now, suppose the `override.sh` script is defined like this:
254
+
255
+
```sh
256
+
#!/bin/sh
257
+
258
+
TASK_INPUT=$1# First argument is the input to the overridden Task state
259
+
echo"$TASK_INPUT"| jq '.num1 + .num2'# Use jq to add "num1" and "num2", and print result to stdout
260
+
```
261
+
262
+
When overriding a `Task` state, the overriding executable will be passed the input to the `Task` state as first argument, which can then be used to compute the task result. Similarly, the executable must print the task result as a JSON value to the standard output, so `local-sfn` can then read stdout and use the value as the result of the `Task` state. If the executable terminates with an exit code different from `0`, its standard error will be printed and the execution will be marked as a failure.
263
+
264
+
Additionally, you can pass the `-t, --override-task` option multiple times, to override more than one `Task` state. For example:
265
+
266
+
```sh
267
+
local-sfn
268
+
-f state-machine.json \
269
+
-t AddNumbers:./override.sh \
270
+
-t SendRequest:./request.py \
271
+
-t ProcessImage:./proc_image \
272
+
'{ "num1": 1, "num2": 2 }'
273
+
```
274
+
275
+
This command would execute the state machine, and override `Task` states `AddNumbers`, `SendRequest`, and `ProcessImage` to run the `override.sh` shell script, the `request.py` Python script, and the `proc_image` program, respectively.
276
+
277
+
#### Wait state override
278
+
279
+
To override the duration of a `Wait` state, pass the `-w, --override-wait` option. This option takes as value the name of the `Wait` state you want to override, and a number that represents the amount in milliseconds that you want to pause the execution for. The state name and the milliseconds amount must be separated by a colon `:`.
This command would execute the state machine, and when entering the `WaitResponse``Wait` state, the execution would be paused for 1500 milliseconds (1.5 seconds), disregarding the `Seconds`, `Timestamp`, `SecondsPath`, or `TimestampPath` fields that could've been specified in the definition of `WaitResponse`.
288
+
289
+
In the same way as the `-t, --override-task` option, you can pass the `-w, --override-wait` option multiple times, to override more than one `Wait` state. For example:
290
+
291
+
```sh
292
+
local-sfn \
293
+
-f state-machine.json \
294
+
-w WaitResponse:1500 \
295
+
-w PauseUntilSignal:250 \
296
+
-w Delay:0 \
297
+
'{ "num1": 1, "num2": 2 }'
298
+
```
299
+
300
+
This command would execute the state machine, and override `Wait` states `WaitResponse` and `PauseUntilSignal` to pause the execution for 1500 and 250 milliseconds, respectively. The `Delay` state wouldn't be paused at all, since the override value is set to 0.
301
+
302
+
### Disabling ASL validations
303
+
304
+
Before attempting to run the state machine with the given inputs, the state machine definition itself is validated to check that:
305
+
306
+
- JSONPath strings are valid.
307
+
- ARNs in the `Resource` field of `Task` states are valid.
308
+
309
+
If any of these two checks fail, `local-sfn` will print the validation error and exit. To suppress this behavior, you can pass the `--no-jsonpath-validation` option, to suppress JSONPath validation; and the `--no-arn-validation` option, to suppress ARN validation.
310
+
311
+
### Exit codes
312
+
313
+
`local-sfn` can terminate with the following exit codes:
0 commit comments