bootstrap/tools/portainer/README.md

Portainer CLI Scripts

CLI tools for managing Portainer stacks via the API.

Setup

Environment Variables

Set these environment variables before using the scripts:

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.

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

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

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

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

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

stack-stop.sh

Stop a running stack.

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

endpoint-list.sh

List all Portainer endpoints/environments.

# 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:

# 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

# 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

# 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
• Portainer API Examples
• Portainer API Docs