Poe Usage

Monitor Poe API point balance and usage history from the terminal using poeusage CLI.

Security Scan

The skill's requirements and runtime instructions match its stated purpose (monitoring Poe API usage via the poeusage CLI); nothing requested is disproportionate, but the install uses a third‑party Homebrew tap which you should review before installing.

Purpose & Capability

Name/description, required binary (poeusage), and required env var (POE_API_KEY) align with a CLI tool that queries the Poe API for usage and balance information.

Instruction Scope

SKILL.md is instruction-only and confines actions to installing/running the poeusage CLI, reading its config (~/.config/poeusage/config.toml) and using POE_API_KEY. It does not instruct the agent to read unrelated files, exfiltrate data to unknown endpoints, or access unrelated credentials.

Install Mechanism

Install uses a Homebrew tap (rgstephens/tap) and formula 'poeusage'. Homebrew installs are common, but this is a third‑party tap (not an official central formula), so you should inspect the tap/formula and upstream repo before trusting the binary.

Credentials

Only POE_API_KEY (and ordinary opt-in envs like NO_COLOR/timeout/page_size) are referenced. Requesting the Poe API key is proportionate to the stated function. The SKILL.md notes storing api_key in ~/.config/poeusage/config.toml is possible but 'not recommended'.

Persistence & Privilege

Skill does not request always:true, does not modify other skills or system-wide settings, and relies on a standalone CLI binary. No elevated persistence or cross-skill privileges are requested.

Assessment

This skill appears to do what it claims: run the poeusage CLI using your POE_API_KEY to report Poe usage. Before installing: (1) review the Homebrew tap and formula (rgstephens/tap) and the upstream repo to confirm the binary's source and build steps; (2) avoid storing your API key in plaintext config files if possible — prefer passing POE_API_KEY at runtime or using a secure credential store; (3) verify the installed poeusage binary (checksums/signature) if provided; and (4) limit the API key's scope/rotate it if you stop using the tool. If you cannot inspect the tap or binary, treat the install as higher risk.

slug: poeusage version: 0.5.0

A ClawHub skill for monitoring Poe API point balance and usage history via the poeusage CLI.

Install

brew tap rgstephens/tap
brew install poeusage

Description

poeusage is a terminal utility to monitor your Poe API quota, usage history, and spend summaries. It supports JSON/csv/table output modes, pagination, filtering, and shell completion generation.

CLI Commands

Global flags

• --api-key string (default from $POE_API_KEY)
• --json bool
• --plain bool
• --no-color bool
• --quiet / -q bool
• --verbose / -v bool
• --timeout int (default 30)
• --help / -h bool
• --version bool

Subcommands

poeusage balance

Fetch and display current point balance.

Usage:

poeusage balance [--json] [--plain]

• TTY example: Current balance: 1,500 pts
• --plain example: 1500
• --json example: {"current_point_balance":1500}

poeusage history

Fetch usage history. Auto-paginates by default until all records are retrieved (or until --limit).

Usage:

poeusage history [flags]

Flags:

• --limit / -n int (0 == all)
• --page-size int (default 100, max 100)
• --no-paginate bool
• --cursor string
• --bot / -b string
• --type / -t string (chat, api, canvas)
• --since string (YYYY-MM-DD or unix timestamp)
• --until string (YYYY-MM-DD or unix timestamp)
• --output / -o string
• --format / -f string (table, csv, json)

Notes:

• --json is alias for --format json
• --plain is alias for --format csv
• date filters are applied client-side
• with --no-paginate, prints next-cursor: <query_id> to stderr if more pages exist

Default table output columns: TIME, BOT, TYPE, POINTS, COST (USD)

CSV output columns: time,bot_name,usage_type,cost_points,cost_usd,query_id,chat_name,input_pts,output_pts,cache_write_pts,cache_discount_pts

JSON output example:

[
  {
    "bot_name": "Claude-3.5-Sonnet",
    "time": "2024-01-09T14:00:00Z",
    "query_id": "2Nhd9xBFbLcXEwmNj",
    "cost_usd": "0.00075",
    "cost_points": 339,
    "usage_type": "API",
    "chat_name": null,
    "cost_breakdown": {
      "input": 120,
      "output": 219,
      "cache_write": 0,
      "cache_discount": 0,
      "total": 339
    }
  }
]

poeusage summary

Aggregate usage and display cost breakdown. Same filters as history plus grouping.

Usage:

poeusage summary [flags]

Flags:

• --bot / -b string
• --type / -t string
• --since string
• --until string
• --group-by / -g string (bot, type, day, bot,type)
• --format / -f string (table, csv, json)

Default table output columns (group-by bot): BOT, QUERIES, POINTS, COST (USD)

poeusage completion <shell>

Generate shell completion script.

Usage:

poeusage completion <bash|zsh|fish>

Example:

poeusage completion zsh > ~/.zsh/completions/_poeusage

I/O contract

• stdout: primary command output
• stderr: diagnostics, progress, warnings, next-cursor hints
• TTY detection controls color and formatting

Exit codes

• 0: success
• 1: runtime error (network/API error)
• 2: invalid usage
• 3: auth error (401)

Configuration

Priority: flags > env > config file > defaults

Env vars:

• POE_API_KEY
• NO_COLOR
• POEUSAGE_TIMEOUT
• POEUSAGE_PAGE_SIZE

Config file: ~/.config/poeusage/config.toml

# api_key = "..." # not recommended
timeout = 30
page_size = 100

Release

• make release TAG=v1.0.0