Kickbacks CLI

Product Introduction

1. Definition: The Kickbacks CLI is a local-first, command-line interface (CLI) tool and companion macOS menu bar application for the Kickbacks.ai browser extension. It is a read-only, independent utility that provides terminal and system-level access to user earnings and advertising status data.
2. Core Value Proposition: It exists to provide developers and power users with a transparent, secure, and immediate way to monitor their Kickbacks.ai affiliate earnings and ad rotation history directly from the terminal or macOS menu bar, without needing to open a browser, promoting a local-first and privacy-centric workflow.

Main Features

1. Terminal-Based Earnings Dashboard: Provides real-time command-line access to lifetime and "today" earnings. It executes a one-line curl or brew install, requiring only python3 and openssl (default on macOS). It operates by locally reading encrypted tokens from the user's editor state and macOS Keychain, then sending only the necessary authentication data to the official Kickbacks.ai backend API.
2. macOS Menu Bar Application (Kickbacks Bar): A native menu bar app that displays live earnings at a glance. It bundles the CLI tool and provides a graphical one-click interface to access full CLI functionality (earnings, ad history, daily chart, status). It is code-signed and notarized by Apple for security.
3. Local-First Data Analysis & History: Generates approximate per-ad earnings and daily charts by sampling local cli-ad.json and debug.log files written by the Kickbacks.ai extension. This feature, disabled by default, runs a 60-second background job to log ad rotations and attribute earnings changes, creating a derived history without accessing private advertiser data.
4. Safe-by-Default Configuration & Diagnostics: Every write-capable feature (network calls, background sampling, macOS notifications, token refresh) is opt-in, controlled via kickback config. The kickback doctor command performs live diagnostics on all dependencies (extension format, backend connectivity, keychain access, token validity). All paths and settings are user-editable in ~/.config/kickback/config.json.

Problems Solved

1. Pain Point: Lack of a quick, glanceable, and developer-centric interface for monitoring Kickbacks.ai earnings without interrupting workflow by switching to a browser or web dashboard.
2. Target Audience: Software developers and technical users who use Claude Code with the Kickbacks.ai extension, prefer terminal/CLI workflows, value data transparency, and utilize macOS. Specifically, developers who prioritize automation, local data control, and system integration.
3. Use Cases: A developer wanting to check their daily earnings instantly via a terminal command (kickback status); a user preferring a persistent, passive display of earnings in the macOS menu bar; a technically-minded user seeking to audit and understand their approximate earnings history derived from local data.

Unique Advantages

1. Differentiation: Unlike web dashboards or bundled analytics, this is an independent, read-only companion tool. It provides system-level integration (terminal, menu bar) that the official extension does not, while strictly limiting its network access to the official backend only, matching the extension's own traffic pattern.
2. Key Innovation: Its "safe by default" and "local-first" architecture. It discovers all configuration (account tokens, paths) at runtime, touches only necessary local files, and has zero telemetry to the tool's author. It gracefully degrades if the upstream extension changes, ensuring robustness without crashing. It transparently derives approximate ad earnings from aggregate data, clearly labeling its estimates.

Frequently Asked Questions (FAQ)

1. Is the Kickbacks CLI safe and secure to use? Yes, the Kickbacks CLI is designed with a security-first, local approach. It reads only existing local files from your editor and Kickbacks extension, uses your macOS Keychain for decryption, and sends data only to the official Kickbacks.ai backend. All write-capable features are disabled by default, and the code is open for inspection.
2. How accurate are the per-ad earnings and daily charts shown by the CLI? The earnings per ad and daily totals are approximate, derived estimates. The Kickbacks backend only provides aggregate lifetime and "today" earnings. The CLI attributes changes in these totals to the ad displayed at the time, calculating a share. These figures are clearly labeled as approximations of your share, not actual advertiser spend.
3. What happens if the Kickbacks.ai extension updates and breaks the CLI? The CLI is built to degrade gracefully. If the extension changes its token format or log file structure, features like live earnings will show as "unavailable," but the tool will not crash. Local status reading will continue to work where possible, and the kickback doctor command will help diagnose the specific issue.
4. Do I need to install Python or other dependencies separately? On macOS, openssl is pre-installed. If python3 is not present, the first run of the CLI or the menu bar app will prompt you to install Apple's free Command Line Tools, which include it. No additional pip packages are required.
5. What is the difference between installing via Homebrew and downloading the menu bar app? The Homebrew CLI install (brew install .../kickback) installs only the command-line tool. The Homebrew Cask or direct .zip download for the "Kickbacks Bar" menu bar app includes the CLI as a bundled dependency and sets it up automatically on first launch. Both methods result in the kickback command being available in your terminal.