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