| 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, 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.1","date":"2026-03-05T00:00:00.000Z","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:
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
pip install requests python-dotenv
Basic Configuration
The API uses JWT authentication. Required flow:
- Authenticate via
POST /auth with client_id and client_secret to obtain a JWT token
- Include the token in all requests:
Authorization: Bearer {token}
- Renew the token upon expiration (default validity: 1 hour)
Base URL: https://api.piercloud.io
Verify the connection by running:
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_client.py | Robust client with CLI and reusable library |
Note: Workspace-groups scripts (pier-cloud-list-workspace-groups.py, pier-cloud-get-workspace-group.py) do not work — the corresponding endpoints do not exist in the current API.
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
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
Quality Checklist
