Skip to main content
skill CX Codex

pier-cloud — Claude Code skill: Pier Cloud cost API, install guide

A skill for calling the Pier Cloud (Lighthouse) API: JWT auth, contexts, workspaces and FinOps view data through ready-made Python scripts.

Apache-2.0 ★ 141 updated 2026-10-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add fabricioctelles/skills --skill pier-cloud -a claude-code
Open on GitHub

What pier-cloud does

The skill hands the agent the layout of Pier Cloud's Lighthouse API for cloud spend. It covers the JWT login at POST /auth, listing contexts, workspaces and workspace groups, and pulling FinOps view data with filters. Requests go to https://api.piercloud.io; a token is good for one hour, so long sessions need a refresh.

Scripts ship in scripts/: auth, workspaces with pagination, a single workspace or view, and view data. pier_cloud_client.py adds retries and token renewal. Endpoint details sit in references/REFERENCE.md, while references/TROUBLESHOOTING.md handles 401 and 404 responses.

Two things have to be in place first. Drop a .env into the skill folder holding PIERCLOUD_CLIENT_ID, PIERCLOUD_CLIENT_SECRET and PIERCLOUD_TENANCY_ID, then run pip install requests python-dotenv. Without that file the skill stops and tells you to get credentials from Pier Cloud. Mind the path too: workspace groups sit under /workspaces-groups.

What it helps with

  • fetch a JWT and renew it before the hour runs out
  • pull every workspace with automatic pagination
  • read FinOps view data with filters applied
  • look up a workspace group by id
  • debug a 401 or 404 coming back from the API

Example prompts for the agent

  • Log in to Pier Cloud and list the contexts I can see
  • Pull all workspaces with the pagination script from the skill
  • Get this workspace's view data, filtered by period

How to install pier-cloud

1Skills CLI (Vercel)

npx skills add fabricioctelles/skills --skill pier-cloud -a claude-code

2Manually: put the files in place

~/.claude/skills/pier-cloud/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/pier-cloud/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about pier-cloud

How do I install pier-cloud in Claude Code?

Run npx skills add fabricioctelles/skills --skill pier-cloud -a claude-code. The skill then sits at ~/.claude/skills/pier-cloud/SKILL.md.

What does pier-cloud do?

It teaches the agent to call the Pier Cloud API: grab a token, list contexts, workspaces and workspace groups, and read FinOps view data. Ready-made scripts cover the common calls.

What does the skill need before it runs?

A .env file in the skill folder with PIERCLOUD_CLIENT_ID, PIERCLOUD_CLIENT_SECRET and PIERCLOUD_TENANCY_ID, plus the requests and python-dotenv packages. It will not continue without the .env.

Source text

SKILL.md · Apache-2.0
---
name: "pier-cloud"
description: "This skill should be used when the user needs to consume the Pier Cloud (Lighthouse) API for cloud cost management — including JWT authentication, listing contexts, workspaces, workspace groups, and FinOps data views. Trigger whenever there is a need to integrate, automate, or debug calls to the Pier Cloud platform via Python, Node.js, or cURL."
metadata:
  author: ft.ia.br
  version: "1.2"
  date: 2026-09-21
  repository: https://github.com/fabricioctelles/skills
  license: Apache 2.0
  keywords: ["pier", "piercloud", "lighthouse", "api", "finops", "cloud", "costs"]
  category: library-and-api-reference
---

# Pier Cloud API

## Prerequisites

### Credentials

Locate the `.env` file in the skill directory with the following variables:

```env
PIERCLOUD_CLIENT_ID=your_client_id
PIERCLOUD_CLIENT_SECRET=your_client_secret
PIERCLOUD_TENANCY_ID=your_tenancy_id
```

If the `.env` file does not exist, inform the user that credentials must be obtained from the Pier Cloud platform before proceeding. Do not proceed without the `.env` file.

> Note: `PIERCLOUD_TENANCY_ID` is equivalent to the former `PIERCLOUD_BUSINESS_ID`. Scripts accept both as fallback.

### Python Dependencies

```bash
pip install requests python-dotenv
```

## Basic Configuration

The API uses JWT authentication. Required flow:

1. Authenticate via `POST /auth` with `client_id` and `client_secret` to obtain a JWT token
2. Include the token in all requests: `Authorization: Bearer {token}`
3. Renew the token upon expiration (default validity: 1 hour)

**Base URL**: `https://api.piercloud.io`

> Workspace groups live at `/lighthouse/tenancies/{tenancy_id}/workspaces-groups` (note the plural *workspaces*).

Verify the connection by running:

```bash
python scripts/pier-cloud-auth.py
```

## Available Scripts

