The sartar CLI

sartar is the command-line client of the sartar platform. It is a single binary with no dependencies. It does what the web dashboard does: list and edit monitors, run a scenario, read results, manage users and notification channels.

Install

On Linux and macOS:

curl -fsSL https://sartar.app/install.sh | sh

The installer detects your operating system and architecture, downloads the matching build, verifies its checksum, and installs sartar into ~/.local/bin. It tells you if that directory is not on your PATH.

Check the result:

sartar version

Installer options

The installer reads two environment variables.

Variable	Effect	Default
`SARTAR_VERSION`	install this version instead of the latest	latest release
`SARTAR_INSTALL_DIR`	install into this directory	`~/.local/bin`

curl -fsSL https://sartar.app/install.sh | SARTAR_INSTALL_DIR=/usr/local/bin sh

Supported platforms

System	Architectures	Archive
Linux	amd64, arm64	`.tar.gz`
macOS	amd64 (Intel), arm64 (Apple silicon)	`.tar.gz`
Windows	amd64, arm64	`.zip`

Manual download, and Windows

The installer script does not run on Windows. Download the archive by hand instead. This also works anywhere you would rather not pipe a script into a shell.

Read the latest version number at sartar.app/dl/sartar/latest.json.
Download the archive for your platform. The address has this shape:

https://sartar.app/dl/sartar/<version>/sartar_<version>_<os>_<arch>.tar.gz
https://sartar.app/dl/sartar/<version>/sartar_<version>_windows_<arch>.zip

Extract the sartar binary and put it in a directory of your PATH.

Verify a download

Every release publishes a checksum file and its signature next to the archives:

https://sartar.app/dl/sartar/<version>/sartar_<version>_SHA256SUMS
https://sartar.app/dl/sartar/<version>/sartar_<version>_SHA256SUMS.sig

The installer checks the archive against the checksum file. To also check where the release comes from, verify the signature of the checksum file with GPG. The signing key has this fingerprint:

598F C4D4 D2CB 22E0 A197  7BD3 FDC7 EE9C 5F90 3C58

Upgrade

Run the installer again. It replaces the binary with the latest release.

sartar version tells you whether your build and the platform still agree. See Versions and upgrades.

Configure

The CLI needs an API key. Create one in the web dashboard: account menu, API keys, Create key. See Before you start.

The simplest setup is a one-line file, ~/.sartar:

token = <your API key>

The file holds a credential, so keep it private. The CLI refuses to read it when other users of the machine can:

chmod 600 ~/.sartar

Then check that everything works:

sartar whoami

whoami shows the account the key belongs to, its role, and what it may do. The key itself is never printed.

Other ways to pass the key

Four sources are read. Each one overrides the one before it.

Source	Example
`~/.sartar`	`token = <key>`
a file you name	`sartar --config ./ci.sartar monitor list`
the environment	`SARTAR_TOKEN=<key> sartar monitor list`
a flag	`sartar --token <key> monitor list`

In a CI pipeline, use SARTAR_TOKEN and store the key as a secret of the pipeline.

Several accounts in one file

Optional [sections] hold one profile each. default names the profile used when the command line names none.

default = main

[main]
token = <key of the main account>

[sandbox]
token = <key of the sandbox account>

sartar monitor list                      # the "main" profile
sartar --profile sandbox monitor list    # or SARTAR_PROFILE=sandbox

How commands are built

sartar [global flags] <domain> <action> [flags]

Domain	What it manages
`whoami`	the account the key belongs to, its role and rights
`monitor`	HTTP monitors
`folder`	folders
`scenario`	multi-step scenarios
`user`	users of the account
`role`	named roles, the sets of permissions given to users and keys
`channel`	notification channels
`notify-list`	notification lists, which group several targets under one name
`settings`	the default settings of the account
`property`	the properties of the account
`region`	the regions checks can run from
`mailbox`	inbound e-mail addresses
`terraform`	adopting an existing account into Terraform
`version`	the version of the CLI, and whether the platform agrees

Built-in help

Help exists at three levels, and needs no API key.

sartar --help                  # the domains and the global flags
sartar monitor --help          # the actions of one domain
sartar monitor show --help     # one action and its own flags

Global flags

Flag	Meaning
`--config`, `-c`	configuration file, `~/.sartar` by default
`--profile`, `-p`	profile to read in the configuration file
`--token`, `-t`	API key
`--json`	print the raw JSON of the API instead of a table
`--quiet`, `-q`	print bare identifiers, for piping into another command
`--dry-run`	print what would be sent, and change nothing
`--help`, `-h`	help

Global flags are accepted anywhere on the line.

The CLI takes named flags only. An unknown flag or a stray word is an error, never a guess.

Naming an object

Every command that acts on one object accepts two forms.

--uuid <uuid> is exact.
--name <path> is the name of the object, with its folders in front.

