> 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

Explore how to bring agentic workflows into your Kubernetes optimization process with the 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
* 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

{% stepper %}
{% step %}
**Download the skill**

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

{% code collapsedlinecount="10" %}

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

{% endcode %}

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](https://app.perfectscale.io/)
2. In the left navigation, click **More**, then **Settings**
3. Open the **API Tokens** tab and click **Create Token**
4. Enter a name, select the **Read Only** role and click **Create**
5. Copy the **Token ID** and the **Token Secret**. They are the `client_id` and `client_secret` used in the next step. The secret is shown only once.

For roles, expiration and deleting tokens, see [API and cluster tokens](https://docs.perfectscale.io/administration/api-and-cluster-tokens.md).
{% endstep %}

{% step %}
**Authenticate**

{% code collapsedlinecount="10" %}

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

{% endcode %}

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**

{% code collapsedlinecount="10" %}

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

{% endcode %}
{% 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`, `--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
  {% endhint %}

## 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

{% stepper %}
{% step %}
**Installing PerfectScale CLI**

Install the PerfectScale CLI using the option for your platform:

* **macOS/Linux (Homebrew):**

  <pre class="language-bash" data-collapsed-line-count="10"><code class="lang-bash">brew install doitintl/tap/pscli
  </code></pre>
* **Windows (Scoop):**

  <pre class="language-bash" data-collapsed-line-count="10"><code class="lang-bash">scoop bucket add pscli https://github.com/doitintl/perfectscale-cli
  scoop install pscli
  </code></pre>
* **Linux (.deb/.rpm):** Download the package for your architecture and install it with `dpkg -i` or `rpm -Uvh`.

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

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

{% hint style="info" %}
Run `pscli update` to check for a newer version. It prints the appropriate upgrade command for your installation method.
{% endhint %}
{% endstep %}

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

1. Open [app.perfectscale.io](https://app.perfectscale.io/)
2. In the left navigation, click **More**, then **Settings**
3. Open the **API Tokens** tab and click **Create Token**
4. Enter a name, select the **Read Only** role and click **Create**
5. Copy the **Token ID** and the **Token Secret**. They are the `client_id` and `client_secret` used in the next step. The secret is shown only once.

For roles, expiration and deleting tokens, see [API and cluster tokens](https://docs.perfectscale.io/administration/api-and-cluster-tokens.md).
{% endstep %}

{% step %}
**Authenticate**

{% code collapsedlinecount="10" %}

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

{% endcode %}

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 %}
**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.

{% code collapsedlinecount="10" %}

```bash
pscli skill claude
pscli skill --all
```

{% endcode %}
{% endstep %}

{% step %}
**Start Querying**

{% code collapsedlinecount="10" %}

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

```

{% endcode %}
{% 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`, `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
  {% endhint %}
