npm package: @omnicron/cli
Description: The official CLI for using omnicron, a cloud-based cron job monitoring service
Author: Brendon Hablutzel
Latest version: 0.2.6

# @omnicron/cli

The official CLI for using `omnicron`, a cloud-based cron job monitoring service.

## Installation

Ensure you have npm and node installed, then run `npm install @omnicron/cli`. You should then be able to use the CLI as `omnicron-cli`.

## Usage

Omnicron deals with three primary object types: devices, jobs, and invocations:

- A **device** is a single machine that has been registered with the backend and can run cron jobs. Each device has a unique ID and a private token used for authentication.
- A device can have many **jobs**, and each job represents a cron job--one line of the device's crontab file.
- Each job can have many **invocations**, where an invocation represents the job having been run.

NOTE: you should not edit the monitored commands in the local crontab file manually, this is likely to cause bugs. Use Omnicron CLI commands instead.

NOTE: in order for this CLI to work properly, there should be nothing in the local crontab file except valid cron jobs. Commented out jobs are allowed, but arbitrary comment text is not (e.g. `# * * * * * command` is valid but `# some command below` is not).

### Device Commands

#### `omnicron-cli device register`

This is the first command you should run. You will be prompted to enter an auth token and a url for the monitoring API endpoint. Upon successful registration, the backend will generate and return a device ID, and this will be stored in `.omnicron/config` with your auth token and the monitoring API url. It will also load a cron wrapper script (used when running monitored jobs) to `.omnicron/cron_wrapper.sh`

#### `omnicron-cli device info`

This will print the current device's configuration.

#### `omnicron-cli device unregister`

This removes the config file from your home directory, removes all monitored cron jobs from the user crontab file, and removes all device metadata and jobs associated with the current device from the backend.

### Jobs Commands

#### `omnicron-cli jobs delete <job-id>`

This will delete a job, removing its entry from the local crontab file and removing its corresponding record from the remote server.

#### `omnicron-cli jobs disable <job-id>`

This will disable a job: disabling a job involves commenting its entry on the local crontab and marking the job as disabled on the remote server.

#### `omnicron-cli jobs enable <job-id>`

This will enable a job: enabling a job involves uncommenting its entry on the local crontab and marking the job as enabled on the remote server.

#### `omnicron-cli jobs get <job-id>`

This takes a job ID and fetches information from the backend about that job, if it exists. This includes data about recent invocations--use the CLI's help commands to see available options for filtering and displaying invocation.

#### `omnicron-cli jobs list`

This will parse the local crontab file and get information about all jobs from the remote server, displaying what was found.

#### `omnicron-cli jobs load ...`

This is the primary command for creating a new monitored job. You can choose from one of several ways below to do this:

##### `--from-string <job-string>`

This will take a cron job (in the format of a single line of a crontab file, ex. `* * * * * command`), load the job onto the current device, and create a job entry on the backend. As part of loading the job onto the machine, it will configure the cron job to send logging data to the backend, so the job entry in the user crontab file should not be modifed.

##### `--from-remote <job-id>`

This will attempt to retrieve a record from the remote server corresponding to the given job id, then load that job onto the local crontab file.

##### `--from-local`

This will open an interactive prompt that iterates through all unmonitored jobs on the current device's crontab file, offering the option to register each as a monitored job.

#### `omnicron-cli jobs run`

This command should not be run directly. Monitored jobs will be run via this command, and it will send data to the logging endpoint.

#### `omnicron-cli jobs sync`

This will parse the local crontab file and get information about all jobs from the remote server, then ensure that for each job, the local and remote entries match.