Admin Registry CLI Reference
This document is the operator reference for the vetrix-cli registry command
tree. It covers every subcommand, its flags, realistic examples, and exit codes.
The command tree is implemented in cmd/vetrix-cli/cmd/registry.go. Error handling
utilities live in cmd/vetrix-cli/cmd/registry_errors.go.
Overview
The vetrix-cli registry command group gives operators direct CLI access to the
Vetrix admin container registry API. Use it to inspect images and tags, reclaim
storage by deleting unused content, view storage statistics, and manage garbage
collection runs.
Authentication requirement: every subcommand requires an admin bearer token
with acl.AdminSystem scope. Tokens can be supplied via the global --token
flag or the VETRIX_TOKEN environment variable. Requests that fail the scope
check are rejected with HTTP 403; missing or invalid tokens are rejected with
HTTP 401. Both produce a non-zero exit and a message on stderr.
Global flags
These flags are inherited from the vetrix-cli root command and apply to every
registry subcommand. Source: cmd/vetrix-cli/cmd/root.go.
| Flag | Env | Default | Description |
|---|---|---|---|
--server |
VETRIX_SERVER |
(none) | Vetrix API base URL (e.g. https://www.gitvetrix.com). |
--token |
VETRIX_TOKEN |
(none) | Admin bearer token. |
--token-file |
VETRIX_TOKEN_FILE |
(none) | Path to a file containing the bearer token. Resolved lazily. |
--insecure |
false |
Skip TLS verification. Warns on stderr when set. | |
-o, --output |
table |
Output format: table, json, or yaml. |
|
--timeout |
60s |
HTTP request timeout. | |
-v, --verbose |
false |
Increase log verbosity. | |
-h, --help |
Print help. |
Subcommands
list-images
Synopsis
vetrix-cli registry list-images [flags]
Description
Lists images in the admin registry, with optional filtering by owner, repository, or name substring.
Wraps GET /api/v1/admin/registry/images.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--limit |
int | 0 |
Page size (1–100; 0 uses the server default of 50). |
--offset |
int | 0 |
Page offset. |
--search |
string | (none) | Filter by image name (substring match). |
--owner |
string | (none) | Filter by repository owner. |
--repo |
string | (none) | Filter by repository name. |
Examples
# List all images (server default page size)
vetrix-cli registry list-images
# List images owned by a specific user, JSON output
vetrix-cli registry list-images --owner alice --output json
# Search for images whose name contains "api", page 2
vetrix-cli registry list-images --search api --limit 20 --offset 20
Exit codes
| Code | Condition |
|---|---|
| 0 | Success — image list printed to stdout. |
| 1 | API error (see Exit codes below). |
get-image
Synopsis
vetrix-cli registry get-image <owner> <repo> <image>
Description
Shows full details for a single image (tag count, total size, last push
timestamp, and latest tag) in the admin registry. The command resolves the
image by filtering the list endpoint with exact owner, repo, and image
name matching.
Wraps GET /api/v1/admin/registry/images?owner=&repo=&search=.
Flags
No subcommand-specific flags. Global flags apply.
Examples
# Inspect a specific image in text format
vetrix-cli registry get-image alice myapp api-server
# Same image, YAML output
vetrix-cli registry get-image alice myapp api-server --output yaml
Exit codes
| Code | Condition |
|---|---|
| 0 | Success — image details printed to stdout. |
| 1 | Image not found, or API error. |
delete-image
Synopsis
vetrix-cli registry delete-image [--yes] <owner> <repo> <image>
Description
Deletes an image and all of its tags from the admin registry. Prompts for
interactive confirmation unless --yes is set. This operation is irreversible.
Wraps DELETE /api/v1/admin/registry/images/{owner}/{repo}/{name}.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--yes |
bool | false |
Skip the interactive confirmation prompt. |
Examples
# Delete an image interactively
vetrix-cli registry delete-image alice myapp api-server
# Delete non-interactively (e.g. from a script)
vetrix-cli registry delete-image alice myapp api-server --yes
Exit codes
| Code | Condition |
|---|---|
| 0 | Image and all tags deleted successfully. |
| 1 | User cancelled the prompt, or API error. |
delete-tag
Synopsis
vetrix-cli registry delete-tag [--yes] <owner> <repo> <image> <tag>
Description
Deletes a single tag from an image in the admin registry. The image itself
and any remaining tags are not affected. Prompts for interactive confirmation
unless --yes is set.
Wraps DELETE /api/v1/admin/registry/images/{owner}/{repo}/{name}/tags/{tag}.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--yes |
bool | false |
Skip the interactive confirmation prompt. |
Examples
# Delete a specific tag interactively
vetrix-cli registry delete-tag alice myapp api-server v1.2.3
# Delete a tag non-interactively
vetrix-cli registry delete-tag alice myapp api-server latest --yes
Exit codes
| Code | Condition |
|---|---|
| 0 | Tag deleted successfully. |
| 1 | User cancelled the prompt, or API error. |
storage-stats
Synopsis
vetrix-cli registry storage-stats
Description
Displays total storage usage for the registry, plus ranked tables of the top repositories and top owners by bytes consumed.
Wraps GET /api/v1/admin/registry/storage.
Flags
No subcommand-specific flags. Global flags apply.
Examples
# View storage statistics in the default table format
vetrix-cli registry storage-stats
# Emit structured output for ingestion into a monitoring pipeline
vetrix-cli registry storage-stats --output json
Exit codes
| Code | Condition |
|---|---|
| 0 | Statistics printed to stdout. |
| 1 | API error. |
gc-status
Synopsis
vetrix-cli registry gc-status
Description
Shows metrics from the most recent garbage collection run: when it last ran, how many orphaned blobs were found, how many were deleted, how many bytes were freed, and how many deletion errors occurred.
Current server behavior: this command reads state that only the gc-run
on-demand endpoint populates. That endpoint is not currently wired to the
registry's GC service (see the caveat under gc-run below), so gc-status
always prints "No run recorded" — it does not reflect passes performed by
the automatic background GC scheduler documented in
registry.md.
Wraps GET /api/v1/admin/registry/gc/status.
Flags
No subcommand-specific flags. Global flags apply.
Examples
# Check the result of the last GC run
vetrix-cli registry gc-status
# JSON output, suitable for jq post-processing
vetrix-cli registry gc-status --output json | jq '.last_freed_bytes'
Exit codes
| Code | Condition |
|---|---|
| 0 | Status printed to stdout (including "No run recorded" when GC has never run). |
| 1 | API error. |
gc-run
Synopsis
vetrix-cli registry gc-run [--yes]
Description
Triggers a garbage collection pass on the admin registry via the on-demand
admin API. GC scans for blobs that are no longer referenced by any manifest
and deletes them, reclaiming storage. Prompts for interactive confirmation
unless --yes is set.
Current server behavior: the on-demand endpoint this command calls is not
currently wired to the registry's GC service. Every invocation returns HTTP
503 ("gc service not wired") regardless of flags — no GC pass runs and no
blobs are deleted. Garbage collection happens automatically via the
background GC scheduler described in
registry.md; there is currently no way
to trigger an out-of-cycle pass from the CLI.
Wraps POST /api/v1/admin/registry/gc/run.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--yes |
bool | false |
Skip the interactive confirmation prompt. |
Examples
# Run GC interactively and view the result
vetrix-cli registry gc-run
# Run GC non-interactively from a maintenance cron job
vetrix-cli registry gc-run --yes
# Run GC and capture results as JSON
vetrix-cli registry gc-run --yes --output json
Exit codes
| Code | Condition |
|---|---|
| 0 | GC run completed; blobs deleted and bytes reclaimed printed to stdout. |
| 1 | User cancelled the prompt, or API error — including the current always-503 "gc service not wired" response described above. |
Exit codes
All registry subcommands share a common exit-code contract derived from
handleHTTPError in cmd/vetrix-cli/cmd/registry_errors.go:
| Code | Condition |
|---|---|
| 0 | Success. The requested operation completed normally. |
| 1 | Any error condition. The specific cause is printed to stderr: |
— 401 Unauthorized: authentication required (missing or invalid token). |
|
— 403 Forbidden: admin scope required (token lacks acl.AdminSystem). |
|
— 4xx (other): client error; server message on stderr. |
|
— 5xx: server error; HTTP status and server message on stderr. |
|
| — Network / TLS error: message on stderr. | |
| — Interactive prompt cancelled by user: "cancelled" message on stderr. |
Exit code 1 is the only non-zero code. Scripts should test $? -ne 0 rather
than for a specific non-zero value.
See also
../../user-docs/registry/container.md— OCI registry endpoint, authentication, and Docker CLI usage.../../user-docs/registry/publish-action.md— CI/CD publish action for automated image builds and pushes.../maintenance/backup.md— operator CLI reference for the backup subsystem; follows the samevetrix-cliflag and exit-code conventions.