112 lines
2.9 KiB
Markdown
112 lines
2.9 KiB
Markdown
---
|
|
name: portainer
|
|
description: Interact with Portainer stacks via API key authentication. Use for any Portainer stack operations including: listing stacks, resolving stack/endpoint IDs, getting stack status, starting/stopping/restarting stacks, retrieving env vars and compose files, and updating stacks with new compose content. All stack commands accept names and resolve IDs automatically.
|
|
---
|
|
|
|
# Portainer Skill
|
|
|
|
Manage Portainer stacks via API. All stack commands accept names and resolve IDs automatically.
|
|
|
|
## Required auth config
|
|
|
|
`workspace .clawdbot/credentials/portainer/config.json (preferred) or ~/.clawdbot/credentials/portainer/config.json`
|
|
|
|
```json
|
|
{
|
|
"base_url": "https://portainer.example.com",
|
|
"api_key": "YOUR_PORTAINER_API_KEY"
|
|
}
|
|
```
|
|
|
|
## Commands
|
|
|
|
### Resolve stack ID
|
|
|
|
```bash
|
|
bash scripts/get-stack-id.sh "<stack-name>"
|
|
```
|
|
Prints only the stack ID. Exits non-zero if not found.
|
|
|
|
### Resolve endpoint ID
|
|
|
|
```bash
|
|
bash scripts/get-endpoint-id.sh "<endpoint-name>"
|
|
```
|
|
Prints only the endpoint (environment) ID.
|
|
|
|
### List all stacks
|
|
|
|
```bash
|
|
bash scripts/list-stacks.sh
|
|
```
|
|
Outputs: `ID Name Status` (tab-aligned).
|
|
|
|
### Get stack status
|
|
|
|
```bash
|
|
bash scripts/get-stack-status.sh "<stack-name>"
|
|
```
|
|
Returns JSON with: Id, Name, Status, Type, EndpointId, CreationDate, UpdatedDate.
|
|
|
|
### Restart stack
|
|
|
|
```bash
|
|
bash scripts/restart-stack.sh "<stack-name>"
|
|
```
|
|
|
|
### Stop stack
|
|
|
|
```bash
|
|
bash scripts/stop-stack.sh "<stack-name>"
|
|
```
|
|
|
|
### Start stack
|
|
|
|
```bash
|
|
bash scripts/start-stack.sh "<stack-name>"
|
|
```
|
|
|
|
### Get stack env vars
|
|
|
|
```bash
|
|
bash scripts/get-stack-env.sh "<stack-name>"
|
|
```
|
|
Returns JSON array of `{name, value}` objects.
|
|
|
|
### Get stack compose file
|
|
|
|
```bash
|
|
bash scripts/get-stack-compose.sh "<stack-name>"
|
|
```
|
|
Returns the raw docker-compose.yml content.
|
|
|
|
### Update stack
|
|
|
|
```bash
|
|
bash scripts/update-stack.sh "<stack-name>" "<compose-file>" [--env-file "<env-file>"] [--prune-old]
|
|
```
|
|
Updates a stack with a new compose file. Preserves existing env vars unless `--env-file` is provided.
|
|
|
|
Options:
|
|
- `--pull` — Force pull images and redeploy (like `docker compose down/pull/up`). Note: may return 504 timeout for large images, but operation completes in background.
|
|
|
|
### Prune stack images
|
|
|
|
```bash
|
|
bash scripts/prune-stack-images.sh "<stack-name>"
|
|
```
|
|
Removes dangling images on the endpoint. Run this after `update-stack --pull` completes to clean up old image versions.
|
|
|
|
**Typical workflow:**
|
|
```bash
|
|
bash scripts/update-stack.sh "stack-name" "compose.yml" --pull
|
|
# wait for update to complete (even if 504 timeout)
|
|
bash scripts/prune-stack-images.sh "stack-name"
|
|
```
|
|
|
|
## Notes
|
|
|
|
- All `*-stack.sh` commands resolve the stack ID internally from the name.
|
|
- Endpoint ID is fetched automatically from stack info for lifecycle and update operations.
|
|
- `update-stack.sh` is the primary command for deploying new versions — it will trigger Portainer to pull new images if the compose file references updated image tags.
|