cimon

README

cimon

Terminal-first CI monitor for GitHub Actions. Check your workflow status without leaving the terminal.

Features

Core Monitoring

• Zero friction - Run inside any git repo and auto-detect repository/branch
• Fast feedback - See workflow runs, jobs, and status instantly
• Watch mode - Poll until completion with real-time updates (-w)
• Multi-repo dashboard - Monitor multiple repos in one view (--repos or cimon.yml)
• Multi-run history - Browse 10+ recent workflow runs with pagination
• Branch switching - Monitor CI across different branches (b key)
• Status filtering - Filter by success, failure, running, queued (f key)

Deep Inspection

• Job details - Drill into individual jobs with step-by-step breakdown
• Live logs - Stream logs from running jobs with automatic refresh
• Log search - Find specific errors or messages within logs (/ key)
• Interactive navigation - Full keyboard-driven interface

Workflow Control

• Rerun workflows - Restart failed builds with confirmation (cimon retry)
• Cancel runs - Stop running workflows safely (cimon cancel)
• Trigger dispatches - Start manual workflows (cimon dispatch <workflow>)

Developer Experience

• Great terminal UX - Clean TUI with comprehensive keyboard shortcuts
• Scriptable - JSON/plain output modes for automation
• Multiple output formats - Human-readable, JSON, and plain text
• Cross-platform - Works on Linux, macOS, and Windows
• Accessibility - NO_COLOR support and clear visual feedback

Installation

From source

go install github.com/lance0/cimon/cmd/cimon@latest

From releases

Download the latest binary from Releases.

Usage

# Monitor current repo and branch
cimon

# Monitor a specific branch
cimon --branch main

# Watch until completion
cimon --watch

# Override repo detection
cimon --repo owner/name --branch main

# Monitor multiple repos
cimon --repos owner/repo1,owner/repo2,owner/repo3

Multi-Repo Configuration

Create a cimon.yml file in your project root for persistent multi-repo monitoring:

repositories:
  - owner/repo1
  - owner/repo2
  - owner/repo3

Then just run cimon to monitor all configured repos in a single dashboard.

Keyboard Shortcuts

Key	Action
r	Refresh
w	Toggle watch mode
o	Open run/job in browser
b	Select branch
f	Filter by status
h/l or ←/→	Navigate between runs
j/k or ↑/↓	Navigate jobs/steps/logs/branches/filters
enter	Show job details / select branch/filter
l	View/exit job logs
/	Search in logs
n	Next search match
N	Previous search match
s	Save logs to file
H	Toggle syntax highlighting
F	Filter logs by step
m	Multi-job view (select up to 4)
c	Compare logs between runs
y	View workflow YAML
a	Download artifacts
?	Show help
q	Quit

Flags

-b, --branch string   Branch name
-r, --repo string     Repository in owner/name format
    --repos string    Comma-separated repos for multi-repo mode
-w, --watch           Watch mode - poll until completion
-p, --poll duration   Poll interval for watch mode (default 5s)
    --notify          Desktop notification on completion (watch mode)
    --hook string     Run script on completion with env vars (watch mode)
    --json            JSON output for scripting
    --no-color        Disable color output
    --plain           Plain text output (no TUI)
-v, --version         Show version

Exit Codes

Code	Meaning
0	Success (or neutral/skipped)
1	Failure (or cancelled/timed out)
2	Error (auth, not found, etc.)

Authentication

cimon uses GitHub authentication in this order:

1. gh CLI (recommended) - If you have gh installed and authenticated
2. GITHUB_TOKEN - Environment variable

# Option 1: Use gh CLI
gh auth login

# Option 2: Set token directly
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx

Environment Variables

• NO_COLOR - Disable colored output in TUI mode (equivalent to --no-color flag)

Examples

# Quick CI check before pushing
cimon && git push

# Wait for CI to finish
cimon -w

# Check CI on main branch
cimon -b main

# Get plain text output for scripting
cimon --plain

# Get JSON output for automation/scripting
cimon --json

# Monitor a different repo
cimon -r octocat/hello-world -b main

Troubleshooting

Authentication Issues

• "not authenticated to GitHub": Run gh auth login or set GITHUB_TOKEN
• "403 Forbidden": Check repository access permissions
• "rate limit exceeded": Wait a few minutes or authenticate to increase limits

Repository Detection

• "not a git repository": Run cimon from inside a git repo, or use --repo owner/name
• "detached HEAD": Use --branch to specify a branch explicitly

Display Issues

• Colors not showing: Ensure terminal supports ANSI colors; try without --no-color
• UI looks broken: Try a different terminal emulator or resize window

Common Fixes

• Update to latest version: go install github.com/lance0/cimon/cmd/cimon@latest
• Check GitHub status: https://www.githubstatus.com/

License

MIT