Anthony Oteri
01ef25b953
- Add features list, installation section, and prerequisites - Document all subcommands with realistic examples and argument tables - Add REGISTRY argument format table - Fix typo 'Deleteing' -> 'Deleting' - Add known limitations section
5.8 KiB
dredge
dredge is a command-line tool for interacting with the Docker Registry HTTP API V2. It lets you inspect, list, and delete images and tags in any V2-compatible container registry directly from your terminal.
Features
- List all repositories in a registry catalog
- List all tags for a given image
- Show detailed manifest information for a tagged image
- Delete a tagged image by resolving its digest and removing the manifest
- Verify that a registry endpoint speaks the Docker Distribution API v2
Installation
Install from crates.io using Cargo:
cargo install dredge-tool
The installed binary is named dredge.
Prerequisites
- Rust toolchain 1.80 or later. Install via rustup.
- A running Docker Registry V2 endpoint. The registry must be accessible over the network from the machine running
dredge. - For delete operations, the registry must have storage deletion enabled (see Deleting a tagged image).
Usage
dredge [OPTIONS] <REGISTRY> <COMMAND>
<REGISTRY> argument format
The <REGISTRY> positional argument accepts any of the following forms:
| Form | Example |
|---|---|
| Hostname | registry.example.com |
| Host and port | registry.example.com:5000 |
| Full URL | https://registry.example.com:5000 |
When no scheme is provided, https:// is assumed automatically.
Global options
| Option | Default | Description |
|---|---|---|
--log-level=<LEVEL> |
info |
Set the log verbosity. Possible values: trace, debug, info, warn, error, off. |
-h, --help |
Print help information. | |
-V, --version |
Print version information. |
Subcommands
Checking the API version
Verify that the registry endpoint implements the Docker Distribution API v2.
dredge <REGISTRY> check
Example:
dredge registry.example.com check
# Ok
Listing repositories (catalog)
Fetch the full list of repositories available in the registry. Handles paginated responses automatically.
dredge <REGISTRY> catalog
Example:
dredge registry.example.com catalog
# myorg/frontend
# myorg/backend
# myorg/worker
Listing tags for an image
Fetch the list of all tags published for a given image. Handles paginated responses automatically.
dredge <REGISTRY> tags <NAME>
| Argument | Description |
|---|---|
<NAME> |
The repository name (e.g. myorg/backend). |
Example:
dredge registry.example.com tags myorg/backend
# latest
# v1.0.0
# v1.1.0
# v2.0.0-rc1
Showing image details
Show detailed manifest information for a specific tagged image, including the architecture, filesystem layers, digest, and ETag. Output is formatted as YAML.
dredge <REGISTRY> show <IMAGE> [TAG]
| Argument | Default | Description |
|---|---|---|
<IMAGE> |
The repository name (e.g. myorg/backend). |
|
[TAG] |
latest |
The tag to inspect. Defaults to latest if omitted. |
Example:
dredge registry.example.com show myorg/backend v2.0.0-rc1
# name: myorg/backend
# tag: v2.0.0-rc1
# architecture: amd64
# fsLayers:
# - blobSum: sha256:a3ed95caeb02ffe68...
# - blobSum: sha256:7d97e254a0461b0a3...
# digest: sha256:0259571889ac87efbf...
# etag: sha256:0259571889ac87efbf...
Omitting the tag inspects latest:
dredge registry.example.com show myorg/backend
Deleting a tagged image
Delete a specific tagged image from the registry. The tag is resolved to its content digest, and the manifest is deleted by digest.
dredge <REGISTRY> delete <IMAGE> <TAG>
| Argument | Description |
|---|---|
<IMAGE> |
The repository name (e.g. myorg/backend). |
<TAG> |
The tag to delete (e.g. v1.0.0). |
Example:
dredge registry.example.com delete myorg/backend v1.0.0
Note: This requires the registry to have storage deletion enabled. When running a registry container, set the environment variable
REGISTRY_STORAGE_DELETE_ENABLED=true. If deletion is not enabled, the registry will return aMethodNotAllowederror.
Note: This operation removes only the manifest referenced by the given tag. Unreferenced layer blobs (orphaned digests) are not removed automatically. Run the registry's garbage collector separately to reclaim storage space.
Configuration
There is no configuration file. All settings are passed as command-line arguments.
Enabling verbose logging:
dredge --log-level=debug registry.example.com catalog
Silencing all log output:
dredge --log-level=off registry.example.com catalog
Known Limitations
- No authentication support. Registries that require authentication (e.g., Docker Hub, private registries protected by HTTP Basic Auth or token-based auth) are not currently supported. Requests to such registries will fail with an
HTTP Authorization failederror. - Delete only removes the manifest tag, not layer blobs. After deletion, run the registry's garbage collector to free disk space.
- HTTPS assumed by default. Plain HTTP registries must be specified with an explicit
http://scheme in the<REGISTRY>argument.
License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Contributing
Contributions are welcome! Please open an issue or submit a pull request on GitHub.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.