# Portainer CLI Scripts

CLI tools for managing Portainer stacks via the API.

## Setup

### Environment Variables

Set these environment variables before using the scripts:

```bash
export PORTAINER_URL="https://portainer.example.com:9443"
export PORTAINER_API_KEY="your-api-key-here"
```

You can add these to your shell profile (`~/.bashrc`, `~/.zshrc`) or use a `.env` file.

### Creating an API Key

1. Log in to Portainer
2. Click your username in the top right corner > "My account"
3. Scroll to "Access tokens" section
4. Click "Add access token"
5. Enter a descriptive name (e.g., "CLI scripts")
6. Copy the token immediately (you cannot view it again)

### Dependencies

- `curl` - HTTP client
- `jq` - JSON processor

Both are typically pre-installed on most Linux distributions.

## Scripts

### stack-list.sh

List all Portainer stacks.

```bash
# List all stacks in table format
stack-list.sh

# List stacks in JSON format
stack-list.sh -f json

# List only stack names
stack-list.sh -f names
stack-list.sh -q

# Filter by endpoint ID
stack-list.sh -e 1
```

### stack-status.sh

Show status and containers for a stack.

```bash
# Show stack status
stack-status.sh -n mystack

# Show status in JSON format
stack-status.sh -n mystack -f json

# Use stack ID instead of name
stack-status.sh -i 5
```

### stack-redeploy.sh

Redeploy a stack. For git-based stacks, this pulls the latest from the repository.

```bash
# Redeploy a stack by name
stack-redeploy.sh -n mystack

# Redeploy and pull latest images
stack-redeploy.sh -n mystack -p

# Redeploy by stack ID
stack-redeploy.sh -i 5 -p
```

### stack-logs.sh

View logs for stack services/containers.

```bash
# List available services in a stack
stack-logs.sh -n mystack

# View logs for a specific service
stack-logs.sh -n mystack -s webapp

# Show last 200 lines
stack-logs.sh -n mystack -s webapp -t 200

# Follow logs (stream)
stack-logs.sh -n mystack -s webapp -f

# Include timestamps
stack-logs.sh -n mystack -s webapp --timestamps
```

### stack-start.sh

Start an inactive stack.

```bash
stack-start.sh -n mystack
stack-start.sh -i 5
```

### stack-stop.sh

Stop a running stack.

```bash
stack-stop.sh -n mystack
stack-stop.sh -i 5
```

### endpoint-list.sh

List all Portainer endpoints/environments.

```bash
# List in table format
endpoint-list.sh

# List in JSON format
endpoint-list.sh -f json
```

## Common Workflows

### CI/CD Redeploy

After pushing changes to a git-based stack's repository:

```bash
# Redeploy with latest images
stack-redeploy.sh -n myapp -p

# Check status
stack-status.sh -n myapp

# View logs to verify startup
stack-logs.sh -n myapp -s api -t 50
```

### Debugging a Failing Stack

```bash
# Check overall status
stack-status.sh -n myapp

# List all services
stack-logs.sh -n myapp

# View logs for failing service
stack-logs.sh -n myapp -s worker -t 200

# Follow logs in real-time
stack-logs.sh -n myapp -s worker -f
```

### Restart a Stack

```bash
# Stop the stack
stack-stop.sh -n myapp

# Start it again
stack-start.sh -n myapp

# Or just redeploy (pulls latest images)
stack-redeploy.sh -n myapp -p
```

## Error Handling

All scripts:
- Exit with code 0 on success
- Exit with code 1 on error
- Print errors to stderr
- Validate required environment variables before making API calls

## API Reference

These scripts use the Portainer CE API. Key endpoints:

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/stacks` | GET | List all stacks |
| `/api/stacks/{id}` | GET | Get stack details |
| `/api/stacks/{id}/file` | GET | Get stack compose file |
| `/api/stacks/{id}` | PUT | Update/redeploy stack |
| `/api/stacks/{id}/git/redeploy` | PUT | Redeploy git-based stack |
| `/api/stacks/{id}/start` | POST | Start inactive stack |
| `/api/stacks/{id}/stop` | POST | Stop running stack |
| `/api/endpoints` | GET | List all environments |
| `/api/endpoints/{id}/docker/containers/json` | GET | List containers |
| `/api/endpoints/{id}/docker/containers/{id}/logs` | GET | Get container logs |

For full API documentation, see:
- [Portainer API Access](https://docs.portainer.io/api/access)
- [Portainer API Examples](https://docs.portainer.io/api/examples)
- [Portainer API Docs](https://docs.portainer.io/api/docs)