sartar monitor show --name "api health"              # a monitor at the root
sartar monitor show --name "/prod/edge/api health"   # a monitor inside /prod/edge

Two monitors may share a name. When a name matches several objects, the CLI stops, lists the candidates with their uuid, and exits with code 3. Run the command again with --uuid.

A monitor whose own name contains a / cannot be reached by name. Use its uuid.

Monitors

Look

sartar monitor list
sartar monitor list --folder /prod --tree
sartar monitor show --name "/prod/api health"
sartar monitor status --name "/prod/api health"
sartar monitor results --name "/prod/api health" --since 24h
sartar monitor incidents --name "/prod/api health"

Create

sartar monitor create --name "/prod/api health" \
  --url https://api.example.com/health \
  --period 60 --region fr \
  --expect-status 200 \
  --header "Accept: application/json" \
  --notify-email ops@example.com

A monitor runs from exactly one region. --region is required unless the default settings of your account already name one. sartar region list shows the regions available to you.

Change

sartar monitor update --name "/prod/api health" --period 120
sartar monitor disable --name "/prod/api health"
sartar monitor move --name "/prod/api health" --folder /staging
sartar monitor run-now --name "/staging/api health"
sartar monitor delete --name "/staging/api health"

update changes only what you name. Every other value stays as it was.

To review a change before you send it, add --dry-run.

Edit a monitor as a file

show --json prints exactly what update --file accepts.

sartar monitor show --name "/prod/api health" --json > monitor.json
# edit monitor.json
sartar monitor update --name "/prod/api health" --file monitor.json

Flags given with --file override what the file says.

Inherited settings

Most settings of a monitor are inherited: from the defaults of the account, then from its folders, then from the monitor itself. The deepest value wins.

monitor show prints a SOURCE column that says where each value comes from. monitor show --overrides lists only what the monitor sets itself.

Scenarios

A scenario is a sequence of steps that run one after another.

sartar scenario list
sartar scenario show --name checkout
sartar scenario runs --name checkout --since 24h

Run a scenario from a pipeline

scenario run --wait starts a run, follows it step by step, and exits with a non-zero code when the run fails. This is what makes it usable as a gate.

sartar scenario run --name checkout --wait --timeout 5m

started checkout (run c1cf2436-7338-4b13-aa73-b192dfbde8d6)
checkout — run c1cf2436-7338-4b13-aa73-b192dfbde8d6, 5 step(s)
  1/5  login (1s)
  2/5  wait 30s (31s)
  3/5  listing monitors (1s)
  4/5  wait 1–10s (7s)
  5/5  wait 1s (1s)
status    success
steps     5/5
run time  41s

Exit code	Meaning
0	the run succeeded
6	the run finished in error: the monitored system failed, not the CLI
7	`--timeout` was reached while the run continued

After a timeout, follow the same run with its instance uuid:

sartar scenario status --instance <uuid> --wait

Alerts

Send the alerts of a monitor, a folder or a scenario to an e-mail address, a notification channel, or a notification list.

sartar monitor  update --name "/prod/api health" --notify-email ops@example.com
sartar folder   update --name /prod              --notify-channel "ops-alerts"
sartar scenario update --name checkout           --notify-list on-call

An alert target set on a folder applies to everything inside it, unless a monitor or a scenario sets its own.

A notification list groups several targets under one name:

sartar notify-list create --name on-call \
  --channel ops-alerts --email ops@example.com

Scripting

--json prints the response of the API unchanged. Parse that, not the tables.
--quiet prints bare identifiers, one per line.
Branch on the exit code, never on the text of a message.

Exit codes

Code	Meaning	What to do
0	success
1	wrong usage, or an error with no more specific code	read the message
2	object not found	check the name or the uuid
3	the name matches several objects	run again with `--uuid`
4	no key, or the key is invalid or expired	fix the credentials
5	the key is not allowed to do this	use a key with more rights
6	a scenario run finished in error	fix the monitored system
7	`--wait` gave up while the run continued	raise `--timeout`
8	the platform cannot be reached	safe to retry
9	the CLI is too old, or too new, for the platform	upgrade the CLI

Code 8 is the only one worth retrying without a change.

Versions and upgrades

sartar version

sartar 2.4.0
api contract  2.1
site          https://sartar.app/api
server        2.1.0 (deployed 2026-09-28T16:23:11Z)
compatible    yes

Two numbers appear. The first is the release of the CLI. The second, the API contract, is the version of the interface the CLI was built for.

The platform serves any CLI whose contract has the same first number as its own. When that number differs, every command stops with exit code 9 and a message that names both sides. Upgrade the CLI by running the installer again.

In a pipeline, sartar version --check exits with a non-zero code when the CLI and the platform no longer agree. It needs no API key.

What the CLI cannot do

Manage API keys. Keys are created, revoked and extended in the web dashboard only. A key that could create other keys, or extend itself, would defeat the point of limiting it.
Test a monitor before saving it. The test dialog exists in the web dashboard only.