Managing Apicurio Registry content using the command-line interface

You can use the Apicurio Registry command-line interface (CLI) to manage Apicurio Registry content from the command line. The CLI provides commands for managing CLI contexts and artifact groups.

The CLI is currently in dev-preview status. The CLI supports Linux (bash) and macOS (zsh). Windows is not supported yet. The CLI currently implements only group management commands. Future releases will include additional commands.

The CLI does not yet support authentication. You can only use the CLI with Apicurio Registry instances that do not require authentication.
Prerequisites

  • You have installed Apicurio Registry.

  • You have Java 11 or higher installed.

  • You have access to a bash shell (Linux) or zsh shell (macOS).

Installing the Apicurio Registry CLI

You can install the Apicurio Registry CLI to interact with Apicurio Registry from the command line. The CLI comes as a .zip file that has the executable program and required dependencies.

Prerequisites

  • You have Java 11 or higher installed on your system.

  • You have access to a bash shell (Linux) or zsh shell (macOS).

Procedure

  1. Download the latest apicurio-registry-cli-VERSION.zip file from the Apicurio Registry GitHub Releases page. Alternatively, you can download the CLI from the Maven Central repository by searching for apicurio-registry-cli.

  2. Extract the downloaded file to a location of your choice:

    $ unzip apicurio-registry-cli-VERSION.zip -d ~/apicurio-cli

  3. Install the CLI for the current user:

    $ cd ~/apicurio-cli
$ ./acr install

    This command installs the CLI executable to $HOME/bin and creates a configuration directory at $HOME/.apicurio/apicurio-registry-cli. The command also updates your ~/.bashrc file (Linux) or ~/.zshrc file (macOS) and configures shell completions.

  4. Reload your shell configuration:

    On Linux:

    $ source ~/.bashrc

    On macOS:

    $ source ~/.zshrc

  5. Verify the installation:

    $ acr --help
Additional resources

  • For more information, see the CLI README on GitHub.

Configuring Apicurio Registry CLI contexts

An Apicurio Registry CLI context stores the registry URL and identifies the instance that the CLI commands target. You can create many contexts and switch between them as needed, similar to how you use contexts in Kubernetes.

Procedure

  1. Create a new context for your Apicurio Registry instance:

    $ acr context create CONTEXT_NAME REGISTRY_URL

    For example:

    $ acr context create dev http://localhost:8080

    The CLI automatically switches to the newly created context.

  2. List all configured contexts:

    $ acr context
    Example output
    Current context is 'default'.
ID        Registry URL
--------  ---------------------
default*  http://localhost:8080

    The asterisk (*) indicates the current active context.

  3. Optional: Create additional contexts without switching to them:

    $ acr context create prod http://registry.example.com --no-switch-current

  4. Delete a context that you no longer need:

    $ acr context delete CONTEXT_NAME

Managing groups using the CLI

You can use the CLI to create, list, update, and delete artifact groups in Apicurio Registry. Groups offer a way to organize related artifacts.

Prerequisites

  • You have configured at least one CLI context.

Listing groups

To list all groups in the registry:

$ acr group

You can use pagination options for large result sets:

$ acr group --page 1 --size 50

Creating a group

To create a new group:

$ acr group create GROUP_ID

You can include a description and labels:

$ acr group create my-schemas --description "Production schemas" --label env=prod --label team=platform

Getting group details

To get details for a specific group:

$ acr group get GROUP_ID

For example:

$ acr group get my-schemas

Updating a group

To update a group description:

$ acr group update my-schemas --description "Updated description"

To add or update labels:

$ acr group update my-schemas --set-label env=staging --set-label owner=alice

To delete labels:

$ acr group update my-schemas --delete-label env

Deleting a group

To delete a group:

$ acr group delete GROUP_ID

You must configure Apicurio Registry with apicurio.rest.deletion.group.enabled=true to allow group deletions.

To delete a group that has artifacts, use the --force option:

$ acr group delete my-schemas --force

Using --force deletes the group and all artifacts it contains. Use this option with caution.

CLI output formats and pagination

The CLI supports different output formats and pagination options for managing large result sets.

Output formats

The CLI supports the following output formats:

  • table (default) - Human-readable tabular format

  • json - Machine-readable JSON format

To specify the output format, use the --output-type or -o option:

$ acr group --output-type json
$ acr group get my-schemas -o json
Pagination

For commands that return lists, you can use pagination options:

  • --page - The page number (starting from 1)

  • --size - The number of items per page

For example:

$ acr group --page 2 --size 25

CLI reference

The following tables describe CLI global options and exit codes.

Global options

The following options are available for most CLI commands:

Option Description

--verbose, -v

Enable verbose output for debugging.

--help, -h

Display help information for the command.

--output-type, -o

Set the output format. Valid values are table (default) and json.
Exit codes

The CLI uses the following exit codes:

Code Description

0

Successful execution.

1

Application error.

2

Input validation error.

3

Apicurio Registry server error.
Command summary

The following commands are currently available:

Command Description

acr context

List all configured contexts.

acr context create

Create a new context.

acr context delete

Delete a context.

acr group

List all groups.

acr group create

Create a new group.

acr group get

Get group details.

acr group update

Update a group.

acr group delete

Delete a group.

acr install

Install the CLI for the current user.

acr update

Update the CLI to a newer version.

acr version

Display CLI version information.
Additional resources