Metadata-Version: 2.4
Name: ptctools
Version: 0.1.1
Summary: Portainer Client Tools - CLI for managing Portainer from client
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: docker==7.1.0
Requires-Dist: pydantic>=2.12.5
Requires-Dist: python-dateutil>=2.9.0.post0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# ptctools - Portainer Client Tools

CLI for managing Portainer stacks, volume backups, and database operations.

> **Note:** Only tested on Portainer 2.33.6

## Installation

```bash
# From Git repository
uv tool install git+https://github.com/tamntlib/ptctools.git
# or
uv tool install ptctools --from git+https://github.com/tamntlib/ptctools.git

# From local path
uv tool install openapi-generator-cli==7.19.0
openapi-generator-cli generate \
  -i portainer_openapi.yml \
  -g python \
  -o ./src/ptctools/portainer_client \
  --skip-validate-spec \
  --additional-properties=generateSourceCodeOnly=true
uv tool install . --no-cache --reinstall
```

## Usage

```bash
export PORTAINER_URL=https://portainer.example.com
export PORTAINER_ACCESS_TOKEN=your-api-key
export S3_ACCESS_KEY=your-s3-key
export S3_SECRET_KEY=your-s3-secret
export S3_ENDPOINT=https://s3.<region>.amazonaws.com

# Stack deployment
ptctools stack deploy -u $PORTAINER_URL -n mystack -f compose.yaml

# Volume backup/restore (uses Duplicati)
ptctools volume backup -u $PORTAINER_URL -v vol1,vol2 -o s3://mybucket
ptctools volume restore -u $PORTAINER_URL -i s3://mybucket/vol1  # volume name derived from URI path
ptctools volume restore -u $PORTAINER_URL -v vol1 -i s3://mybucket/vol1  # explicit volume name

# Volume copy (raw copy using mc/busybox)
ptctools volume cp -u $PORTAINER_URL source dest                         # volume to volume
ptctools volume cp -u $PORTAINER_URL s3://mybucket/path dest              # S3 to volume
ptctools volume cp -u $PORTAINER_URL source s3://mybucket/path            # volume to S3

# Volume management
ptctools volume rm -u $PORTAINER_URL myvolume                             # remove volume (with confirmation)
ptctools volume rm -u $PORTAINER_URL -y myvolume                          # remove without confirmation
ptctools volume rename -u $PORTAINER_URL old_name new_name                # rename volume (copy + delete)

# Database backup/restore (uses minio/mc for S3)
ptctools db backup -u $PORTAINER_URL -c container_id -v db_data \
  --db-user postgres --db-name mydb -o backup.sql.gz
ptctools db backup -u $PORTAINER_URL -c container_id -v db_data \
  --db-user postgres --db-name mydb -o s3://mybucket/backups/db.sql.gz

ptctools db restore -u $PORTAINER_URL -c container_id -v db_data \
  --db-user postgres --db-name mydb -i backup.sql.gz
ptctools db restore -u $PORTAINER_URL -c container_id -v db_data \
  --db-user postgres --db-name mydb -i s3://mybucket/backups/db.sql.gz

# Config management
# Create config from inline data
ptctools config set -u $PORTAINER_URL -n my-config -d "config content"
ptctools config set -u $PORTAINER_URL -n nginx.conf -f ./nginx.conf
ptctools config set -u $PORTAINER_URL -n my-config -d "new content" --force
ptctools config list -u $PORTAINER_URL
ptctools config get -u $PORTAINER_URL -n my-config
ptctools config delete -u $PORTAINER_URL -n my-config

# Utils - local Duplicati operations
ptctools utils backup --input ./data --output s3://backups/mydata
ptctools utils restore --input s3://backups/mydata --output ./restored

```

## Environment Variables

- `PORTAINER_ACCESS_TOKEN` - Portainer API key (required)
- `S3_ACCESS_KEY` / `S3_SECRET_KEY` - S3 credentials (for backup commands)
- `S3_ENDPOINT` - S3/MinIO endpoint URL
- `DUPLICATI_PASSPHRASE` - Backup encryption passphrase (optional, for volume backups)

## Commands

### `ptctools stack deploy`
Deploy or update a Docker stack in Portainer.

### `ptctools volume backup/restore`

- **backup**: Backup multiple Docker volumes (comma-separated) to S3 using Duplicati container.
- **restore**: Restore a single Docker volume from S3. Volume name can be specified via `--volume` or derived from the input URI path.

### `ptctools volume cp`
Copy data between volumes and S3 (raw file copy).
- **volume to volume**: Uses `busybox` with `cp -a`
- **S3 to volume**: Uses `minio/mc` to download files
- **volume to S3**: Uses `minio/mc` to upload files

### `ptctools volume rm`
Remove a Docker volume. Use `-y` to skip confirmation, `-f` to force removal.

### `ptctools volume rename`
Rename a volume by copying data to a new volume and deleting the original.

### `ptctools db backup/restore`
Backup/restore PostgreSQL database. Supports both local files and S3 URIs.
- Uses `pg_dump`/`psql` for database operations
- Uses `minio/mc` container for S3 transfers

### `ptctools utils backup/restore`
Local backup/restore operations using Duplicati CLI (docker or local).

### `ptctools config set/get/list/delete`
Manage Docker Swarm configs via Portainer API.
