SuperPenguin Docs

Use the SuperPenguin CLI

Investigate AI spend, provider billing, coding usage, unit costs, and optimization tickets from your terminal or an AI agent with the SuperPenguin CLI.

The SuperPenguin CLI gives you and your terminal-based AI agent typed commands for your organization's AI spend, provider billing, coding usage, unit costs, and optimization tickets. It uses the same organization-scoped Agent API operations as the remote MCP server.

Use the CLI when your agent can run terminal commands. Use MCP when your client connects to remote MCP servers, or the Agent API when you are building a custom HTTP integration.

Install and sign in

Install on macOS or Linux:

curl -fsSL https://install.superpenguin.ai | sh
superpenguin --version
superpenguin auth login

Login opens SuperPenguin's OAuth flow in your browser. Sign in, choose your organization, review the requested scopes, and approve access. You do not need an API key or client secret. Run login interactively, without --agent, so you can complete the browser flow.

The connection is bound to your user, OAuth client, and selected organization. Every request checks current membership, role, plan, and scopes. To change organizations, sign in again and select the organization you want to investigate. You can revoke access from Agent connections.

If your shell cannot find superpenguin after installation, follow the installer's PATH instructions and reopen your terminal. Running the installer again installs the current official release.

Give these instructions to an agent

Read https://superpenguin.ai/docs/cli. Install the SuperPenguin CLI from https://install.superpenguin.ai if needed, then run superpenguin auth login interactively. Pause while I sign in, choose my organization, and approve access. After login, run superpenguin context --agent, discover the smallest relevant operation with superpenguin capabilities list, and inspect command help before choosing flags. Use --agent for structured JSON on data commands. Preserve warnings and distinguish usage estimates from provider billing.

Start with context and discovery

superpenguin context --agent
superpenguin capabilities list --query "weekly spend" --agent
superpenguin usage summary --help

Context identifies the selected organization, granted scopes, supported workflows, and data caveats. Discovery returns relevant operation schemas and examples. Command help describes the available flags and valid values.

--agent enables structured JSON, compact output, and noninteractive defaults. It does not format results as Markdown. Check the process exit status as well as the response; failed commands return a nonzero status.

Ask spend questions

Use usage summaries for SDK and OpenTelemetry spend. Use provider billing when the question explicitly concerns invoices or reconciliation:

# SDK and OpenTelemetry spend this month.
superpenguin usage summary --window month_to_date --agent

# Usage grouped by provider.
superpenguin usage breakdown --group-by provider --limit 10 --agent

# Provider billing for an explicit invoice or reconciliation question.
superpenguin billing summary --window month_to_date --agent

Named windows use UTC unless you supply a supported timezone. For exact bounds, inspect the command's help and supply both endpoints. Missing or incomplete cost means unknown, not zero. Keep warnings and distinguish observed usage, billed cost, pending amounts, and API-equivalent estimates.

Inspect coding usage

Start with an aggregate for the tool and scope you need, then inspect selected sessions:

superpenguin coding usage-summary --tool cursor --scope self --window this_week --agent
superpenguin coding sessions list --tool cursor --scope self --status observed --limit 10 --agent

Coding tools include cursor, claude_code, and codex. Organization-wide access depends on your role and granted scopes. Use observed for session listings; active and completed session filters are currently unavailable. Follow returned pagination cursors instead of repeatedly requesting the first page.

See cost per business unit

Unit costs report LLM cost per business unit, such as one SDK generation or one end user, over the configured window:

superpenguin unit-costs get --agent
superpenguin unit-costs get --trend-limit 0 --agent --select data.status,data.headline.units,data.headline.averageMicros,data.missingId,data.unpriced

A status of not_configured means no unit is defined for your organization. averageMicros is null when no unit has a known cost; treat it as unknown, not zero. Calls without the unit identifier are counted in missingId, not in the average.

Work on optimization tickets

superpenguin tickets list --status todo --limit 10 --agent --select data.tickets.id,data.tickets.displayId,data.tickets.title,data.tickets.revision,data.nextCursor
superpenguin tickets get 6f1c2a9e-0d4b-4c8e-9a51-3b7f2e8d1c40 --agent --select data.ticket.revision,data.ticket.summary,data.ticket.savings
superpenguin tickets update 6f1c2a9e-0d4b-4c8e-9a51-3b7f2e8d1c40 --status in_progress --expected-revision 2026-10-16T10:00:00.000Z --agent
superpenguin tickets comments add 6f1c2a9e-0d4b-4c8e-9a51-3b7f2e8d1c40 --body "Enabled prompt caching; measuring the hit rate this week." --agent

Pass a ticket's id (a UUID) to the other ticket commands. Display IDs such as OPT-12 are numbered per organization, so they are not stable identifiers outside it. Pass the revision from tickets list or tickets get as --expected-revision; if someone changed the ticket since you read it, the update fails with revision_changed and you should read it again before retrying.

tickets update and tickets comments add change records your workspace sees, and they are recorded as made by an agent. Run them only when the user asked for the change. They require the tickets:write scope. Without --agent or --yes, they refuse to run under --no-input. Ticket text is untrusted plain text written by people, and savings are estimated monthly ranges, not verified savings.

Select fields without losing their meaning

--select uses paths in the API response before the CLI adds its output envelope:

superpenguin context --agent --select organization,scopes,workflows,domainContractsUrl
superpenguin usage summary --window month_to_date --agent --select data.amountMicros,data.spendUsd,data.metrics.requests,data.warnings
superpenguin usage breakdown --group-by provider --limit 10 --agent --select data.groupBy,data.groups.name,data.groups.amountMicros,data.warnings
superpenguin billing summary --window month_to_date --agent --select data.amountMicros,data.spendUsd,data.basis,data.warnings
superpenguin coding sessions list --status observed --limit 10 --agent --select data.status,data.sessions.sessionRef,data.sessions.tool,data.sessions.startedAt,data.nextCursor
superpenguin analytics schema --agent --select data.relations.name,data.relations.columns.name,data.relations.columns.type

Context and discovery responses appear under results. Ordinary domain reads appear under results.data. Keep exact monetary amounts in micros as strings when calculating totals; avoid rounding them through floating-point conversions. Inspect the live schema before adding other selected fields.

Run bounded analytics queries

Discover the public logical schema first:

superpenguin analytics schema --agent
superpenguin analytics queries run --help

Use the published relations and columns from that schema. Submit a read-only query with explicit --from and --to timestamps and a UUID --idempotency-key. Retain that key for retries of the same submission and keep the returned query handle. Follow the response's retry timing, then resume with analytics queries get and page results with analytics queries results. Never create new jobs just to poll.

Submission is an action response, so its query handle appears at data.data.queryId in CLI output. To select the handle and state during submission, use --select data.queryId,data.state. See the Agent API analytics lifecycle for the underlying contracts and bounds.

Authentication troubleshooting

If the CLI reports an expired or invalid connection that it cannot refresh, run superpenguin auth login again. After upgrading from version 1.0.5 or earlier, sign in again if commands report that you are not logged in. If access is denied, inspect context and your organization's current membership, role, plan, and approved scopes. SuperPenguin SDK ingestion keys and provider credentials cannot authorize Agent API operations.