IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Monitor resources on private networks Configure Synthetics projects »

› ›

Use the Synthetics CLI

edit

Use the Synthetics CLI

edit

`@elastic/synthetics`

edit

The Synthetics app uses the npx @elastic/synthetics command to run and report synthetic tests. It can also be used locally to help develop your tests.

npx @elastic/synthetics [options] [files] [dir]

You will not need to use most command line flags — they have been implemented purely to interact with the Synthetics app. However, there are some you may find useful:

--match <string>

Filters journey with the name or a matching tag.

--tags Array<string>

Filters journey with the given tag(s).

--reporter <junit|default|json>

One of junit, default, or json. Use the JUnit reporter to provide easily parsed output to CI servers like Jenkins.

--inline

Instead of reading from a file, cat inline scripted journeys and pipe them through stdin. For example, cat path/to/file.js | npx @elastic/synthetics --inline.

--params <jsonstring>

A JSON object that defines any variables your tests require. Read more in Work with params and secrets.

Params passed will be merged with params defined in your synthetics.config.js file. Params defined via the CLI take precedence.

--playwright-options <jsonstring>

JSON object to pass in custom Playwright options for the agent. For more details on relevant Playwright options, refer to the the configuration docs.

Options passed will be merged with Playwright options defined in your synthetics.config.js file. Options defined via the CLI take precedence.

--screenshots <on|off|only-on-failure>

Control whether or not to capture screenshots. Options include 'on', 'off', or 'only-on-failure'.

This can also be set in the configuration file using monitor.screenshot. The value defined via the CLI will take precedence.

--no-throttling

Does not apply throttling.

Throttling can also be disabled in the configuration file using monitor.throttling. The value defined via the CLI will take precedence.

--no-headless

Runs with the browser in headful mode.

This is the same as setting Playwright’s headless option to false by running --playwright-options '{"headless": false}'.

Headful mode should only be used locally to see the browser and interact with DOM elements directly for testing purposes. Do not attempt to run in headful mode when running through Elastic’s global managed testing infrastructure or Private Locations as this is not supported.

-h, --help: Shows help for the npx @elastic/synthetics command.

The --tags and --match flags for filtering are only supported when you grep or run synthetic tests locally. Filtering is not supported in any other subcommands like init, push, and locations.

For debugging synthetic tests locally, you can set an environment variable, DEBUG=synthetics, to capture Synthetics agent logs when running npx @elastic/synthetics.

`@elastic/synthetics init`

edit

Scaffold a new project using Elastic Synthetics.

This will create a template Node.js project that includes the synthetics agent, required dependencies, a synthetics configuration file, and example journey files. These journeys can be edited and then pushed to Kibana to create monitors.

npx @elastic/synthetics init <name-of-project>

Read more about what’s included in a template project in Create a project.

`@elastic/synthetics push`

edit

Create monitors in Kibana by using your local journeys.

npx @elastic/synthetics push --auth <api-key> --url <kibana-url> --id <id|name>

The push command includes interactive prompts to prevent you from accidentally deleting or duplicating monitors. You will see a prompt when:

You push a project that used to contain one or more monitors but no longer contains any monitors. Select yes to delete all monitors associated with the project ID being pushed.
You push a project that’s already been pushed using one project ID and then try to push it using a different ID. Select yes to create duplicates of all monitors in the project.

If the journey contains external NPM packages other than the @elastic/synthetics, those packages will be bundled along with the journey code when the push command is invoked. However there are some limitations when using external packages:

Bundled journeys after compression should not be more than 800 Kilobytes.
Native node modules will not work as expected due to platform inconsistency.

--auth <string>

API key used for Kibana authentication.

If you are pushing to a Private Location, you must use an API key generated in 8.4 or higher.

To create an API key, you must be logged into Kibana as a user with the privileges described in Writer role.

--id <string>

A unique id associated with your project. It will be used for logically grouping monitors.

If you used init to create a project, this is the <name-of-project> you specified.

This can also be set in the configuration file using project.id. The value defined via the CLI will take precedence.

--url <string>

The Kibana URL for the deployment to which you want to upload the monitors.

This can also be set in the configuration file using project.url. The value defined via the CLI will take precedence.

--space <string>

The identifier of the target Kibana space for the pushed monitors. Spaces help you organize pushed monitors. Pushes to the "default" space if not specified.

This can also be set in the configuration file using project.space. The value defined via the CLI will take precedence.

--schedule <number>

The interval (in minutes) at which the monitor should run.

This can also be set in the configuration file using monitor.schedule. The value defined via the CLI will take precedence.

--locations Array<SyntheticsLocationsType>

Where to deploy the monitor. Monitors can be deployed in multiple locations so that you can detect differences in availability and response times across those locations.

To list available locations, refer to @elastic/synthetics locations.

This can also be set in the configuration file using monitor.locations in the configuration file. The value defined via the CLI will take precedence.

--private-locations Array<string>

The Private Locations to which the monitors will be deployed. These Private Locations refer to locations hosted and managed by you, whereas locations are hosted by Elastic. You can specify a Private Location using the location’s name.

To list available Private Locations, refer to @elastic/synthetics locations.

This can also be set in the configuration file using monitor.privateLocations in the configuration file. The value defined via the CLI will take precedence.

--yes

The push command includes interactive prompts to prevent you from accidentally deleting or duplicating monitors. If running the CLI non-interactively, you can override these prompts using the --yes option. When the --yes option is passed to push:

If you push a project that used to contain one or more monitors but no longer contains any monitors, all monitors associated with the project ID being pushed will be deleted.
If you push a project that’s already been pushed using one project ID and then try to push it using a different ID, it will create duplicates of all monitors in the project.

`@elastic/synthetics locations`

edit

List all available locations for running synthetics monitors.

npx @elastic/synthetics locations --url <kibana-host> --auth <api-key>

Run npx @elastic/synthetics locations with no flags to list all the available global locations managed by Elastic for running synthetics monitors.

To list both locations on Elastic’s global managed infrastructure and Private Locations, include:

--url <string>: The Kibana URL for the deployment from which to fetch all available public and Private Locations.
--auth <string>: API key used for Kibana authentication.

If an administrator has disabled Elastic managed locations for the role you are assigned and you do not include --url and --auth, all global locations managed by Elastic will be listed. However, you will not be able to push to these locations with your API key and will see an error: You don’t have permission to use Elastic managed global locations. For more details, refer to the troubleshooting docs.

« Monitor resources on private networks Configure Synthetics projects »