CLI Command Reference | Calibre Documentation

calibre site#

calibre site create#

Add a Site for Calibre to monitor.

calibre site create <name> [options]

Option	Description	Required	Default
`--url`	The URL of the Site.	Yes
`--location`	Choose the location for the test.	Yes
`--team`	The identifying slug of the Team.
`--schedule`	Set the schedule for automated Snapshots. Available options: hourly, daily, every_x_hours.		`every_x_hours`
`--interval`	Set the Snapshot interval. Provide UTC hour (between 0 and 23) for daily Snapshots and numeric hour interval for every_x_hours option (between 1 and 168 hours).		`6`
`--json`	Outputs the results of the command in JSON format.

calibre site list#

List all Sites you are tracking in Calibre.

calibre site list

Option	Description	Required	Default
`--json`	Outputs the results of the command in JSON format.

calibre site delete#

Delete a selected Site.

calibre site delete <slug> [options]

Option	Description	Required	Default
`--confirm`	Use this flag to confirm the deletion of the selected Site.
`--json`	Outputs the results of the command in JSON format.

calibre synthetic#

calibre synthetic pages#

List Pages for a selected Site.

calibre synthetic pages [options]

Option	Description	Required	Default
`--site`	A unique slug identifying each Site. You can find it in Site Settings → General or by using the calibre site list command.	Yes
`--count`	The number of items to return (default: 25, maximum: 500).		`25`
`--cursor`	The cursor to fetch records after
`--json`	Outputs the results of the command in JSON format.

calibre synthetic create-page#

Add a Page to an existing Site tracked by Calibre.

calibre synthetic create-page <name> [options]

Option	Description	Required
`--site`	A unique slug identifying each Site. You can find it in Site Settings → General or by using the calibre site list command.	Yes
`--url`	The URL of the Page.	Yes
`--json`	Outputs the results of the command in JSON format.

calibre synthetic update-page#

Update the name or URL of a Page.

calibre synthetic update-page [options]

Option	Description	Required
`--uuid`	The UUID of the Page.	Yes
`--name`	Update the name of the Page.
`--url`	Update the URL of the Page.
`--site`	A unique slug identifying each Site. You can find it in Site Settings → General or by using the calibre site list command.	Yes
`--json`	Outputs the results of the command in JSON format.

calibre synthetic delete-page#

Delete a Page from a selected Site.

calibre synthetic delete-page [options]

Option	Description	Required
`--site`	A unique slug identifying each Site. You can find it in Site Settings → General or by using the calibre site list command.	Yes
`--uuid`	The UUID of the Page.	Yes
`--confirm`	Use this flag to confirm the deletion of the selected Page.
`--json`	Outputs the results of the command in JSON format.

calibre synthetic snapshots#

List selected Snapshots for a Site.

calibre synthetic snapshots [options]

Option	Description	Required	Default
`--site`	A unique slug identifying each Site. You can find it in Site Settings → General or by using the calibre site list command.	Yes
`--count`	The number of items to return (default: 25, maximum: 500).		`25`
`--cursor`	The cursor to fetch records after
`--json`	Outputs the results of the command in JSON format.

calibre synthetic create-snapshot#

Create a Snapshot.

calibre synthetic create-snapshot [options]

Option	Description	Required
`--site`	A unique slug identifying each Site. You can find it in Site Settings → General or by using the calibre site list command.	Yes
`--ref`	Set a reference to the Snapshot.
`--json`	Outputs the results of the command in JSON format.

calibre synthetic delete-snapshot#

Delete a Snapshot from a selected Site.

calibre synthetic delete-snapshot [options]

Option	Description	Required
`--site`	A unique slug identifying each Site. You can find it in Site Settings → General or by using the calibre site list command.	Yes
`--id`	The id of the Snapshot.	Yes
`--confirm`	Use this flag to confirm the deletion of the selected Snapshot.
`--json`	Outputs the results of the command in JSON format.

calibre synthetic download-artifacts#

Download the artifacts of a Snapshot to ./snapshot-artifacts/<id>. Includes: lighthouse.json, render progress screenshots, render progress MP4 video, HAR file (request log) and all other metrics and data available through the Calibre interface.

calibre synthetic download-artifacts [options]

Option	Description	Required
`--site`	A unique slug identifying each Site. You can find it in Site Settings → General or by using the calibre site list command.	Yes
`--id`	The id of the Snapshot.	Yes
`--json`	Outputs the results of the command in JSON format.

calibre synthetic get-snapshot-metrics#

Get all metrics of a given Snapshot.

calibre synthetic get-snapshot-metrics [options]

Option	Description	Required
`--site`	A unique slug identifying each Site. You can find it in Site Settings → General or by using the calibre site list command.	Yes
`--snapshot`	The id of a Snapshot.	Yes
`--json`	Outputs the results of the command in JSON format.
`--csv`	Outputs the results of the command in CSV format.

