Seer CLI Documentation

Seer CLI is a command-line tool that wraps your existing scripts and automatically sends execution data to Seer for monitoring. No code changes required — just prefix your commands with seer run.

Key Features

• Zero Code Changes: Monitor existing scripts without modifications
• Automatic Log Capture: Captures stdout and stderr; synced progressively while the job runs (default every 10 s)
• Offline Resilience: If Seer is unreachable, the command still runs locally. Only the final outcome is queued — no forever-running stubs. Exit code is always preserved.
• Shared Offline Queue: Uses the same ~/.seer/queue format as SeerPy — events queued by either client can be flushed by either.
• Cross-Platform: Works on Linux, macOS, and Windows
• Language Agnostic: Works with Python, Node.js, Shell scripts, and more

Quick Install (Linux/macOS)

curl -fsSL https://raw.githubusercontent.com/seer-monitoring/seer-cli/main/cli/install.sh | sh

Build from Source

cd cli
go build -o seer .

Prefer manual installation? Download binaries directly

Verify Installation

seer --version

Required

export SEER_API_KEY="your-api-key-here"

Get your API key from your SEER dashboard — API Keys.

Optional Environment Variables

Add to Shell Profile

# Add to ~/.bashrc or ~/.zshrc
export SEER_API_KEY="your-api-key-here"

Wrap any command with seer run. The job name must match a pipeline that exists in your Seer dashboard.

Python Script

seer run daily_etl --tags=etl,prod -- python etl.py

Node.js Script

seer run data_sync -- node sync-data.js

Shell Script

seer run backup_database -- ./backup.sh

Any Command

seer run docker_cleanup -- docker system prune -af

PowerShell

$env:SEER_API_KEY = "your_key"
seer run daily_etl --tags=etl,prod -- python etl.py

Send a one-time liveness signal to a pipeline:

seer heartbeat worker_process --metadata='{"pid":1234}' --tags=prod

Metadata & Tags

seer run etl_pipeline \
  --metadata='{"environment":"production","version":"2.1.0"}' \
  --tags=etl,prod \
  -- python etl.py

Progressive Log Sync

Logs are captured and synced to the dashboard while the job runs (default every 10 s). Disable or adjust:

# Disable log capture entirely
seer run my_job --capture-logs=false -- python script.py

# Change sync interval (0 disables mid-run syncing)
seer run my_job --log-sync-interval=30 -- python script.py

Offline Mode & Replay

If the Seer API is unreachable, the command still runs locally and only the final outcome is queued. Exit code is always preserved.

# Auto-replay (default: on) — flushes queue once at startup
seer run critical_job -- python script.py

# Skip auto-replay at startup
seer run critical_job --no-auto-replay -- python script.py

# Flush queue periodically while the job runs
seer run long_job --background-replay --replay-interval=60 -- python script.py

# Flush manually anytime
seer replay

Custom API Host

seer run my_job --base-url=https://seer.internal.company.com -- python script.py
# or
export SEER_BASE_URL=https://seer.internal.company.com

seer run

seer run <job-name> [flags] [--] <command> [args...]

Flags:
  --capture-logs=true|false    Capture stdout/stderr (default true)
  --log-sync-interval=<sec>    Progressive log upload interval (default 10; 0 disables)
  --metadata=<json>            JSON object attached to the run
  --tags=a,b,c                 Comma-separated tags
  --base-url=<url>             Override API host
  --no-auto-replay             Skip one-shot queue flush on start
  --background-replay          Flush queue periodically while job runs
  --replay-interval=<sec>      Background interval (default 60)

seer heartbeat

seer heartbeat <job-name> [--metadata=<json>] [--tags=a,b] [--base-url=<url>]

seer replay

seer replay [--max-attempts=5] [--base-url=<url>]

# replay-failed is kept as an alias for compatibility
seer replay-failed

seer --version

seer --version

Cron Jobs

# Crontab entry
0 2 * * * SEER_API_KEY=your_key /usr/local/bin/seer run nightly_backup -- /path/to/backup.sh

CI/CD Pipelines

# GitHub Actions / GitLab CI
seer run deploy_production \
  --metadata='{"commit":"$GITHUB_SHA"}' \
  --tags=deploy \
  -- ./deploy.sh

Data Processing

seer run daily_etl \
  --metadata='{"source":"warehouse"}' \
  --tags=etl,prod \
  -- python process_data.py

System Maintenance

seer run log_rotation -- logrotate /etc/logrotate.conf

CLI Not Found

# Check if binary is in PATH
which seer

# Add to PATH if needed
export PATH="$HOME/.local/bin:$PATH"

Authentication Errors

• Verify your API key is correct
• Check SEER_API_KEY environment variable is set
• Regenerate API key from dashboard API Keys

Inspecting the Offline Queue

# View queued envelopes
ls ~/.seer/queue/

# View dead-lettered envelopes (repeated failures)
ls ~/.seer/queue/dead/

# Flush the queue manually
seer replay

Permission Denied

chmod +x /usr/local/bin/seer

• Getting Started Guide — Learn the basics of SEER
• Python SDK (seerpy) Documentation — For deeper Python integration
• Configure Notifications — Set up Slack or email alerts
• View Your Dashboard — Monitor your jobs