Ready-to-use scripts in `scripts/`. See `scripts/README.md` for detailed instructions.

| Script | Description |
|--------|-------------|
| `pier-cloud-auth.py` | Authenticate and obtain JWT token |
| `pier-cloud-list-contexts.py` | List available contexts |
| `pier-cloud-list-workspaces.py` | List workspaces with pagination |
| `pier-cloud-get-workspace.py` | Get specific workspace details |
| `pier-cloud-get-all-workspaces.py` | Get all workspaces (automatic pagination) |
| `pier-cloud-list-views.py` | List views for a workspace |
| `pier-cloud-get-view.py` | Get specific view information |
| `pier-cloud-get-view-data.py` | Get view data with filters |
| `pier-cloud-list-workspace-groups.py` | List workspace groups (`/workspaces-groups`) |
| `pier-cloud-get-workspace-group.py` | Get workspace group by id |
| `pier_cloud_client.py` | Robust client with CLI and reusable library |

## Workflows

Follow the detailed workflows with request and response examples in `references/REFERENCE.md`:

- **Workflow 1** — Authentication and Token Retrieval
- **Workflow 2** — List Contexts
- **Workflow 3** — List Workspaces
- **Workflow 4** — Get Workspace Details
- **Workflow 5** — Get All Workspaces (Automatic Pagination)
- **Workflow 6** — Robust Client with Retry and Token Renewal
- **Workflow 9** — List Workspace Views
- **Workflow 10** — Get View Information
- **Workflow 11** — Get View Data with Filters
- **Workflow 12** — List Workspace Groups (`/workspaces-groups`)
- **Workflow 13** — Get Workspace Group Details

For endpoint reference, parameters, response structures, and cURL examples, see `references/REFERENCE.md`.

For error diagnosis (401, 403, 404, timeout, rate limiting), see `references/TROUBLESHOOTING.md`.

## Additional Resources

- **API Docs**: https://docs.piercloud.com/api-docs-pier-cloud
- **Public routes (EN)**: https://docs.piercloud.com/api-docs-pier-cloud/api-pier-cloud/public-routes-en-us
- **Pier Cloud Platform**: https://piercloud.com/en/

## Quality Checklist

- [ ] `.env` file present with `PIERCLOUD_CLIENT_ID`, `PIERCLOUD_CLIENT_SECRET`, and `PIERCLOUD_TENANCY_ID`
- [ ] Python dependencies installed (`requests`, `python-dotenv`)
- [ ] Authentication successful (JWT token obtained without errors)
- [ ] Correct endpoint being used (`/lighthouse/tenancies/{tenancy_id}/...`; groups → `workspaces-groups`)
- [ ] Token being renewed before expiration in long sessions
- [ ] Workspace/view IDs confirmed via listing before using directly
- [ ] Errors handled per `references/TROUBLESHOOTING.md`

© ft.ia.br · Apache-2.0 · fabricioctelles/skills

Similar skills

All skills for Cloud: AWS, Azure, GCP →

From the same set46

The whole set →
agent-ready-ard The agent-ready-ard skill guides you through publishing /.well-known/ai-catalog.json so agents can discover MCP servers, A2A agents, skills, and API tools. Use it to add resource discovery to a project. CX Codex +1 ★ 141repo stars agent-ready-scan-site agent-ready-scan-site scans a website and validates compliance with AI agent standards. Evaluates 23 checks across five categories: discoverability, content accessibility, bot rules, API/auth discovery, and commerce. CX Codex +1 ★ 141repo stars ultimate-design-system-master ultimate-design-system-master guides users through an 18-step briefing questionnaire to produce design systems, brand assets, and UI code across 10 specialized generators. CX Codex +1 ★ 141repo stars substack-expert substack-expert — a skill for shaping Substack newsletters, from post structure and SEO fields to reader engagement and free-to-paid conversion. CX Codex +1 ★ 141repo stars geo-optimization geo-optimization optimizes site content for LLM citations and answer engines like ChatGPT, Perplexity, Claude, and Google AI Overview. CX Codex +1 ★ 141repo stars human-ai human-ai reworks English prose to remove canned AI wording and stiff structure while keeping the source facts, meaning, and authorial voice. CX Codex +1 ★ 141repo stars design-md-validator design-md-validator is a Claude Code skill that checks DESIGN.md against Google's specification with the @google/design.md CLI linter. It flags broken token references and computes WCAG contrast ratios. CX Codex +1 ★ 141repo stars humanizar humanizar is a Claude Code skill that drafts and edits Brazilian Portuguese text with natural cadence while preserving the author's facts and voice. CX Codex +1 ★ 141repo stars

Project sponsors

Companies that keep this analytics open