Use the SuperPenguin CLI

The SuperPenguin CLI gives you and your terminal-based AI agent typed commands for your organization's AI spend, provider billing, and coding usage. 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 --native

Native 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 --native 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 --q "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 --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.

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 --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 --native again. 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.