stackeye-cli

StackEye CLI

Command-line interface for StackEye - the full-stack uptime monitoring platform.

Overview

The StackEye CLI (stackeye) provides command-line access to the StackEye uptime monitoring platform. Authenticate with your account, manage configuration contexts, and integrate monitoring into your automation workflows.

Current Features:

• Browser-based authentication via OAuth
• Multi-context configuration management
• API key management
• Probe management (list, create, update, delete, pause, resume, test, watch, export/import, dependencies)
• Alert management (list, acknowledge, resolve, history, stats)
• Notification channel management (email, Slack, Discord, Teams, PagerDuty, webhook, SMS)
• Status pages (create, update, custom domains, incidents)
• Maintenance windows and alert mute periods
• Team management (invite, roles, invitations)
• Probe labels for filtering and organization
• Self-hosted agents and private monitoring regions
• Billing and subscription management
• Organization switching
• Dashboard view
• Shell completion for bash, zsh, fish, and PowerShell

Installation

Installer Script (Recommended for macOS/Linux)

The easiest way to install StackEye CLI:

curl -fsSL https://releases.stackeye.io/install.sh | bash

This auto-detects your OS and architecture, downloads the appropriate binary, verifies the checksum, and installs it.

Options:

• Install a specific version: curl -fsSL https://releases.stackeye.io/install.sh | bash -s -- --version v1.0.0
• Install to custom directory: STACKEYE_INSTALL_DIR=~/bin curl -fsSL https://releases.stackeye.io/install.sh | bash

The script installs to /usr/local/bin (with sudo) or ~/.local/bin (without sudo) by default.

Installer Script (Windows PowerShell)

iwr -useb https://releases.stackeye.io/install.ps1 | iex

This auto-detects your architecture, downloads the appropriate binary, verifies the checksum, and installs it to %LOCALAPPDATA%\StackEye\bin.

Options:

• Install a specific version: $env:STACKEYE_VERSION = "v1.0.0"; iwr -useb https://releases.stackeye.io/install.ps1 | iex
• Install to custom directory: $env:STACKEYE_INSTALL_DIR = "C:\custom\path"; iwr -useb https://releases.stackeye.io/install.ps1 | iex

The script automatically adds the install directory to your User PATH.

Manual Download

Download pre-built archives from GitHub Releases. Archives are named stackeye_<VERSION>_<OS>_<ARCH>.tar.gz.

macOS (Apple Silicon):

