Metadata-Version: 2.4
Name: flatline-cli
Version: 0.1.0
Summary: Command line tool for FlatLine: monitors as code and a job wrapper
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: boto3>=1.40
Requires-Dist: croniter>=6.2.4
Provides-Extra: cli
Requires-Dist: pyyaml>=6; extra == "cli"
Provides-Extra: dev
Requires-Dist: pyyaml>=6; extra == "dev"
Requires-Dist: types-PyYAML; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: moto[dynamodb]>=5.1; extra == "dev"
Requires-Dist: fastapi>=0.115; extra == "dev"
Requires-Dist: uvicorn>=0.30; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.11; extra == "dev"
Requires-Dist: types-croniter; extra == "dev"

# flatline-cli

The command line tool for [FlatLine](https://flatline.example), heartbeat monitoring for scheduled jobs.

FlatLine tells you when a scheduled job stops running. Your job visits a web address (the "ping URL") when it runs. If FlatLine does not hear from it on time, you get an alert.

This tool does two things:

- **Monitors as code.** Keep your monitors in a file in your repo. Export them, check what would change, and apply them.
- **Wrap a job.** Run any command and report its start, result and output to FlatLine.

You do not need this tool to use FlatLine. `curl` is enough to send a ping. The CLI is optional.

## Install

You need Python 3.12 or newer.

```bash
pip install "flatline-cli[cli]"
```

Or with pipx, which keeps it out of your other Python projects:

```bash
pipx install "flatline-cli[cli]"
```

The command is called `flatline`:

```bash
flatline --help
```

## Set up

Make an API key in the FlatLine dashboard, under Settings, then API keys. A read key can only look. A write key can also change things. The full key is shown once, so copy it then.

```bash
export FLATLINE_API_URL=<your FlatLine API address>
export FLATLINE_API_KEY=flk_...
```

You can also pass `--api-url` and `--api-key` on the command line.

## Monitors as code

Save your current monitors to a file:

```bash
flatline export > monitors.yaml
```

See what would change, without changing anything:

```bash
flatline apply -f monitors.yaml --dry-run
```

Make the changes:

```bash
flatline apply -f monitors.yaml
```

Add `--prune` to also delete monitors that are not in the file.

Use `--detailed-exitcode` with `--dry-run` to catch drift in CI. It exits with code 2 when something would change.

```bash
flatline apply -f monitors.yaml --dry-run --detailed-exitcode
```

An example `monitors.yaml`:

```yaml
monitors:
  - name: nightly backup
    schedule: {cron: "0 2 * * *", timezone: Europe/London}
    grace_seconds: 10m
    max_duration_seconds: 1h
    channels: [on-call]
  - name: hourly sync
    schedule: {interval: 1h}
```

Durations can be written as `300`, `5m`, `2h` or `1d`. List channels by name or by id.

## Wrap a job

`flatline run` sends the start ping, runs your command, then sends its exit code and the last 10 KB of its output. It never breaks your job if FlatLine cannot be reached.

```bash
flatline run --url https://<your ping URL> -- ./job.sh
```

You can set the URL once with `FLATLINE_PING_URL` instead of `--url`. Use `--tail-bytes` to change how much output is sent. Use `0` to send none.

## Other commands

| Command | What it does |
| --- | --- |
| `flatline monitors` | List your monitors and their state |
| `flatline channels` | List your alert channels |
| `flatline pause <name>` | Pause a monitor |
| `flatline resume <name>` | Resume a monitor |

`monitors` and `channels` take `--json` for machine-readable output.

## Keep your keys safe

- An API key works like a password. Do not commit it to a repository.
- A ping URL also works like a password. Anyone with it can mark your job as healthy. If it leaks, rotate it in the dashboard.
