Metadata-Version: 2.4
Name: nexus3-tool
Version: 0.5.0
Summary: A CLI tool for managing Sonatype Nexus3 via its REST API
Author: tkdpython
License: MIT
Project-URL: Homepage, https://github.com/tkdpython/nexus3-tool
Project-URL: Repository, https://github.com/tkdpython/nexus3-tool
Project-URL: Issues, https://github.com/tkdpython/nexus3-tool/issues
Keywords: nexus3,sonatype,cli,devops,docker,repository-management
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: requests>=2.18
Dynamic: license-file

# nexus3-tool

[![PyPI version](https://img.shields.io/pypi/v/nexus3-tool)](https://pypi.org/project/nexus3-tool/)
[![Python Versions](https://img.shields.io/pypi/pyversions/nexus3-tool)](https://pypi.org/project/nexus3-tool/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Publish to PyPI](https://github.com/tkdpython/nexus3-tool/actions/workflows/publish.yml/badge.svg)](https://github.com/tkdpython/nexus3-tool/actions/workflows/publish.yml)

A command-line tool for managing [Sonatype Nexus3](https://www.sonatype.com/products/sonatype-nexus-repository) via its REST API, following a familiar docker-style command pattern.

---

## Installation

```bash
pip install nexus3-tool
```

---

## Usage

```
nexus3-tool [OPTIONS] COMMAND [ARGS]...

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  login                 Authenticate with a Nexus3 instance.
  list-docker-repos     List all Docker repositories.
  list-docker-images    List images and tags in a Docker repository, including size usage.
  delete-docker-images  Delete selected Docker image tags.
  prune-docker-images   Prune old tags from a Docker image.
```

---

### login

Authenticate with your Nexus3 instance. Credentials (including SSL preference) are stored in `~/.nexus-credentials` and reused by all subsequent commands.

**Interactive (default) — prompts for username and password:**
```bash
nexus3-tool login https://nexus.example.com
```

If the server uses an internal or self-signed certificate, the tool will detect the SSL failure and prompt you to disable verification — no flags required.

**Non-interactive — for use in CI/CD pipelines:**
```bash
nexus3-tool login https://nexus.example.com --username admin --password secret

# With an internal/self-signed certificate:
nexus3-tool login https://nexus.example.com --username admin --password secret --ignore-untrusted-certs
```

---

### list-docker-repos

List all Docker-format repositories and their type (`hosted`, `proxy`, `group`).

```bash
nexus3-tool list-docker-repos
```

---

### list-docker-images

List images and tags in a repository, with their publish date and the disk space used by each tag. The command also prints a summary of the total disk space used by all matched tags, deduplicating shared blob assets where Nexus exposes stable asset identifiers/checksums, and when Nexus exposes the information to your user, the available space on the backing blob store.

```bash
# List all images in a repo
nexus3-tool list-docker-images development

# Filter to a specific image (faster — server-side filtering)
nexus3-tool list-docker-images development --image-name myapp

# Match image names with shell-style wildcards (* and ?)
nexus3-tool list-docker-images development --image-name 'team-a/*'
nexus3-tool list-docker-images development --image-name 'service-?'
```

> **Note:** available space is reported for the Nexus blob store that backs the repository, not for an individual Docker repository. Some Nexus users may not have permission to read blob store quota details; in that case the command still shows matched image usage and reports available space as `unknown`.

---

### delete-docker-images

Delete specific tags from a Docker image. `--tags` accepts a comma-separated list. Before deletion, the tool shows every selected tag, including any other tags on the same image that point at the same manifest digest as a requested tag.

```bash
# Prompt before deleting the requested tag(s) and matching aliases
nexus3-tool delete-docker-images development --image-name myapp --tags old,dev-123

# Non-interactive delete
nexus3-tool delete-docker-images development --image-name myapp --tags old,dev-123 --quiet
```

After successful deletes, the command reports the disk usage represented by the successfully deleted tag components and the remaining blob-store space when Nexus exposes that information to your user.

> **Note:** Nexus may not physically reclaim disk immediately after component deletion. An administrator may still need to run the *"Delete unused manifest and unreferenced blobs"* and *"Compact blob store"* tasks.

---

### prune-docker-images

Remove old tags from a Docker image, keeping the most recent. The `latest` tag is always preserved and is not counted against `--keep-last`.

```bash
# Preview what would be deleted (no changes made)
nexus3-tool prune-docker-images production --image-name myapp --dry-run

# Keep the 5 most recent tags (default), prompt for confirmation
nexus3-tool prune-docker-images production --image-name myapp --keep-last 5

# Keep the 10 most recent tags, skip confirmation prompt
nexus3-tool prune-docker-images production --image-name myapp --keep-last 10 --yes

# Short flag equivalent
nexus3-tool prune-docker-images production --image-name myapp --keep-last 10 -y
```

Tags are sorted by last-modified date. If `latest` is an alias for a versioned tag, both are annotated in the output so you can see exactly what is being kept.

> **Note:** Deleting tags removes the component from Nexus, but physical disk space is only reclaimed when a Nexus admin runs the *"Delete unused manifest and unreferenced blobs"* and *"Compact blob store"* tasks.

---

## Development

Clone the repository and install in editable mode:

```bash
git clone https://github.com/tkdpython/nexus3-tool.git
cd nexus3-tool
pip install -e .
```

You can also run any command directly without installing:

```bash
python3 -m nexus3_tool login https://nexus.example.com
python3 -m nexus3_tool list-docker-repos
python3 -m nexus3_tool list-docker-images development --image-name myapp
python3 -m nexus3_tool prune-docker-images production --image-name myapp --dry-run
```

---


## License

MIT © [tkdpython](https://github.com/tkdpython)

