PerfectScale agent skill — SaaS

What is PerfectScale CLI

PerfectScale CLI is a command-line tool that uses PerfectScale’s public APIs to access cluster cost and optimization data. It lets you work with AI agents such as Claude, Codex, and Antigravity to query clusters, workloads, namespaces, costs, waste, risks, and other metrics, and combine this data with information from other sources to get a more complete operational context.

When to use

PerfectScale CLI introduces various use cases to improve your optimization workflows:

• Query clusters, workloads, namespaces, costs, waste, and risks from the command line
• Aggregate and rank data, group by namespace, team label, workload type, risk
  severity
• Access InfraFit node group utilization, costs, and optimization recommendations, and investigate unevictable pods and their remediation guidance
• Export workload data to CSV for reporting and downstream analysis
• Return list, summary, and grouped results as JSON or JSONL for programmatic consumption
• Review automation audit logs with filtering by cluster, namespace, and time range
• Pipe results into any workflow: dashboards, Slack bots, CI/CD pipelines, custom
  reports

Getting started

Step 1

Download the skill

Use your Agent to install PerfectScale CLI skill with a single prompt:

Install the skill from https://github.com/doitintl/perfectscale-cli

Alternatively, you can do it manually. Download and install the latest release for your platform from:

Related resource

Step 2

Generate an API Token

1. Open app.perfectscale.io
2. Click the user icon in the bottom-left corner
3. Go to Org Settings -> API Tokens
4. Click Generate Token and assign a Read Only role
5. Copy the client_id and client_secret

Step 3

Authenticate

pscli auth login --client-id 'YOUR_CLIENT_ID' --client-secret 'YOUR_CLIENT_SECRET' 

The CLI validates the token and saves a local profile. Credentials are stored securely in your OS config directory with restricted file permissions.

Step 4

Start Querying

pscli clusters list # List your clusters
pscli workloads list -c prod-a -s waste -r desc -T 10 # Top 10 wasteful workloads
pscli workloads summary -c prod-a # Cost summary for a cluster
pscli workloads export -c prod-a -F workloads.csv # Export to CSV

注意

Known limitations

• Only service-token auth is supported
• Only the public API is supported
• Workloads are fixed to a 30d period because the public endpoint is fixed-window
• --namespace, --name, --type, --min-cost, --min-waste filters are client-side
• CSV is the only workload export format
• Audit logs are available for the last 30 days and use cursor-based pagination

What is PerfectScale CLI

PerfectScale CLI is a command-line tool that uses PerfectScale’s public APIs to access cluster cost and optimization data. It lets you work with AI agents such as Claude, Codex, and Antigravity to query clusters, workloads, namespaces, costs, waste, risks, and other metrics, and combine this data with information from other sources to get a more complete operational context.

When to use

PerfectScale CLI introduces various use cases to improve your optimization workflows:

• Query clusters, workloads, namespaces, costs, waste, and risks from the command line
• Aggregate and rank data, group by namespace, team label, workload type, risk
  severity
• Access InfraFit node group utilization, costs, and optimization recommendations, and investigate unevictable pods and their remediation guidance
• Export workload data to CSV for reporting and downstream analysis
• Return list, summary, and grouped results as JSON or JSONL for programmatic consumption
• Review automation audit logs with filtering by cluster, namespace, and time range
• Pipe results into any workflow: dashboards, Slack bots, CI/CD pipelines, custom
  reports

Getting started

Step 1

Installing PerfectScale CLI

Install the PerfectScale CLI using the option for your platform:

• macOS/Linux (Homebrew):

  brew install doitintl/tap/pscli

• Windows (Scoop):

  scoop bucket add pscli https://github.com/doitintl/perfectscale-cli
  scoop install pscli

• Linux (.deb/.rpm): Download the package for your architecture and install it with dpkg -i or rpm -Uvh.

Related resource

• Other platforms: Download the release archive and extract the pscli binary onto your PATH.

情報

Run pscli update to check for a newer version. It prints the appropriate upgrade command for your installation method.

Step 2

Generate an API Token

1. Open app.perfectscale.io
2. Click the user icon in the bottom-left corner
3. Go to Org Settings -> API Tokens
4. Click Generate Token and assign a Read Only role
5. Copy the client_id and client_secret

Step 3

Authenticate

pscli auth login --client-id 'YOUR_CLIENT_ID' --client-secret 'YOUR_CLIENT_SECRET' 

The CLI validates the token and saves a local profile. Credentials are stored securely in your OS config directory with restricted file permissions.

Step 4

Installing the Agent skill (optional)

This skill ships with the CLI binary, so there’s no separate download needed. Use --all to install it for every agent whose config directory already exists.

pscli skill claude
pscli skill --all

Step 5

Start Querying

pscli clusters list # List your clusters
pscli workloads list -c prod-a -s waste -r desc -T 10 # Top 10 wasteful workloads
pscli workloads summary -c prod-a # Cost summary for a cluster
pscli workloads export -c prod-a -F workloads.csv # Export to CSV
pscli automation audit-logs -c prod-a --since 24h # Return recent automation actions
pscli open workload -c prod-a -m my-deployment # Open the specific workload's page in the browser

注意

Known limitations

• Only service-token auth is supported
• Only the public API is supported
• Workloads are fixed to a 30d period because the public endpoint is fixed-window
• namespace, name, type, min-cost, min-waste filters are client-side
• CSV is the only workload export format
• Audit logs are available for the last 30 days and use cursor-based pagination