From c5f4cc2f9e741f735f1ff487ff3bff9432e86cca Mon Sep 17 00:00:00 2001 From: Anthony Oteri <4360016+anthonyoteri@users.noreply.github.com> Date: Wed, 13 May 2026 14:01:26 -0400 Subject: [PATCH] docs: rewrite README with comprehensive usage examples and installation guide - 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 --- README.md | 271 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 186 insertions(+), 85 deletions(-) diff --git a/README.md b/README.md index 7922e50..1932c35 100644 --- a/README.md +++ b/README.md @@ -1,125 +1,226 @@ # dredge -Dredge is a command line tool for working with the Docker Registry V2 API. +`dredge` is a command-line tool for interacting with the [Docker Registry HTTP API V2](https://distribution.github.io/distribution/spec/api/). 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](https://crates.io/crates/dredge-tool) using Cargo: + +```sh +cargo install dredge-tool +``` + +The installed binary is named `dredge`. + +### Prerequisites + +- **Rust toolchain** 1.80 or later. Install via [rustup](https://rustup.rs/). +- 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](#deleting-a-tagged-image)). ## Usage -```shell -Dredge is a command line tool for working with the Docker Registry V2 API. - -Usage: dredge [OPTIONS] - -Commands: - catalog Fetch the list of available repositories from the catalog - tags Fetch the list of tags for a given image - show Show detailed information about a particular image - delete Delete a tagged image from the registry - check Perform a simple API Version check towards the configured registry endpoint - help Print this message or the help of the given subcommand(s) - -Arguments: - - The host or host:port or full base URL of the Docker Registry - -Options: - --log-level[=] - [default: info] - [possible values: trace, debug, info, warn, error, off] - - -h, --help - Print help (see a summary with '-h') - - -V, --version - Print version +``` +dredge [OPTIONS] ``` -### Checking the API Version +### `` argument format -Perform a simple API Version check towards the registry endpoint +The `` 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=` | `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 check +``` + +**Example:** ```sh -Usage: dredge check - -Options: - -h, --help Print help +dredge registry.example.com check +# Ok ``` -### Fetch Repository List +--- -Fetch the list of available repositories from the catalog +### Listing repositories (catalog) + +Fetch the full list of repositories available in the registry. Handles paginated responses automatically. + +``` +dredge catalog +``` + +**Example:** ```sh -Usage: dredge catalog - -Options: - -h, --help Print help +dredge registry.example.com catalog +# myorg/frontend +# myorg/backend +# myorg/worker ``` +--- + ### Listing tags for an image -Fetch the list of tags for a given image +Fetch the list of all tags published for a given image. Handles paginated responses automatically. -```shell -Usage: dredge tags - -Arguments: - - -Options: - -h, --help Print help +``` +dredge tags ``` -### Viewing details of a tagged image +| Argument | Description | +|---|---| +| `` | The repository name (e.g. `myorg/backend`). | -Show detailed information about a particular image +**Example:** -```shell -Usage: dredge show [TAG] - -Arguments: - -[TAG] - -Options: --h, --help Print help +```sh +dredge registry.example.com tags myorg/backend +# latest +# v1.0.0 +# v1.1.0 +# v2.0.0-rc1 ``` -### Deleteing a tagged image +--- -Delete a tagged image from the registry +### Showing image details -Note! This requires that the registry has storage delete rights enabled. For -example, when creating the registry, setting the environment variable -`REGISTRY_STORAGE_DELETE_ENABLED=true` to enable that feature. If that is not -enabled, a `MethodNotAllowed` error will be returned. +Show detailed manifest information for a specific tagged image, including the architecture, filesystem layers, digest, and ETag. Output is formatted as YAML. -Note! This will only remove the tag from the registry, it will not remove -orphaned digests. For that, the garbage collector on the registry service must -be run separately. - -```shell -Usage: dredge delete - -Arguments: - - - -Options: --h, --help Print help ``` +dredge show [TAG] +``` + +| Argument | Default | Description | +|---|---|---| +| `` | | The repository name (e.g. `myorg/backend`). | +| `[TAG]` | `latest` | The tag to inspect. Defaults to `latest` if omitted. | + +**Example:** + +```sh +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`: + +```sh +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 delete +``` + +| Argument | Description | +|---|---| +| `` | The repository name (e.g. `myorg/backend`). | +| `` | The tag to delete (e.g. `v1.0.0`). | + +**Example:** + +```sh +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 a `MethodNotAllowed` error. + +> **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:** + +```sh +dredge --log-level=debug registry.example.com catalog +``` + +**Silencing all log output:** + +```sh +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 failed` error. +- **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 `` argument. + +--- ## License Licensed under either of -* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0) -* MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT) +- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or ) +- MIT license ([LICENSE-MIT](LICENSE-MIT) or ) at your option. -### Contribution +--- -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. +## Contributing +Contributions are welcome! Please open an issue or submit a pull request on [GitHub](https://github.com/anthonyoteri/dredge). + +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.