nexus3-go

README

nexus3-go

UNOFFICIAL Go client and CLI for Sonatype Nexus Repository Manager 3, built on the community-generated OpenAPI client.

Overview

nexus3-go has two independent parts:

• pkg/nexus3 — a small library wrapping the community-generated OpenAPI client github.com/sonatype-nexus-community/nexus-repo-api-client-go for use from Go programs. It configures the client, injects basic auth per request, and exposes a handful of convenience methods (ListRepositories, SearchComponents, Status, ...) plus an escape hatch to the full generated client for anything else.

• cmd/nexus3-go — a CLI with total command coverage of a Nexus instance's REST API, built by embedding Restish (github.com/rest-sh/restish). Restish discovers the live OpenAPI document a Nexus server publishes at /service/rest/swagger.json and generates one CLI command per operation — the full ~950-endpoint surface (repositories, components, assets, search, blobstores, security, tasks, staging, cleanup policies, and more), always in sync with whatever version that specific server actually runs, with no code generation or vendoring on our side.

Installation

Library:

go get github.com/M0Rf30/nexus3-go

CLI:

go install github.com/M0Rf30/nexus3-go/cmd/nexus3-go@latest

Library usage

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/M0Rf30/nexus3-go/pkg/nexus3"
)

func main() {
	client := nexus3.New("http://localhost:8081",
		nexus3.WithBasicAuth("admin", "admin123"))

	repos, err := client.ListRepositories(context.Background())
	if err != nil {
		log.Fatal(err)
	}

	for _, repo := range repos {
		fmt.Println(repo.Name)
	}
}

Only a handful of convenience methods are wrapped (ListRepositories, SearchComponents/ListComponents, Status). For anything else — blob stores, security, tasks, staging, cleanup policies, and the rest of Nexus's ~950-endpoint REST surface — drop down to the generated client directly via Client.API(), authenticating each call with Client.AuthContext(ctx):

api := client.API()
ctx := client.AuthContext(context.Background())

task, _, err := api.TasksAPI.GetTaskById(ctx, taskID).Execute()

CLI usage

Connect once per Nexus instance (credentials and the discovered command set are persisted under Restish's config directory):

nexus3-go api connect nexus http://localhost:8081 \
    --spec http://localhost:8081/service/rest/swagger.json

You'll be prompted for the Basic Auth username/password Nexus requires (or pass them inline, e.g. prompt.credentials.BasicAuth.username:admin). Then every discovered operation is available as a subcommand under the profile name you chose (nexus above):

nexus3-go nexus --help
nexus3-go nexus get-all-repositories
nexus3-go nexus create-maven-hosted-repository 'name: releases, ...'
nexus3-go nexus get-all-repositories --help   # full flag/schema/example docs

See the Restish docs for output formatting (-o table, -f shorthand filters), pagination, and profile management — all of it applies unchanged since nexus3-go is a thin, Nexus-named build of the stock Restish CLI.

Uploading components

Nexus's own OpenAPI/swagger.json declares no request body for the component upload endpoint (POST /v1/components), so Restish can never generate flags for it — the CLI's generic nexus3-go nexus ... command tree cannot reach it. A small hand-written upload command covers it instead, for every hosted format Nexus exposes through that endpoint except docker (which uses the separate Docker Registry HTTP API v2 — plain docker push):

export NEXUS_USERNAME=admin NEXUS_PASSWORD=admin123

nexus3-go upload deb --base-url http://localhost:8081 \
    --repository apt-hosted --file mypkg_1.0_amd64.deb
nexus3-go upload rpm --base-url http://localhost:8081 \
    --repository yum-hosted --file mypkg-1.0.el9.x86_64.rpm
nexus3-go upload raw --base-url http://localhost:8081 \
    --repository raw-hosted --directory docs --file notes.txt
nexus3-go upload maven2 --base-url http://localhost:8081 \
    --repository maven-hosted --file lib.jar \
    --group-id com.example --artifact-id lib --version 1.0
nexus3-go upload npm --base-url http://localhost:8081 \
    --repository npm-hosted --file mypkg-1.0.0.tgz   # also: go, helm, nuget, pypi, rubygems

--base-url also reads from NEXUS_BASE_URL if unset.

Multiple files

--file is repeatable, and trailing positional arguments are treated as files too — mix and match whichever's convenient. Any value containing a glob metacharacter (*, ?, [) is expanded with filepath.Glob; quote it so your shell passes the pattern through to nexus3-go instead of expanding it itself:

nexus3-go upload deb --base-url http://localhost:8081 \
    --repository apt-hosted --file 'dist/*.deb'

nexus3-go upload rpm --base-url http://localhost:8081 \
    --repository yum-hosted \
    --file build/mypkg-1.0.el9.x86_64.rpm --file build/mypkg-1.0.el9.noarch.rpm

For every kind except maven2 (which packs its assets into a single request — see below), each matched file becomes its own upload request, and up to --concurrency (default 4) run in parallel; the flag has no effect on maven2. A failure on one file never aborts the rest: every file is attempted regardless of earlier failures, and if any fail the command exits non-zero after reporting how many succeeded (uploaded N/M) followed by each failing path and its error.

Maven2 multi-asset components

A single Maven2 component can bundle more than one asset — the jar, its POM, a -sources jar — as long as they share one group/artifact/version and go up together in one POST /v1/components request. Nexus's API caps that request at three assets (asset1..asset3), which is a limit of the Nexus API itself, not of this CLI — so --asset may be repeated at most three times.

Once you have more than one asset, use the repeatable --asset path[:extension[:classifier]] flag instead of --file:

nexus3-go upload maven2 --base-url http://localhost:8081 \
    --repository maven-hosted \
    --group-id com.example --artifact-id lib --version 1.0 \
    --asset lib.jar \
    --asset lib.pom:pom \
    --asset lib-sources.jar:jar:sources

Extension and classifier travel inside each --asset value rather than as separate, index-aligned --extension/--classifier list flags: with parallel arrays, a dropped or reordered entry silently attaches the wrong metadata to the wrong file, and nothing catches it. Keeping path:extension:classifier together as one token makes that class of bug structurally impossible — there is no index to misalign.

--extension and --classifier still exist as plain scalar strings, but only apply to the single-asset --file form above. --file and --asset are mutually exclusive for maven2 — combining them is an error.

Docker

Multi-arch (linux/amd64, linux/arm64) images are published to GHCR on every tagged release:

docker run --rm ghcr.io/m0rf30/nexus3-go:latest --help

Pin to a specific version instead of latest for reproducible pulls (e.g. ghcr.io/m0rf30/nexus3-go:0.1.0 — goreleaser tags images with the bare version, without the v prefix used for git tags).

Development

make build   # build ./bin/nexus3-go
make test    # go test -v ./...
make lint    # golangci-lint run

See make help for the full target list.

License

MIT

Disclaimer

This project is not affiliated with, endorsed by, or supported by Sonatype. "Nexus" and "Sonatype" are trademarks of Sonatype, Inc.