# Working from the CLI ## Overview The [tuna](https://tuna.am/en/docs/guides/install/install-cli.md) console client lets you interact with [Job](https://tuna.am/en/docs/monitors/types/job.md) and [Heartbeat](https://tuna.am/en/docs/monitors/types/heartbeat.md) monitors directly from the terminal or scripts. Main commands: * `tuna monitor ping` — send a Heartbeat signal to a monitor * `tuna monitor exec` — run a command and track it as a Job monitor * `tuna monitor status` — view monitor statuses *** ## Authorization To view a monitor's status you need an [API key](https://tuna.am/en/docs/guides/api.md). It can be passed in several ways: **Environment variable** ```bash export TUNA_API_KEY=your-api-key tuna monitor ping YOUR_MONITOR_ID ``` **Flag** ```bash tuna monitor ping YOUR_MONITOR_ID --api-key=your-api-key ``` **Config file** ```bash # Save the key to the config tuna config save-api-key your-api-key # Now you can use it without explicitly passing the key tuna monitor ping YOUR_MONITOR_KEY ``` *** ## monitor ping Sends a signal to a Heartbeat monitor. ### Syntax ```bash tuna monitor ping MONITOR_ID [flags] ``` ### Parameters | Parameter | Description | Default | | ------------ | ---------------------------------------- | -------- | | `MONITOR_ID` | Monitor key (required) | — | | `--state` | State: `ping`, `start`, `finish`, `fail` | `ping` | | `--message` | Additional message | — | | `--host` | Sender host name | hostname | ### Examples #### Simple ping ```bash tuna monitor ping MONITOR_ID ``` #### With explicit host ```bash tuna monitor ping MONITOR_ID --host=server-01 ``` #### With a message ```bash tuna monitor ping MONITOR_ID --message="All systems operational" ``` #### Different states ```bash # Start of work tuna monitor ping MONITOR_ID --state=start # Successful completion tuna monitor ping MONITOR_ID --state=finish # Error tuna monitor ping MONITOR_ID --state=fail ``` ### Using in crontab ```bash # Heartbeat every 5 minutes */5 * * * * /usr/local/bin/tuna monitor ping MONITOR_ID --host=gitlab-runner ``` ### Using in systemd ```ini # /etc/systemd/system/heartbeat.service [Unit] Description=Send heartbeat to Tuna [Service] Type=oneshot ExecStart=/usr/local/bin/tuna monitor ping MONITOR_ID ``` ```ini # /etc/systemd/system/heartbeat.timer [Unit] Description=Heartbeat timer [Timer] OnBootSec=1min OnUnitActiveSec=5min [Install] WantedBy=timers.target ``` *** ## monitor exec Runs a command and automatically tracks a Job monitor. On start it sends the `start` signal, on successful completion `finish`, and on error `fail`. ### Syntax ```bash tuna monitor exec MONITOR_ID [flags] -- COMMAND [ARGS...] ``` ### Parameters | Parameter | Description | Default | | ------------- | -------------------------------- | -------- | | `MONITOR_ID` | Monitor key (required) | — | | `--host` | Execution host name | hostname | | `--no-stdout` | Do not send output to the server | false | ### Examples #### Simple run ```bash tuna monitor exec MONITOR_ID -- ./backup.sh ``` #### With explicit host ```bash tuna monitor exec MONITOR_ID --host=backup-server -- ./backup.sh ``` #### Without sending logs ```bash tuna monitor exec MONITOR_ID --no-stdout -- ./backup.sh ``` #### Command with arguments ```bash tuna monitor exec MONITOR_ID -- pg_dump -U postgres -d mydb -f /backups/dump.sql ``` #### Command with a pipe ```bash tuna monitor exec MONITOR_ID -- bash -c 'pg_dump mydb | gzip > /backups/dump.sql.gz' ``` ### Using in crontab ```bash # Backup every night at 3:00 0 3 * * * /usr/local/bin/tuna monitor exec MONITOR_ID -- /scripts/backup.sh # Log cleanup every hour 0 * * * * /usr/local/bin/tuna monitor exec MONITOR_ID -- /scripts/cleanup.sh ``` ### Logging When `monitor exec` is used the system captures stdout and stderr of the running command. The logs can be viewed in the web UI in the monitor's event history. ![screenshot with the message field content](/docs/img/monitors/event.png) To disable sending logs use the `--no-stdout` flag: ```bash tuna monitor exec MONITOR_ID --no-stdout -- ./command.sh ``` ### Signal handling `monitor exec` handles Unix signals correctly: * On SIGINT, SIGTERM, SIGHUP — the signal is forwarded to the child process * When the child process exits with a non-zero code — `fail` is sent * On clean exit (exit code 0) — `finish` is sent *** ## monitor status Shows the status of the team's monitors. To view the status you need an [API key](https://tuna.am/en/docs/guides/api.md). ### Syntax ```bash tuna monitor status [MONITOR_ID] [flags] ``` ### Parameters | Parameter | Description | Default | | ----------- | ------------------------------- | --------------- | | `KEY` | Specific monitor key (optional) | — | | `--api-key` | API key for authorization | `$TUNA_API_KEY` | ### Examples #### Status of all monitors ```bash tuna monitor status ``` #### Status of a specific monitor ```bash tuna monitor status MONITOR_ID ``` *** ## Practical examples ### PostgreSQL backup with monitoring ```bash #!/bin/bash # /scripts/backup-postgres.sh BACKUP_DIR="/backups/postgres" DATE=$(date +%Y%m%d_%H%M%S) DB_NAME="production" tuna monitor exec MONITOR_ID --host=pg-prod-replica-1 -- bash -c " pg_dump -U postgres $DB_NAME | gzip > $BACKUP_DIR/${DB_NAME}_${DATE}.sql.gz # Remove old backups (older than 7 days) find $BACKUP_DIR -name '*.sql.gz' -mtime +7 -delete " ``` ### File synchronization ```bash #!/bin/bash # /scripts/sync-files.sh tuna monitor exec MONITOR_ID -- rsync -avz --delete /data/ backup-server:/backups/data/ ``` ### Monitoring a service in Docker ```bash #!/bin/bash # healthcheck.sh inside the container # Check application health if curl -sf http://localhost:8080/health > /dev/null; then tuna monitor ping MONITOR_ID --message="healthy" else tuna monitor ping MONITOR_ID --state=fail --message="unhealthy" fi ``` ### Monitoring GitLab Runner ```bash # In crontab on the GitLab Runner machine */5 * * * * /usr/local/bin/tuna monitor ping MONITOR_ID --host=raspberry-pi --message="Runner active" ```