---
title: Using Cronitor CLI
description: The CronitorCLI is the fastest way to add monitoring to all your cron jobs.
---

CronitorCLI is our cross-platform, open source companion application. Run it on your workstation and deploy it to your server for powerful features, including: {% .lead %}

**Import and sync all of your cron jobs**
Complete your integration in minutes with `cronitor sync` and sync schedule changes to Cronitor automatically.

**Manage your cron jobs from a web-based control panel**
Run `cronitor dash` to start the bundled [Crontab Guru Dashboard](#crontab-guru-dashboard), with one-click "run now", job suspension, a local test console, and a built-in [MCP server](#mcp-server-ai-integration) for AI tools.

**Easier integration with Cronitor**
Run and monitor any command with `exec` and use `ping` to send telemetry pings more reliably than curl.

**Manage your account from the terminal**
Create and update monitors, status pages, issues, notification lists, and more. Connect Slack, PagerDuty, and other alert destinations with `cronitor connect`.

**Power tools for your cron jobs**
Use `list` to view every cron job on your system. Use `shell` to test running a command like cron does.

## Installation

### Install by Script (recommended)

CronitorCLI is packaged as a single executable for Linux, MacOS and Windows. This installation script selects the right binary for your operating system and platform. Installation does not require an API key; authenticate separately after inspecting the installed command. [View Source](https://cronitor.io/install-linux?sudo=1&pretty=1)

You can re-run this script at any time to install the latest version of CronitorCLI.
[![Latest Release](https://img.shields.io/github/v/release/cronitorio/cronitor-cli?style=flat&color=brightgreen)](https://github.com/cronitorio/cronitor-cli/releases)
```bash
curl -fsSL 'https://cronitor.io/install-linux?sudo=1' | sh
cronitor help
```

Do not run `cronitor sync` until you have reviewed the jobs it will discover and approved the resulting Cronitor resources and crontab changes.

### Manual Installation

Download and install a prebuilt executable for your platform, or compile CronitorCLI directly from source.

#### Linux (amd64)

**Choosing an installation location**
The easiest way to integrate and use CronitorCLI is to install the binary system-wide in `/usr/bin`. If you choose an alternate install location (e.g. your home directory) you will need to remember and use its full path when running commands.

**Downloading and installing**
Paste each instruction into a terminal and execute. Because `/usr/bin` is a privileged directory you will require sudo or root access for that step. By default the CronitorCLI config file is stored in `/etc/cronitor` and you will also need sudo access to create and write this file.

```bash
curl -sOL https://cronitor.io/dl/linux_amd64.tar.gz
sudo tar xvf linux_amd64.tar.gz -C /usr/bin/
```

**Testing your installation**
To verify your installation, run `cronitor help` from your terminal.

#### MacOS (amd64)

**Choosing an installation location**
The easiest way to integrate and use CronitorCLI is to install the binary system-wide in `/usr/bin`. If you choose an alternate install location (e.g. your home directory) you will need to remember and use its full path when running commands.

**Downloading and installing**
Paste each instruction into a terminal and execute. Because `/usr/bin` is a privileged directory you will require sudo or root access for that step. By default the CronitorCLI config file is stored in `/etc/cronitor` and you will also need sudo access to create and write this file.

```bash
curl -sOL https://cronitor.io/dl/darwin_amd64.tar.gz
sudo tar xvf darwin_amd64.tar.gz -C /usr/local/
```

**Testing your installation**
To verify your installation, run `cronitor help` from your terminal.

#### Windows

1. Download application: [https://cronitor.io/dl/windows_amd64.zip](https://cronitor.io/dl/windows_amd64.zip)
2. Unzip and move the executable to `%ProgramFiles%\` for system-wide use
3. Run `%ProgramFiles%\cronitor.exe help` from PowerShell or cmd.

**Testing your installation**
To verify your installation, run `%ProgramFiles%\cronitor.exe` from powershell. A usage block will be printed to your screen.

#### More Options

**Download an executable**
CronitorCLI builds for multiple platforms and operating systems can be found on our Github Release page:
[https://github.com/cronitorio/cronitor-cli/releases](https://github.com/cronitorio/cronitor-cli/releases)

**Verify a build**
MD5 and SHA256 hashes for every build are available on our Github Release page:
[https://github.com/cronitorio/cronitor-cli/releases](https://github.com/cronitorio/cronitor-cli/releases)

**Installing from source**
[View on Github](https://github.com/cronitorio/cronitor-cli)

After installation, inspect `cronitor help` before authenticating or changing cron jobs.

## Authentication

Provide `CRONITOR_API_KEY` through an approved secret injector. Never put a literal key in `--api-key`, a copied command, source control, shell history, logs, tickets, or screenshots.

Your API key authorizes resource management; it is not a production workload credential. Give deployed jobs a telemetry-only `CRONITOR_PING_API_KEY` or another documented runtime credential through their secret manager. There is no `cronitor auth login`. Integration writes use `integration:write` (included on SDK Integration keys). See the [Integrations API](/docs/integrations-api).

## Usage

### Command Reference

```bash
cronitor help
cronitor <command> --help
```

Use the installed command's help as the command reference; it stays aligned with that binary's version and available resource commands.

### Cron management

| Command | Description |
| --- | --- |
| `cronitor sync [path]` | Add monitoring to new cron jobs and sync schedule changes to existing jobs |
| `cronitor exec <key> <cmd>` | Run a command with monitoring |
| `cronitor ping <key>` | Send a telemetry event (`--run`, `--complete`, `--fail`, `--ok`, `--tick`) |
| `cronitor list [path]` | List all cron jobs found on this system, or in a crontab file or directory |
| `cronitor status [key]` | View monitor status for your account or a single monitor |
| `cronitor shell` | Run commands from a cron-like shell to reproduce cron's environment |
| `cronitor dash` | Start the [web dashboard](#crontab-guru-dashboard) |
| `cronitor configure` | Save configuration variables to the config file |
| `cronitor update` | Update CronitorCLI to the latest version |

### Account resource commands

CronitorCLI manages the same account resources exposed by Cronitor's API. The installed command's `--help` output is authoritative for its version.

| Resource | Command | Common operations |
| --- | --- | --- |
| Monitors | `cronitor monitor` | `list`, `search`, `get`, `export`, `create`, `update`, `delete`, `clone`, `pause`, `unpause` |
| Status pages | `cronitor statuspage` | `list`, `get`, `create`, `update`, `delete`; manage components with `statuspage component` |
| Issues | `cronitor issue` | `list`, `get`, `create`, `update`, `resolve`, `delete`, `bulk` |
| Notification lists | `cronitor notification` | `list`, `get`, `create`, `update`, `delete` |
| Integrations | `cronitor integration` | `list`, `get`, `services`, `create`, `delete`; connect interactively with [`cronitor connect`](#integrations) |
| Groups | `cronitor group` | `list`, `get`, `create`, `update`, `delete`, `pause`, `resume` |
| Environments | `cronitor environment` | `list`, `get`, `create`, `update`, `delete` |
| Maintenance windows | `cronitor maintenance` | `list`, `get`, `create`, `update`, `delete` |
| Metrics | `cronitor metric` | `get`, `aggregate` |
| RUM sites | `cronitor site` | `list`, `get`, `create`, `update`, `delete`, `query`; list and inspect JavaScript errors with `site error` |

Representative examples:

```bash
cronitor monitor list --type job --state failing
cronitor monitor list --tag critical --env production
cronitor monitor export -o monitors.yaml
cronitor monitor get billing-rollup --with-events
cronitor monitor create --file monitors.yaml
cronitor monitor update billing-rollup --data '{"name":"Billing rollup"}'
cronitor monitor pause billing-rollup --hours 24
cronitor monitor delete key1 key2 key3
cronitor statuspage get company-status --with-components
cronitor statuspage component list --statuspage company-status
cronitor issue list --state unresolved --severity outage
cronitor issue update ISSUE_KEY --data '{"state":"investigating"}'
cronitor issue resolve ISSUE_KEY
cronitor notification list
cronitor group list --with-status
cronitor group pause production-jobs 24
cronitor environment list
cronitor maintenance list --upcoming
cronitor metric aggregate --monitor billing-rollup --time 30d
cronitor site error list --site web-app
```

**Aliases:** `cronitor env` for `environment`, `cronitor notifications` for `notification`, `cronitor integrations` for `integration`, `cronitor maint` for `maintenance`, `cronitor metrics` for `metric`.

Before sending a payload, read `cronitor <resource> <operation> --help` and the linked raw API documentation. The [CronitorCLI README](https://github.com/cronitorio/cronitor-cli#api-resources) contains additional examples for every resource.

### Common flags

| Flag | Description |
| --- | --- |
| `--format <json,table,yaml>` | Output format. Defaults to `table` for list commands and `json` for get commands. YAML is supported where noted in `--help`. |
| `-o, --output <file>` | Write output to a file |
| `--page <n>` | Page number for paginated results |
| `-d, --data <json>` | JSON payload for create and update commands |
| `-f, --file <path>` | Read a JSON or YAML payload from a file |
| `-k, --api-key <key>` | Cronitor API key. Appears in shell history and process lists; prefer `CRONITOR_API_KEY`. |

### Integrations

Integrations are the Slack workspaces, PagerDuty services, webhooks, and other destinations that Cronitor sends alerts to. `cronitor connect` adds one interactively; `cronitor integration` lists, inspects, creates, and deletes them.

```bash
cronitor connect                                      # List available services
cronitor connect slack                                # OAuth: print URL, open browser, wait
cronitor connect slack --no-browser                   # Print authorize URL only
cronitor connect pagerduty --timeout 10m --add-to default
cronitor connect opsgenie --name "On-call" --field key=SECRET
cronitor connect telegram                             # Print bot instructions; wait for a new label
cronitor connect telegram --name "On-call bot"        # Wait for a new label that matches
```

`cronitor connect` behaves differently depending on the service:

- **OAuth services** (`slack`, `pagerduty`): starts a connect session, prints the authorize URL, opens a browser unless `--no-browser` is set, then polls until the integration is complete. `--timeout` (default `15m`) bounds the wait.
- **API-key services** (`discord`, `microsoft-teams`, `gchat`, `larksuite`, `opsgenie`, `victorops`, `datadog-on-call`, `webhook`): prompts for each field unless it is supplied with `--field key=value`, then creates the integration. Secret values are not echoed. Omit `--field` to be prompted; values passed with `--field` are visible in shell history.
- **Telegram**: prints bot instructions and waits for a new Telegram integration to appear on the account. If `--name` is set, the new integration's label must match it.

Pass `--add-to <notification list key>` to append the new integration to a notification list once it is connected. Service names are the catalogue keys shown by `cronitor connect` and `cronitor integration services`; friendly aliases are not accepted.

```bash
cronitor integration list
cronitor integration list --service slack
cronitor integration get Workspace
cronitor integration get Alerts --service slack
cronitor integration services
cronitor integration create --service discord --name "Alerts" --field key=https://example.com/webhook
cronitor integration create -d '{"service":"webhook","name":"Hook","fields":{"key":"https://example.com"}}'
cronitor integration delete Alerts
cronitor integration delete Alerts --force
```

Integrations are addressed by their unique label; add `--service` when the same label exists for more than one service. Field names come from `cronitor integration services`. Most API-key services take a single `key` (the webhook URL or API key). Integrations can also be managed from [Settings → Integrations](/app/settings/integrations) or the [Integrations API](/docs/integrations-api).

## Crontab Guru Dashboard

CronitorCLI bundles the [Crontab Guru Dashboard](https://crontab.guru/dashboard.html), a self-hosted web UI to manage your cron jobs. It includes one-click "run now" and "suspend" actions, a local console for testing jobs, and a built-in [MCP server](#mcp-server-ai-integration) for configuring jobs and checking the health of existing ones.

**Start locally**

```bash
cronitor dash
# then visit http://localhost:9000
```

Use `--port` to change the port and `--safe-mode` to limit the ability to edit jobs, crontabs, and settings.

**Secure access**

The dashboard is intended for local or secured access. A simple, safe pattern for remote use is an SSH tunnel:

```bash
ssh -L 9000:localhost:9000 user@your-server
# now open http://localhost:9000
```

**Access control and options**

```bash
# Set login credentials via environment variables (preferred).
# --dash-username / --dash-password work but appear in shell history and process lists.
export CRONITOR_DASH_USER=USER
export CRONITOR_DASH_PASS=PASS
cronitor configure

# Optionally, restrict which system users' crontabs are loaded
cronitor configure --users user1,user2

# Optionally, restrict access to a list of IP addresses or CIDR ranges
cronitor configure --allowed-ips 192.168.1.0/24,10.0.0.1
```

For systemd and Docker examples, and security best practices, see the full [Dashboard documentation](https://crontab.guru/dashboard.html).

## MCP Server (AI integration)

CronitorCLI includes a built-in [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for managing cron jobs with natural language through AI-powered tools like Claude Code, Cursor, Cline, and Windsurf.

CronitorCLI's local MCP server can inspect and edit crontabs on the machine where the CLI runs. To manage Cronitor resources remotely, connect to the [Cronitor MCP server](/docs/mcp-server). The local and hosted servers can be used together.

The MCP server is a bridge that your AI tool spawns locally. It talks to the tool over stdio and connects to a running dashboard over HTTP, so `cronitor dash` must be running on the server where your cron jobs live.

**Quick start:** run `cronitor dash` on your server, then configure your MCP client to spawn `cronitor dash --mcp-instance default`.

```json
{
  "mcpServers": {
    "cronitor": {
      "command": "cronitor",
      "args": ["dash", "--mcp-instance", "default"]
    }
  }
}
```

The `default` instance connects to `localhost:9000` using the dashboard credentials from your Cronitor config file. Additional named instances for other hosts are configured in the same file. For setup instructions, available tools, and configuration options, see the [MCP Integration Guide](https://github.com/cronitorio/cronitor-cli/blob/master/docs/MCP_INTEGRATION.md).

## Safe use

### Wrap an executable without uploading its output

`cronitor exec` sends the wrapped command's stdout and stderr to Cronitor by default. It also includes the command string with run telemetry. Begin with output collection disabled:

```bash
cronitor exec --no-stdout monitor-key path/to/executable arg1 arg2
```

CLI flags such as `--no-stdout` must appear before the monitor key. Inspect the executable's arguments for passwords, tokens, connection strings, or customer data; move sensitive values to the workload's normal secret injector. Remove `--no-stdout` only after deciding that the output is appropriate to retain in Cronitor.

Put the wrapper in the real crontab, scheduler, service, or deployment command and preserve the executable's exit status. A test invocation from a setup shell does not prove that the production scheduler is monitored.

### Limit agent-visible output

Start account inspection with the CLI's default table or summary output. JSON/YAML exports and event expansions may contain request headers, bodies, event messages, or captured output. Request and locally filter those fields only when needed; do not paste raw exports into an agent conversation.

Keep verbose and file logging disabled during credential setup and telemetry debugging unless the destination and contents have been reviewed. Logs can include telemetry URLs or other sensitive request details.

Treat `sync`, `connect`, create, update, delete, and crontab-editing commands as writes. Inspect their help and proposed scope, reconcile stable monitor keys, and obtain approval before running them.

### On Your Server

If you're using Cronitor to monitor traditional cron jobs, `cronitor sync` is the easiest way to create monitors and keep their schedule in sync with your server. If you're monitoring Windows scheduled tasks, scripts, daemons, ETL processes or almost anything else, using CronitorCLI for `cronitor exec` and `cronitor ping` will send telemetry pings more reliably than simply using Curl.

- Required configuration can be provided as environment variables or from a json file. See Configuration section for details.
- Update easily to the latest version with a simple `cronitor update` command.
- Install CronitorCLI in a system-wide location to more easily monitor tasks running as different users.
- Run `cronitor dash` to manage the server's crontabs from a browser or an AI tool.

### On Your Local Machine

Running CronitorCLI on your local machine enables quick commandline access to your Cronitor account.

- Use `cronitor status` to view the status of every monitor from your terminal, or `cronitor status <key>` for a single monitor.
- Use the [account resource commands](#account-resource-commands) to inspect and change monitors, issues, status pages, and other resources.
- Like server deployment, update easily to the latest version with a simple `cronitor update` command.

## Configuration

Configuration variables like api key and current server hostname can be provided as runtime arguments or environment variables. Alternatively, the `configure` command can be used to save configuration variables to a file.

Prefer environment variables supplied by a secret manager over literal arguments. Configure management and telemetry credentials separately; some CLI versions fall back to the management API key for telemetry when `CRONITOR_PING_API_KEY` is absent.

| Name | Argument | Variable name |
|------|----------|---------------|
| Monitor API Key | `-k, --api-key [key]` | `CRONITOR_API_KEY` |
| Telemetry Events API Key | `-p, --ping-api-key [key]` | `CRONITOR_PING_API_KEY` |
| Current server name | `-n, --hostname [name]` | `CRONITOR_HOSTNAME` |
| Log Cronitor activity | `-l, --log [path]` | `CRONITOR_LOG` |
| Verbose output | `-v, --verbose` | |
| Users whose crontabs to include | `-u, --users [user1,user2]` | `CRONITOR_USERS` |
| Exclude from name | `-e, --exclude-from-name [substring]` (`configure` only) | `CRONITOR_EXCLUDE_TEXT` |
| Config file to use | `-c, --config [path to file]` | `CRONITOR_CONFIG` |
| Environment to send telemetry events to | `--env` | `CRONITOR_ENV` |
| Cronitor API version | `--api-version [date]` | `CRONITOR_API_VERSION` |
| Dashboard username | `--dash-username` (`configure` only) | `CRONITOR_DASH_USER` |
| Dashboard password | `--dash-password` (`configure` only) | `CRONITOR_DASH_PASS` |
| Dashboard allowed IPs | `--allowed-ips` (`configure` only) | `CRONITOR_ALLOWED_IPS` |
| Disable sending job output logs to Cronitor | `--no-stdout` (`exec` only) | |

### Default Config File Locations

| Platform | Default config file location |
|----------|------------------------------|
| Linux | `/etc/cronitor/cronitor.json` |
| MacOS | `/etc/cronitor/cronitor.json` |
| Windows | `%SystemDrive%\ProgramData\Cronitor\cronitor.json` |

### Configuration and secrets

Do not put API keys, ping keys, or dashboard passwords on the command line. Those flags (`--api-key`, `--ping-api-key`, `--dash-password`) remain for compatibility but appear in shell history and process lists. Set credentials in the environment instead:

```bash
export CRONITOR_API_KEY
export CRONITOR_PING_API_KEY
cronitor configure
```

`cronitor configure` prints `API Key: Set` / `Ping API Key: Set` (or `Not Set`). It never prints complete keys. Dashboard passwords are shown as `********`.

New config files are created **owner-only** (`0600` on Unix; an owner-restricted ACL on Windows), and `configure` prints a note saying so the first time. An existing file keeps its current permissions when saved, so upgrading never changes which users can read it. `exec` and `ping` read the file exactly as before.

If an existing file is readable by other users, `configure` prints a note after saving. To make it owner-only:

```bash
cronitor configure --restrict
```

Jobs that run as another user then need credentials from somewhere else:

1. **Preferred:** set `CRONITOR_API_KEY` / `CRONITOR_PING_API_KEY` in the crontab or service environment. On Windows, set them on the scheduled task or Windows service.
2. **Per-user file:** a user-owned `0600` file via `--config` / `CRONITOR_CONFIG`.

If the config file exists but cannot be read, the CLI prints one warning to stderr naming the path instead of running unconfigured.

On Windows, new files get an owner-restricted ACL (Administrators and SYSTEM keep access, a platform limitation). Existing files keep their ACL unless `--restrict` is passed.

## Uninstall

First, you will need to update any crontab files that were edited to include Cronitor to remove the reference to `cronitor exec MONITOR_KEY` that were added when you created monitors.

Then, remove the cronitor executable from wherever it was installed. If you followed our default instructions it can be removed with `rm /usr/bin/cronitor`