calibre synthetic metrics#

Get time-series metrics for a selected Site.

calibre synthetic metrics [options]

Option	Description	Required
`--site`	A unique slug identifying each Site. You can find it in Site Settings → General or by using the calibre site list command.	Yes
`--pages`	A list of Page UUIDs to return metrics for. You can separate multiple Pages by a space or use multiple --pages flags.
`--profiles`	A list of Test Profile UUIDs to return metrics for. You can separate multiple Test Profiles by a space or use multiple --profiles flags.
`--metrics`	A list of metric UUIDs to return metrics for. You can separate multiple metrics by a space or use multiple --metrics flags.
`--json`	Outputs the results of the command in JSON format.
`--csv`	Outputs the results of the command in CSV format.
`--from`	The start date to retrieve data from in the Year-Month-Day format (default: 7 days ago).
`--to`	The end date to retrieve data from in the Year-Month-Day format (default: today).
`--30-day`	Get the last 30 days of metrics. Without this flag, CLI will use the to and from values.

calibre synthetic test-profiles#

List all Test Profiles for a Site.

calibre synthetic test-profiles [options]

Option	Description	Required	Default
`--site`	A unique slug identifying each Site. You can find it in Site Settings → General or by using the calibre site list command.	Yes
`--json`	Outputs the results of the command in JSON format.

calibre synthetic create-test-profile#

Add a Test Profile to a Site.

calibre synthetic create-test-profile <name> [options]

Option	Description	Required	Default
`--site`	A unique slug identifying each Site. You can find it in Site Settings → General or by using the calibre site list command.	Yes
`--device`	Choose the emulated test device.		`Desktop`
`--connection`	Choose the emulated network connection speed.
`--javascript`	Turn JavaScript execution on or off.		`true`
`--cookie-jar`	Set cookies by specifying a path to a Netscape formatted cookie jar file.
`--json`	Outputs the results of the command in JSON format.

calibre synthetic update-test-profile#

Update Test Profile settings. Only changes specified attributes.

calibre synthetic update-test-profile [options]

Option	Description	Required	Default
`--uuid`	The UUID of the Test Profile.	Yes
`--device`	Set the emulated device.
`--connection`	Set the emulated network connection speed.
`--site`	A unique slug identifying each Site. You can find it in Site Settings → General or by using the calibre site list command.	Yes
`--json`	Outputs the results of the command in JSON format.
`--javascript`	Turn JavaScript execution on or off		`true`
`--cookie-jar`	Set cookies by specifying a path to a Netscape formatted cookie jar file.

calibre synthetic delete-test-profile#

Delete a Test Profile from a Site.

calibre synthetic delete-test-profile [options]

Option	Description	Required
`--site`	A unique slug identifying each Site. You can find it in Site Settings → General or by using the calibre site list command.	Yes
`--uuid`	The UUID of the Test Profile.	Yes
`--confirm`	Use this flag to confirm the deletion of the selected Test Profile.
`--json`	Outputs the results of the command in JSON format.

calibre synthetic pull-request-reviews#

List Pull Request Reviews for a selected Site.

calibre synthetic pull-request-reviews [options]

Option	Description	Required	Default
`--site`	A unique slug identifying each Site. You can find it in Site Settings → General or by using the calibre site list command.	Yes
`--json`	Outputs the results of the command in JSON format.

calibre synthetic create-pull-request-review#

Create a Pull Request Review of a preview deployment.

calibre synthetic create-pull-request-review [options]