# Replace VERSION with the actual version (e.g., 1.0.0)
VERSION=$(curl -fsSL https://api.github.com/repos/StackEye-IO/stackeye-cli/releases | grep '"tag_name"' | head -1 | sed -E 's/.*"tag_name": *"v?([^"]+)".*/\1/')
curl -Lo stackeye.tar.gz "https://github.com/StackEye-IO/stackeye-cli/releases/download/v${VERSION}/stackeye_${VERSION}_darwin_arm64.tar.gz"
tar -xzf stackeye.tar.gz
sudo mv stackeye /usr/local/bin/
rm stackeye.tar.gz

macOS (Intel):

VERSION=$(curl -fsSL https://api.github.com/repos/StackEye-IO/stackeye-cli/releases | grep '"tag_name"' | head -1 | sed -E 's/.*"tag_name": *"v?([^"]+)".*/\1/')
curl -Lo stackeye.tar.gz "https://github.com/StackEye-IO/stackeye-cli/releases/download/v${VERSION}/stackeye_${VERSION}_darwin_amd64.tar.gz"
tar -xzf stackeye.tar.gz
sudo mv stackeye /usr/local/bin/
rm stackeye.tar.gz

Linux (x86_64):

VERSION=$(curl -fsSL https://api.github.com/repos/StackEye-IO/stackeye-cli/releases | grep '"tag_name"' | head -1 | sed -E 's/.*"tag_name": *"v?([^"]+)".*/\1/')
curl -Lo stackeye.tar.gz "https://github.com/StackEye-IO/stackeye-cli/releases/download/v${VERSION}/stackeye_${VERSION}_linux_amd64.tar.gz"
tar -xzf stackeye.tar.gz
sudo mv stackeye /usr/local/bin/
rm stackeye.tar.gz

Linux (ARM64):

VERSION=$(curl -fsSL https://api.github.com/repos/StackEye-IO/stackeye-cli/releases | grep '"tag_name"' | head -1 | sed -E 's/.*"tag_name": *"v?([^"]+)".*/\1/')
curl -Lo stackeye.tar.gz "https://github.com/StackEye-IO/stackeye-cli/releases/download/v${VERSION}/stackeye_${VERSION}_linux_arm64.tar.gz"
tar -xzf stackeye.tar.gz
sudo mv stackeye /usr/local/bin/
rm stackeye.tar.gz

Windows (PowerShell):

# Get latest version
$VERSION = (Invoke-RestMethod "https://api.github.com/repos/StackEye-IO/stackeye-cli/releases")[0].tag_name.TrimStart('v')

# Download and extract
Invoke-WebRequest -Uri "https://github.com/StackEye-IO/stackeye-cli/releases/download/v${VERSION}/stackeye_${VERSION}_windows_amd64.zip" -OutFile stackeye.zip
Expand-Archive stackeye.zip -DestinationPath .
Move-Item stackeye.exe C:\Windows\System32\stackeye.exe
Remove-Item stackeye.zip

Go Install

If you have Go 1.25+ installed:

go install github.com/StackEye-IO/stackeye-cli/cmd/stackeye@latest

The binary will be installed to $GOPATH/bin/stackeye (or $HOME/go/bin/stackeye if GOPATH is not set).

Build from Source

Requires Go 1.25 or later:

# Clone the repository
git clone https://github.com/StackEye-IO/stackeye-cli.git
cd stackeye-cli

# Build the binary
make build

# The binary is at bin/stackeye
# Optionally move to your PATH:
sudo mv bin/stackeye /usr/local/bin/

Homebrew (macOS/Linux)

brew install stackeye-io/tap/stackeye

Scoop (Windows)

# Add the StackEye bucket
scoop bucket add stackeye-io https://github.com/StackEye-IO/scoop-bucket

# Install
scoop install stackeye

# Update
scoop update stackeye

Linux Packages (.deb / .rpm)

StackEye does not currently publish an APT or YUM/DNF repository, and no .deb or .rpm packages are attached to releases. On Debian, Ubuntu, RHEL, Fedora and CentOS, use the installer script, a manual archive download, Homebrew, go install, or Docker.

Docker

Run the CLI directly from a container:

# Run a command
docker run --rm ghcr.io/stackeye-io/stackeye-cli version

# Use with API key
docker run --rm -e STACKEYE_API_KEY=se_your_key ghcr.io/stackeye-io/stackeye-cli probe list

# Pin to a specific version
docker run --rm ghcr.io/stackeye-io/stackeye-cli:v1.0.0 version

Multi-arch images are available for linux/amd64 and linux/arm64.

Verifying Downloads

Every release publishes a checksums.txt covering all archives. To verify a download:

VERSION=$(curl -fsSL https://api.github.com/repos/StackEye-IO/stackeye-cli/releases | grep '"tag_name"' | head -1 | sed -E 's/.*"tag_name": *"v?([^"]+)".*/\1/')

# Download the checksums for your version
curl -LO "https://releases.stackeye.io/cli/v${VERSION}/checksums.txt"

# Verify your downloaded archive against the checksums
sha256sum -c checksums.txt --ignore-missing

checksums.txt is not currently accompanied by a detached GPG signature, so this verifies integrity against the published checksums but does not independently authenticate them.

Quick Start

Get monitoring up and running in minutes. For a comprehensive walkthrough, see the Getting Started Tutorial.

1. Authenticate

# Login via browser (opens your default browser)
stackeye login

# Output:
# Opening browser to: https://stackeye.io/cli-auth?...
# Waiting for authentication...
# (If the browser doesn't open, visit the URL manually)
#
# Verifying credentials... done
#
# Successfully logged in!
#   Organization: {org_name}
#   Context:      {context_name}
#   API URL:      https://api.stackeye.io
#
# Credentials saved to: ~/.config/stackeye/config.yaml

2. Verify Authentication

# Check current user
stackeye whoami

# Output:
#
# User:         {user_email}
# Name:         {user_name}
#
# Context:      {context_name}
# Organization: {org_name} ({org_id})
# API URL:      https://api.stackeye.io
# Auth Type:    api_key

3. View Configuration

# Show current configuration
stackeye config get

# Output:
# Current Context:    {context_name}
# API URL:            https://api.stackeye.io
# API Key:            se_****...xxxx
# Organization:       {org_name}
# Organization ID:    {org_id}
# Config File:        ~/.config/stackeye/config.yaml

CI/CD and Automation

For non-interactive environments (CI/CD pipelines, scripts, Docker containers), the CLI supports direct API key authentication.

Environment Variable (Recommended)

# Set API key via environment variable
export STACKEYE_API_KEY=se_your_api_key_here

# Setup and verify configuration
stackeye setup --no-input

# Create probes using stored credentials
stackeye probe create --name "Production API" --url https://api.example.com

Command Flags (Single-Command Setup)

# Full setup with API key and probe creation
stackeye setup --no-input \
  --api-key se_your_api_key_here \
  --probe-name "Production API" \
  --probe-url https://api.example.com

# API key only (no probe creation)
stackeye setup --no-input --api-key se_your_api_key_here

GitHub Actions Example

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Setup StackEye monitoring
        env:
          STACKEYE_API_KEY: ${{ secrets.STACKEYE_API_KEY }}
        run: |
          curl -fsSL https://releases.stackeye.io/install.sh | bash
          stackeye setup --no-input
          stackeye probe create --name "${{ github.repository }}" --url "https://api.example.com"

Configuration Precedence

1. --api-key command flag (highest)
2. STACKEYE_API_KEY environment variable
3. Config file (~/.config/stackeye/config.yaml)

Commands

Authentication & Configuration

Command	Description
stackeye login	Authenticate with StackEye via browser
stackeye logout	Clear stored credentials for current context
stackeye setup	Interactive setup wizard for first-time users
stackeye whoami	Display current authenticated user
stackeye config get	Display current configuration
stackeye config set-key	Set API key for authentication
stackeye context list	List all configured contexts
stackeye context use <name>	Switch to a different context
stackeye context current	Display active context
stackeye completion <shell>	Generate shell completion script
stackeye version	Print version information

Probe Management

Command	Description
stackeye probe list	List all monitoring probes
stackeye probe get <id>	Get probe details
stackeye probe create	Create a new probe
stackeye probe update <id>	Update probe configuration
stackeye probe delete <id>	Delete a probe
stackeye probe pause <id>	Pause probe monitoring
stackeye probe resume <id>	Resume probe monitoring
stackeye probe test <id>	Run an immediate probe check
stackeye probe history <id>	View probe check history
stackeye probe stats <id>	View probe statistics

Alert Management

Command	Description
stackeye alert list	List current alerts
stackeye alert get <id>	Get alert details
stackeye alert ack <id>	Acknowledge an alert
stackeye alert resolve <id>	Resolve an alert
stackeye alert history	View alert history

Notification Channels

Command	Description
stackeye channel list	List notification channels
stackeye channel get <id>	Get channel details
stackeye channel create	Create a notification channel
stackeye channel update <id>	Update channel configuration
stackeye channel delete <id>	Delete a channel
stackeye channel test <id>	Send a test notification

Organization & Dashboard

Command	Description
stackeye org list	List accessible organizations
stackeye org get	Get current organization details
stackeye org switch <id>	Switch to a different organization
stackeye dashboard	Display dashboard overview
stackeye region list	List available monitoring regions
stackeye region status	Show health status of monitoring regions
stackeye api-key list	List API keys
stackeye api-key create	Create a new API key
stackeye api-key delete <id>	Delete an API key

The api-key command also accepts the apikey alias.

Status Pages & Incidents

Command	Description
stackeye status-page list	List all status pages
stackeye status-page create	Create a new status page
stackeye status-page update <id>	Update an existing status page
stackeye status-page delete <id>	Delete a status page
stackeye status-page add-probe	Add a probe to a status page
stackeye status-page domain-verify <id>	Get DNS verification record for a custom domain
stackeye incident list	List incidents for a status page
stackeye incident create	Create a new incident
stackeye incident update <id>	Update an existing incident
stackeye incident resolve <id>	Resolve an incident

Maintenance & Mutes

Command	Description
stackeye maintenance list	List all maintenance windows
stackeye maintenance create	Schedule a new maintenance window
stackeye maintenance calendar	Show maintenance windows in calendar view
stackeye maintenance delete <id>	Delete a scheduled maintenance window
stackeye mute list	List all alert mute periods
stackeye mute create	Create a new alert mute period
stackeye mute expire <id>	Immediately expire an active mute period
stackeye mute delete <id>	Delete an alert mute period

Team & Labels

Command	Description
stackeye team list	List all team members
stackeye team invite	Invite a new team member
stackeye team update-role	Update a team member's role
stackeye team remove	Remove a team member
stackeye team invitations	List pending team invitations
stackeye label list	List all label keys in your organization
stackeye label create	Create a new label key
stackeye probe label <id> <k=v>	Add labels to a probe

Agents, Private Regions & Billing

Command	Description
stackeye agent list	List all registered self-hosted agents
stackeye agent register	Register a new self-hosted agent
stackeye private-region list	List all private monitoring regions
stackeye private-region create	Create a new private monitoring region
stackeye private-region rotate-key <id>	Rotate the bootstrap key for a private region
stackeye billing status	Show current billing status
stackeye billing usage	Show current resource usage against plan limits
stackeye billing invoices	List billing invoices
stackeye telemetry status	Show current telemetry (anonymous analytics) status

Run stackeye --help for complete command documentation, or stackeye <command> --help for any subcommand.

Authentication Commands

stackeye login

Authenticate with StackEye via browser-based OAuth flow:

# Login to production StackEye
stackeye login

# Login to a specific environment
stackeye login --api-url https://api.dev.stackeye.io

stackeye logout

Clear stored credentials:

# Logout from current context
stackeye logout

# Logout from all contexts
stackeye logout --all

stackeye whoami

Display information about the authenticated user:

stackeye whoami

Configuration Commands

stackeye config get

Display current configuration:

stackeye config get

stackeye config set-key

Set an API key directly (alternative to browser login):

# Set API key interactively (recommended)
stackeye config set-key

# Set API key with verification
stackeye config set-key --verify

# Set API key for specific context
stackeye config set-key --context production

Context Commands

Contexts allow switching between different organizations or environments, similar to kubectl contexts for Kubernetes.

stackeye context list

List all configured contexts:

stackeye context list

# Output:
#    NAME                 ORGANIZATION              API URL
# *  {context_name}       {org_name}                https://api.stackeye.io
#    {context_name_dev}   {org_name}                https://api.dev.stackeye.io

stackeye context use

Switch to a different context:

stackeye context use {context_name}

stackeye context current

Display the active context:

stackeye context current

Configuration

Config File Location

Configuration is stored in ~/.config/stackeye/config.yaml:

# Current active context
current_context: {context_name}

# Configured contexts
contexts:
  {context_name}:
    api_url: https://api.stackeye.io
    api_key: se_{api_key_suffix}
    organization_id: {org_id}
    organization_name: {org_name}
  {context_name_dev}:
    api_url: https://api.dev.stackeye.io
    api_key: se_{api_key_suffix_dev}
    organization_name: {org_name}

# User preferences
preferences:
  output_format: table    # table, json, yaml, wide
  color: auto             # auto, always, never
  debug: false

Environment Variables

Variable	Description	Default
STACKEYE_API_URL	Override API URL	https://api.stackeye.io
STACKEYE_API_KEY	Override API key	(from config)
STACKEYE_CONFIG	Custom config file path	~/.config/stackeye/config.yaml
NO_COLOR	Disable colored output	(unset)

Global Flags

These flags are available on all commands:

Flag	Description
--config <path>	Use custom config file
--context <name>	Override current context
--output, -o <format>	Output format: table, json, yaml, wide
--no-color	Disable colored output
--no-input	Disable interactive prompts
--dry-run	Show what would be done
--debug	Enable debug output
--help, -h	Show help

Shell Completion

Enable tab completion for your shell:

Bash

# Add to ~/.bashrc
source <(stackeye completion bash)

# Or install to system-wide location
stackeye completion bash > /etc/bash_completion.d/stackeye

Zsh

# Add to ~/.zshrc (before compinit)
source <(stackeye completion zsh)

# Or install to fpath
stackeye completion zsh > "${fpath[1]}/_stackeye"

Fish

# Add to ~/.config/fish/config.fish
stackeye completion fish | source

# Or install to completions directory
stackeye completion fish > ~/.config/fish/completions/stackeye.fish

PowerShell

# Add to your PowerShell profile
stackeye completion powershell | Out-String | Invoke-Expression

# Or save to a file and dot-source it
stackeye completion powershell > stackeye.ps1

Exit Codes

Code	Meaning
0	Success
1	General error
2	Command misuse (invalid arguments)
3	Authentication required
4	Permission denied
5	Resource not found
6	Rate limited
7	Server error
8	Network error
9	Timeout
10	Plan limit exceeded

Roadmap

Features previously on the roadmap that have now shipped:

• Status Pages: stackeye status-page list, create, update (plus custom domains and incidents)
• Watch Mode: stackeye probe watch for live terminal updates
• Incident Management: stackeye incident list, create, update, resolve
• Team Management: stackeye team list, invite, remove, update-role
• Maintenance Windows: stackeye maintenance list, create, calendar
• Alert Mutes: stackeye mute list, create, expire
• Self-Hosted Agents & Private Regions: stackeye agent register, stackeye private-region create

See the Commands section for the full, current command set.

Contributing

Contributions are welcome!

Development Setup

# Clone the repository
git clone https://github.com/StackEye-IO/stackeye-cli.git
cd stackeye-cli

# Install dependencies
go mod download

# Build
make build

# Run tests
make test

# Run linters
make lint

# Full validation
make validate

Submit issues and pull requests on GitHub.

Support

• Documentation: docs.stackeye.io
• Issues: GitHub Issues
• Discussions: GitHub Discussions

License

MIT License - see LICENSE for details.