glpkg-cli 0.1.1

A CLI tool for uploading files to GitLab's Generic Package Registry

glpkg

A CLI tool for uploading files to GitLab's Generic Package Registry.

Installation

From PyPI (Recommended)

# Using uv (recommended)
uv pip install glpkg-cli

# Or using pip
pip install glpkg-cli

After installation, the glpkg command is available in your PATH:

# Verify installation
glpkg --version

# View available commands
glpkg --help

Universal Binary (.pyz)

Download the pre-built universal binary from GitHub releases. This is a self-contained executable that requires no installation - just Python 3.11+.

# Download the latest release
curl -L -o glpkg.pyz \
  https://github.com/your-org/glpkg/releases/latest/download/glpkg.pyz

# Make it executable
chmod +x glpkg.pyz

# Run directly
./glpkg.pyz --help

# Or run with Python
python glpkg.pyz --help

Optionally, install the binary to a location in your PATH for easier access:

# Install to ~/.local/bin (user-local)
mv glpkg.pyz ~/.local/bin/glpkg
chmod +x ~/.local/bin/glpkg

# Or install system-wide (requires sudo)
sudo mv glpkg.pyz /usr/local/bin/glpkg
sudo chmod +x /usr/local/bin/glpkg

# Now use it like a regular command
glpkg --help

Development Installation

# Clone the repository
git clone https://github.com/your-org/glpkg.git
cd glpkg

# Install in development mode with uv
uv pip install -e .

# Or run directly without installing
uv run glpkg --help

Usage

# Upload a single file
glpkg upload --package-name my-package --package-version 1.0.0 \
  --files file.tar.gz

# Upload multiple files
glpkg upload --package-name my-package --package-version 1.0.0 \
  --files file1.tar.gz file2.zip

# Upload with automatic project detection from git remote
glpkg upload --package-name my-package --package-version 1.0.0 \
  --files file.tar.gz

# Specify project explicitly
glpkg upload --package-name my-package --package-version 1.0.0 \
    --project-path namespace/project --files file.tar.gz

# Handle duplicates (skip, replace, or error)
glpkg upload --package-name my-package --package-version 1.0.0 \
    --duplicate-policy replace --files file.tar.gz

# Verbose output with global flags
glpkg --verbose upload --package-name my-package \
  --package-version 1.0.0 --files file.tar.gz

# JSON output for CI/CD pipelines
glpkg --json-output upload --package-name my-package \
  --package-version 1.0.0 --files file.tar.gz

Configuration

Environment Variables

Variable	Description	Required
GITLAB_TOKEN	GitLab access token with api scope	Yes
GITLAB_URL	GitLab URL (default: gitlab.com)	No
GITLAB_PROJECT_PATH	Project path (e.g., group/project)	No

Token Permissions

Your GitLab token requires:

• api scope for full API access
• Write access to the target project's Package Registry

Development

For detailed contribution guidelines, see CONTRIBUTING.md.

Quick Start

# Clone and install dependencies
git clone https://github.com/your-org/glpkg.git
cd glpkg
uv sync --all-extras

# Install pre-commit hooks
uv run pre-commit install

# Run tests
uv run pytest tests/unit/

Documentation

• CONTRIBUTING.md - Development setup and guidelines
• docs/SHELL_COMPLETION.md - Shell completion
• docs/RELEASING.md - Release procedures
• docs/WORKFLOWS.md - GitHub Actions workflows
• tests/README.md - Detailed testing documentation

Project Structure

glpkg/
├── src/
│   └── glpkg/
│       ├── __init__.py
│       ├── cli/
│       │   ├── __init__.py
│       │   ├── main.py         # Main CLI entry point
│       │   └── upload.py       # Upload subcommand implementation
│       ├── models.py           # Data models
│       ├── uploader.py         # Upload logic
│       ├── formatters.py       # Output formatting
│       ├── duplicate_detector.py  # Duplicate detection
│       └── validators.py       # Input validation
├── tests/
│   ├── unit/                   # Unit tests
│   ├── integration/            # Integration tests
│   └── utils/                  # Test utilities
├── pyproject.toml              # Project configuration
└── README.md                   # This file

License

MIT License