Option	Description	Required	Default
`--title`	e.g. "My Pull Request"	Yes
`--site`	A unique slug identifying each Site. You can find it in Site Settings → General or by using the calibre site list command.	Yes
`--url`	The base URL of the preview deployment (e.g.: https://my-pull-request-123.example.com).	Yes
`--branch`	The branch of the preview deployment. e.g.: "my-pull-request-123".	Yes
`--sha`	The source control revision of the deployed code. e.g.: 9c72279.	Yes
`--configPath`	Path to a Calibre YAML config file.
`--waitForResult`	Wait for pull request to be evaluated before returning.		`false`
`--failOnUnmetBudget`	Return a command failure if any existing budget is exceeded. (Requires --waitForResult to be set.)		`false`
`--json`	Outputs the results of the command in JSON format.
`--markdown`	Outputs the results of the command in Markdown format.

calibre synthetic pull-request-review#

See the results of a Pull Request Review.

calibre synthetic pull-request-review <branch>

Option	Description	Required
`--site`	A unique slug identifying each Site. You can find it in Site Settings → General or by using the calibre site list command.	Yes
`--json`	Outputs the results of the command in JSON format.
`--markdown`	Outputs the results of the command in Markdown format.

calibre synthetic connections#

List all available network connection speeds.

calibre synthetic connections

Option	Description	Required	Default
`--json`	Outputs the results of the command in JSON format.

calibre synthetic devices#

List all available test devices.

calibre synthetic devices

Option	Description	Required	Default
`--json`	Outputs the results of the command in JSON format.

calibre synthetic locations#

List all available test locations.

calibre synthetic locations

Option	Description	Required	Default
`--json`	Outputs the results of the command in JSON format.

calibre deploy#

calibre deploy list#

List all deployments for a Site.

calibre deploy list [options]

Option	Description	Required	Default
`--site`	A unique slug identifying each Site. You can find it in Site Settings → General or by using the calibre site list command.	Yes
`--count`	The number of items to return (default: 25, maximum: 500).		`25`
`--cursor`	The cursor to fetch records after
`--json`	Outputs the results of the command in JSON format.

calibre deploy create#

Create a deployment.

calibre deploy create [options]

Option	Description	Required
`--site`	A unique slug identifying each Site. You can find it in Site Settings → General or by using the calibre site list command.	Yes
`--revision`	The source control revision id of the code you are deploying. It could be a git hash or a tag name.
`--repository`	The base URL of the repository containing the source code being deployed (e.g. https://github.com/calibreapp/app).
`--username`	The username of who deployed the code.
`--json`	Outputs the results of the command in JSON format.

calibre deploy delete#

Delete a deploy from a selected Site.

calibre deploy delete [options]

Option	Description	Required
`--site`	A unique slug identifying each Site. You can find it in Site Settings → General or by using the calibre site list command.	Yes
`--uuid`	The UUID of the deploy.	Yes
`--confirm`	Use this flag to confirm the deletion of the selected deploy.
`--json`	Outputs the results of the command in JSON format.

calibre crux#

calibre crux summary#

Display Chrome UX Report (CrUX) origin-level performance data and Core Web Vitals assessment.

calibre crux summary [options]

Option	Description	Required
`--site`	A unique slug identifying each Site. You can find it in Site Settings → General or by using the calibre site list command.	Yes
`--json`	Outputs the results of the command in JSON format.
`--formFactor`	Filter by device type.

calibre crux history#

Display Chrome UX Report (CrUX) historical trends for a site.

calibre crux history [options]

Option	Description	Required	Default
`--site`	A unique slug identifying each Site. You can find it in Site Settings → General or by using the calibre site list command.	Yes
`--json`	Outputs the results of the command in JSON format.
`--formFactor`	Filter by device type.
`--timePeriod`	History time window.		`six-months`
`--limit`	Number of history entries to display per metric.		`25`

calibre crux urls#

List Chrome UX Report (CrUX) monitored URLs with their metrics and Core Web Vitals assessment.

calibre crux urls [options]

Option	Description	Required
`--site`	A unique slug identifying each Site. You can find it in Site Settings → General or by using the calibre site list command.	Yes
`--json`	Outputs the results of the command in JSON format.
`--formFactor`	Filter by device type.

calibre crux url#

Display Chrome UX Report (CrUX) data for a specific monitored URL.

calibre crux url <uuid> [options]

Option	Description	Required	Default
`--site`	A unique slug identifying each Site. You can find it in Site Settings → General or by using the calibre site list command.	Yes
`--json`	Outputs the results of the command in JSON format.
`--formFactor`	Filter by device type.
`--timePeriod`	History time window.		`six-months`
`--limit`	Number of history entries to display per metric.		`25`

calibre rum#

calibre rum summary#

Display Real User Metrics (RUM) dashboard — live visitors, aggregate web vitals, and UX ratings.

calibre rum summary [options]

Option	Description	Required	Default
`--site`	A unique slug identifying each Site. You can find it in Site Settings → General or by using the calibre site list command.	Yes
`--json`	Outputs the results of the command in JSON format.
`--duration`	Number of days to aggregate.		`7`
`--dateBin`	Time granularity.		`day`
`--country`	Filter by country code (e.g. AU).
`--device`	Filter by device type.
`--path`	Filter by URL path.
`--pageGrouping`	Filter by page grouping UUID.

calibre rum history#

Display Real User Metrics (RUM) historical trends.

calibre rum history [options]

Option	Description	Required	Default
`--site`	A unique slug identifying each Site. You can find it in Site Settings → General or by using the calibre site list command.	Yes
`--json`	Outputs the results of the command in JSON format.
`--duration`	Number of days to aggregate.		`7`
`--dateBin`	Time granularity.		`day`
`--country`	Filter by country code (e.g. AU).
`--device`	Filter by device type.
`--path`	Filter by URL path.
`--pageGrouping`	Filter by page grouping UUID.
`--limit`	Number of history entries to display.		`25`

calibre rum pages#

Display Real User Metrics (RUM) page-level breakdown.

calibre rum pages [options]

Option	Description	Required	Default
`--site`	A unique slug identifying each Site. You can find it in Site Settings → General or by using the calibre site list command.	Yes
`--json`	Outputs the results of the command in JSON format.
`--duration`	Number of days to aggregate.		`7`
`--dateBin`	Time granularity.		`day`
`--country`	Filter by country code (e.g. AU).
`--device`	Filter by device type.
`--path`	Filter by URL path.
`--pageGrouping`	Filter by page grouping UUID.
`--limit`	Number of pages to display.		`25`
`--offset`	Number of pages to skip.		`0`
`--sortBy`	Sort pages by field.		`sessionCount`

calibre rum config#

Display Real User Metrics (RUM) configuration for a site.

calibre rum config [options]

Option	Description	Required	Default
`--site`	A unique slug identifying each Site. You can find it in Site Settings → General or by using the calibre site list command.	Yes
`--json`	Outputs the results of the command in JSON format.

calibre test#

calibre test create#

Run a Single Page Test against any public URL.

calibre test create <url> [options]

Option	Description	Required	Default
`--device`	Choose the emulated test device.
`--location`	Choose the location for the test.	Yes
`--connection`	Choose the emulated network connection speed.
`--webhookUrl`	Test result JSON will be sent to this URL using HTTP POST.
`--webhookSecret`	Secret used to sign the webhook payload. Secret can be validated using `Calibre-HMAC-SHA256-Signature` HTTP header. See https://calibreapp.com/docs/integrations/webhooks#webhook-security-and-verification for more information.
`--private`	Make the results of a test private (only accessible by members of your Calibre organisation).		`false`
`--expiresAt`	Set a future UTC date time string (ISO8601). After this date, the test will be automatically deleted. (Min=24 hrs, Max=2 years) e.g.: 2025-12-31T23:59:59Z		Default: Expires 1 year from creation date.
`--cookie-jar`	Set cookies by specifying a path to a Netscape formatted cookie jar file.
`--headers`	Set HTTP headers by providing a path to a JSON file or a valid JSON key-value pairs.
`--blockedHosts`	Block hosts by providing a comma-separated list, a path to a JSON file, or a valid JSON array. Supports wildcards (e.g., "*.example.com").
`--json`	Outputs the results of the command in JSON format.
`--markdown`	Outputs the results of the command in Markdown format.
`--waitForTest`	Wait for the test to complete before showing the results (default: test result link is shown immediately).		`false`

calibre test download-artifacts#

Download the artifacts of a test to ./test-artifacts/<uuid>. Includes: lighthouse.json, render progress screenshots, render progress MP4 video, HAR file (request log) and all other metrics and data available through the Calibre interface.

calibre test download-artifacts <uuid>

Option	Description	Required	Default
`--json`	Outputs the results of the command in JSON format.

calibre test list#

List recent Single Page Tests (includes UUID, URL, device, connection, test location and status).

calibre test list

Option	Description	Required	Default
`--json`	Outputs the results of the command in JSON format.

calibre test show#

See the results of a Single Page Test (also as outputted by the test create command).

calibre test show <uuid>

Option	Description	Required	Default
`--json`	Outputs the results of the command in JSON format.
`--markdown`	Outputs the results of the command in Markdown format.

calibre team#

calibre team list#

List Teams based on API Token access. For Admin Tokens, this will list all teams or as specified based on your settings. For Personal Access Tokens, this will list Teams that you have access to.

calibre team list

Option	Description	Required	Default
`--json`	Outputs the results of the command in JSON format.

calibre token#

calibre token set#

Store your API Token to use the CLI (saved in ~/.config/configstore/calibre.json).

calibre token set <token>

calibre token remove#

Remove the saved API Token used for CLI commands (from ~/.config/configstore/calibre.json).

calibre token remove

Reference commands#

calibre request#

Use the request command to make a request to the Calibre GraphQL API.

calibre request

Option	Description	Required	Default
`--query`	Pass a GraphQL query to execute.	Yes
`--variables`	Pass query variables as named arguments. e.g.: `calibre request --query "$(cat query.gql)" --foo="example" --bar="example"`

calibre metric-list#

List available web performance metrics. Returns synthetic metrics by default.

calibre metric-list

Option	Description	Required	Default
`--json`	Outputs the results of the command in JSON format.
`--type`	Filter metrics by data source.

calibre connection-list#

calibre connection-list

Option	Description	Required	Default
`--json`	Outputs the results of the command in JSON format.

calibre device-list#

calibre device-list

Option	Description	Required	Default
`--json`	Outputs the results of the command in JSON format.

calibre location-list#

calibre location-list

Option	Description	Required	Default
`--json`	Outputs the results of the command in JSON format.