anthony/dredge
1
0
Fork 0
mirror of https://github.com/anthonyoteri/dredge.git synced 2026-06-05 15:26:53 -04:00
Code Issues Packages Projects Releases Wiki Activity

docs: rewrite README with comprehensive usage examples and installation guide

Browse Source 
- 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
This commit is contained in:
Anthony Oteri
2026-05-13 14:01:26 -04:00
parent 5031866876
commit c5f4cc2f9e
1 changed files with 186 additions and 85 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+186 -85
View File
@@ -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] <REGISTRY> <COMMAND>
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:
<REGISTRY>
The host or host:port or full base URL of the Docker Registry
Options:
--log-level[=<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] <REGISTRY> <COMMAND>
```
### Checking the API Version
### `<REGISTRY>` argument format
Perform a simple API Version check towards the registry endpoint
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:**
```sh
Usage: dredge <REGISTRY> 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 <REGISTRY> catalog
```
**Example:**
```sh
Usage: dredge <REGISTRY> 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 <REGISTRY> tags <NAME>
Arguments:
<NAME>
Options:
-h, --help Print help
```
dredge <REGISTRY> tags <NAME>
```
### Viewing details of a tagged image
| Argument | Description |
|---|---|
| `<NAME>` | The repository name (e.g. `myorg/backend`). |
Show detailed information about a particular image
**Example:**
```shell
Usage: dredge <REGISTRY> show <IMAGE> [TAG]
Arguments:
<IMAGE>
[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 <REGISTRY> delete <IMAGE> <TAG>
Arguments:
<IMAGE>
<TAG>
Options:
-h, --help Print help
```
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:**
```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 <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:**
```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 `<REGISTRY>` 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 <http://www.apache.org/licenses/LICENSE-2.0>)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
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.