nexus3-tool 0.5.0

A CLI tool for managing Sonatype Nexus3 via its REST API

nexus3-tool

A command-line tool for managing Sonatype Nexus3 via its REST API, following a familiar docker-style command pattern.

---

Installation

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:

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:

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

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.

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

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

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

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

You can also run any command directly without installing:

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