> For the complete documentation index, see [llms.txt](https://docs.perfectscale.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.perfectscale.io/product-overview/perfectscale-agent-skill.md).

# PerfectScale agent skill

## 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
* Export to CSV, JSON, or JSONL for downstream 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

{% stepper %}
{% step %}
**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:

{% embed url="<https://github.com/doitintl/perfectscale-cli>" %}
{% endstep %}

{% step %}
**Generate an API Token**

1. Open [app.perfectscale.io](app.perfectscale.iohttps://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`
   {% endstep %}

{% step %}
**Authenticate**

```bash
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.
{% endstep %}

{% step %}
**Start Querying**

```bash
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
```

{% endstep %}
{% endstepper %}

{% hint style="warning" %}
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 and many workload filters are client-side
* There is no first-class public nodegroup command
* CSV is the only export format
  {% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.perfectscale.io/product-overview/perfectscale-agent-skill.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.