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, authentication, groups, artifacts, artifact versions, rules, role mappings, and export and import of registry data.

The CLI is currently in dev-preview status and is unstable; its arguments and behavior are subject to backwards-incompatible changes. The CLI supports Linux (x86_64, bash), macOS (Apple Silicon, zsh), and Windows (x86_64, command prompt or PowerShell).

Prerequisites

You have installed Apicurio Registry.
You have access to a bash shell on Linux (x86_64), a zsh shell on macOS (Apple Silicon), or a command prompt or PowerShell on Windows (x86_64).

Installing the Apicurio Registry CLI

You can install the Apicurio Registry CLI to interact with Apicurio Registry from the command line. The CLI is distributed as a native executable in a platform-specific .zip file, so it does not require a Java runtime.

Prerequisites

You have a Linux x86_64 system with a bash shell, a macOS Apple Silicon system with a zsh shell, or a Windows x86_64 system with a command prompt or PowerShell.

Procedure

Download the .zip file for your platform, for example apicurio-registry-cli-VERSION-linux-x86_64.zip (Linux), apicurio-registry-cli-VERSION-osx-aarch64.zip (macOS), or apicurio-registry-cli-VERSION-windows-x86_64.zip (Windows), from the Apicurio Registry GitHub Releases page. Alternatively, you can download the CLI from the Maven Central repository by searching for apicurio-registry-cli.

Extract the downloaded file to a location of your choice:

On Linux and macOS:

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

On Windows:

> mkdir %USERPROFILE%\apicurio-cli
> tar -xf apicurio-registry-cli-VERSION-windows-x86_64.zip -C %USERPROFILE%\apicurio-cli

Install the CLI for the current user:

On Linux and macOS:
```
$ cd ~/apicurio-cli
$ ./acr install
```
On Windows:
```
> cd %USERPROFILE%\apicurio-cli
> acr.cmd install
```
This command copies the CLI files to $HOME/.apicurio/apicurio-registry-cli, creates symbolic links in $HOME/bin, updates your ~/.bashrc file (Linux) or ~/.zshrc file (macOS), and configures shell completions.

On Windows, the CLI files are copied to %USERPROFILE%\.apicurio\apicurio-registry-cli and the launcher is copied to %USERPROFILE%\bin, because creating a symbolic link there requires Developer Mode or an elevated prompt. Windows has no shell configuration file to source, so the command sets the ACR_HOME user environment variable and adds the bin directory to your user Path instead. Shell completions are generated for bash and zsh only.
Reload your shell configuration:

On Linux:
```
$ source ~/.bashrc
```
On macOS:
```
$ source ~/.zshrc
```
On Windows, open a new command prompt or PowerShell window so that it picks up the updated environment variables. The installed command is acr, which the command prompt resolves to acr.cmd through PATHEXT.

Verify the installation:

$ acr --help

To update an installed CLI to a newer version, use the acr update command. The CLI checks for updates once per day. To disable the update check, run acr config set update.check-enabled=false.

Additional resources

CLI README

Configuring Apicurio Registry CLI contexts

An Apicurio Registry CLI context stores the registry URL, optional default group and artifact identifiers, and authentication settings for one Apicurio Registry instance. You can create many contexts and switch between them as needed, similar to how you use contexts in Kubernetes.

Procedure

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.

Optional: Set default group and artifact identifiers for the context by using the --group (-g) and --artifact (-a) options. Commands that accept these identifiers use the context defaults when you omit the corresponding option.

List all configured contexts:

$ acr context

Example output

Current context is 'dev'.
ID    Registry URL           Group ID    Artifact ID
----  ---------------------  ----------  -----------
dev*  http://localhost:8080  my-schemas

The asterisk (*) indicates the current active context.

Optional: Create additional contexts without switching to them:

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

Switch to a different context:
```
$ acr context use CONTEXT_NAME
```

Update an existing context. If you omit the context name, the CLI updates the current context:

$ acr context update prod --registry-url http://registry.internal.example.com
$ acr context update --group my-schemas

Delete a context that you no longer need:
```
$ acr context delete CONTEXT_NAME
```
Optional: To delete all contexts, use the --all option.

Authenticating the Apicurio Registry CLI

You can log in to the Apicurio Registry instance of your current CLI context by using basic authentication or OAuth2 client credentials. The CLI stores secrets in the operating system keychain, and stores non-secret authentication settings in the context.

Prerequisites

You have configured a CLI context for a Apicurio Registry instance that requires authentication.
On Linux, the secret-tool utility (libsecret) is available for keychain storage. On macOS, the CLI uses the built-in keychain. On Windows, the CLI uses the built-in Credential Manager, which stores a secret of up to 2560 bytes.

Procedure

To log in with basic authentication, provide a user name. The CLI prompts for the password:
```
$ acr login --username my-user
```
Alternatively, provide the password with the --password (-p) option.
To log in with OAuth2 client credentials, provide the token endpoint and client ID. The CLI prompts for the client secret:
```
$ acr login --token-endpoint https://auth.example.com/realms/registry/protocol/openid-connect/token --client-id registry-client
```
Optional: Provide an OAuth2 scope with the --scope option.
Optional: On systems without a keychain, for example in headless environments, use the --allow-unsafe-credential-storage option. The CLI stores secrets in a credentials.json file and prints a warning. The file is restricted to its owner, by 0600 permissions on Linux and macOS and by an owner-only access control list on Windows. This preference persists per context.
To log out of the current context, run the following command. The CLI removes the stored secrets and clears the authentication settings of the context:
```
$ acr logout
```
Authentication is configured per context. Secret values are stored in the operating system keychain or in the credentials.json file, never in the config.json configuration file.

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.

Procedure

List all groups in the registry:
```
$ acr group
```
Optional: Use pagination options for large result sets:
```
$ acr group --page 1 --size 50
```
Create a new group:
```
$ acr group create GROUP_ID
```
Optional: Include a description and labels:
```
$ acr group create my-schemas --description "Production schemas" --label env=prod --label team=platform
```
The group ID default is reserved. You cannot create or update the default group.

Get details for a specific group:

$ acr group get GROUP_ID

For example:

$ acr group get my-schemas

Update a group description:

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

Optional: Add or update labels:

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

Optional: Delete labels:

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

Delete a group:
```
$ acr group delete GROUP_ID
```
You must configure Apicurio Registry with apicurio.rest.deletion.group.enabled=true to allow group deletions.

Optional: 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.

Managing artifacts using the CLI

You can use the CLI to create, list, get, update, and delete artifacts in Apicurio Registry. When you omit the group option, the CLI uses the default group of the current context, or the default group.

Prerequisites

You have configured at least one CLI context.

Procedure

List the artifacts in a group:
```
$ acr artifact --group my-schemas
```
Create a new artifact from a file:
```
$ acr artifact create my-artifact --group my-schemas --type AVRO --file schema.avsc
```
The --type option accepts the following values: AVRO, PROTOBUF, JSON, OPENAPI, ASYNCAPI, GRAPHQL, KCONNECT, WSDL, XSD, and XML. To read content from standard input, use --file -.

Optional: Provide metadata with the --name, --description, and --label options, and set the identifier of the first version with the --version option.
Get the metadata of an artifact:
```
$ acr artifact get my-artifact --group my-schemas
```
To retrieve the content of the latest version instead of the metadata, use the --content (-c) option. The --content and --output-type options are mutually exclusive.
Update the metadata of an artifact:
```
$ acr artifact update my-artifact --group my-schemas --description "Order event schema"
```
Optional: Manage labels with the --set-label and --delete-label options.
Delete an artifact:
```
$ acr artifact delete my-artifact --group my-schemas
```
You must configure Apicurio Registry with apicurio.rest.deletion.artifact.enabled=true to allow artifact deletions.

Managing artifact versions using the CLI

You can use the CLI to list, create, get, update, and delete the versions of an artifact, including draft versions. When you omit the artifact option, the CLI uses the default artifact of the current context.

Prerequisites

You have configured at least one CLI context.
The artifact exists in the registry.

Procedure

List the versions of an artifact:

$ acr artifact version --group my-schemas --artifact my-artifact

Create a new version from a file:
```
$ acr artifact version create 2.0.0 --file schema-v2.avsc --group my-schemas --artifact my-artifact
```
If you omit the version identifier, the server generates one. To create the version in the DRAFT state, use the --draft option.
Get a version. The version expression is an explicit version identifier, such as 2.0.0, or a branch expression, such as branch=latest:
```
$ acr artifact version get 2.0.0 --group my-schemas --artifact my-artifact
```
To retrieve the version content instead of the metadata, use the --content (-c) option.
Update the metadata or state of a version:
```
$ acr artifact version update 2.0.0 --group my-schemas --artifact my-artifact --state DEPRECATED
```
The --state option accepts the following values: ENABLED, DISABLED, DEPRECATED, and DRAFT. To update the content of a version, use the --file option. Content updates are only possible for versions in the DRAFT state.
Delete a version:
```
$ acr artifact version delete 2.0.0 --group my-schemas --artifact my-artifact
```
You must configure Apicurio Registry with apicurio.rest.deletion.artifact-version.enabled=true to allow version deletions.

Managing rules using the CLI

You can use the CLI to manage content rules at the global, group, and artifact levels. Rules at a more specific level override rules at a broader level.

Prerequisites

You have configured at least one CLI context.

Procedure

Manage global rules with the acr rule commands:

$ acr rule create VALIDITY --config FULL
$ acr rule
$ acr rule get VALIDITY
$ acr rule update VALIDITY --config SYNTAX_ONLY
$ acr rule delete VALIDITY

Manage the rules of a group with the acr group rule commands:

$ acr group rule create COMPATIBILITY --config BACKWARD --group my-schemas

Manage the rules of an artifact with the acr artifact rule commands:

$ acr artifact rule create INTEGRITY --config FULL --group my-schemas --artifact my-artifact

Optional: Delete all rules at a level by using the --all option:
```
$ acr rule delete --all
```
For the valid rule types and configuration values, see the rule types table in the CLI reference section.

Managing role mappings using the CLI

You can use the CLI to assign Apicurio Registry roles to principals, such as user accounts or service accounts, when role-based authorization is enabled on the registry.

Prerequisites

You have configured a CLI context for a Apicurio Registry instance with role-based authorization enabled.
You are authenticated as a user with permission to manage role mappings.

Procedure

Create a role mapping for a principal. The role is one of ADMIN, DEVELOPER, or READ_ONLY:
```
$ acr role create service-account-my-app DEVELOPER
```
Optional: Provide a display name with the --name option.
List all role mappings:
```
$ acr role
```
Get the role mapping of a principal:
```
$ acr role get service-account-my-app
```

Update the role of a principal:

$ acr role update service-account-my-app --role ADMIN

Delete a role mapping:

$ acr role delete service-account-my-app

Exporting and importing data using the CLI

You can use the CLI to export Apicurio Registry data to a .zip file and to import previously exported data into a registry instance.

Prerequisites

You have configured at least one CLI context.

Procedure

Export all registry data to a .zip file:

$ acr admin export --file registry-export.zip

Optional: Export the data of a single group by using the --group option:
```
$ acr admin export --file group-export.zip --group my-schemas
```
Import registry data from a .zip file:
```
$ acr admin import --file registry-export.zip
```
Optional: To import into a registry that already contains data, use the --no-require-empty option. To let the server generate new global and content identifiers instead of preserving the exported ones, use the --no-preserve-ids option.

CLI output formats and pagination

The CLI supports different output formats, pagination, ordering, and column selection options for managing command output.

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

The acr content command is an exception: its output types are raw (default) and json.

In JSON mode, the CLI writes only data to standard output and diverts status messages to standard error, which makes the output suitable for scripting.

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

--page - The page number, starting from 1 (default: 1)
--size - The number of items per page (default: 10)

For example:

$ acr group --page 2 --size 25

List commands also support ordering with the --order-by and --order options. The default sort order is ascending (Asc), and the default sort field depends on the command.

Selecting columns

For commands that list results in a table (for example acr artifact, acr group, and the acr search commands), you can choose which columns to show by using the --columns option. It takes a comma-separated list of column names, matched case-insensitively:

$ acr artifact --columns groupId,artifactId,name
$ acr artifact version --columns version,state,createdOn

An unknown column name produces an error that lists the valid columns. This option only affects table output, and is available on commands that list multiple records rather than commands that show details of a single record.

Verbose output

To enable verbose output for debugging, use the --verbose option. This option has no short form.

CLI reference

The following tables describe CLI global options, exit codes, available commands, rule types, and CLI configuration properties.

The following options are available for most CLI commands:

Table 1. Global options
Option	Description
`--verbose`	Enable verbose output for debugging. This option has no short form.
`--help`, `-h`	Display help information for the command.
`--output-type`, `-o`	Set the output format. Valid values are `table` (default) and `json`. The `acr content` command uses `raw` (default) and `json`.

The CLI uses the following exit codes:

Table 2. Exit codes
Code	Description
0	Successful execution.
1	Application error.
2	Input validation error.
3	Apicurio Registry server error.

The following commands are available. Running a parent command, such as acr group, without a subcommand lists the corresponding records.

Table 3. Command summary
Command	Description
`acr context`	List contexts. Subcommands: `create`, `update`, `use`, `delete`. Aliases: `contexts`, `ctx`.
`acr config`	List CLI configuration properties. Subcommands: `get`, `set`, `delete`. Alias: `cfg`.
`acr login`	Log in to the current context by using basic authentication or OAuth2 client credentials.
`acr logout`	Log out of the current context and remove stored credentials.
`acr group`	List groups. Subcommands: `create`, `get`, `update`, `delete`. Alias: `groups`.
`acr group rule`	List the rules of a group. Subcommands: `create`, `get`, `update`, `delete`. Alias: `rules`.
`acr artifact`	List the artifacts of a group. Subcommands: `create`, `get`, `update`, `delete`. Alias: `artifacts`.
`acr artifact rule`	List the rules of an artifact. Subcommands: `create`, `get`, `update`, `delete`. Alias: `rules`.
`acr artifact version`	List the versions of an artifact. Subcommands: `create`, `get`, `update`, `delete`. Alias: `versions`.
`acr artifact version comment`	Work with version comments. Subcommands: `list`, `create`, `update`, `delete`. Alias: `comments`.
`acr reference list`	List the outbound references of a version. Use the `--inbound` option to list inbound references instead. Aliases: `references`, `ref`.
`acr rule`	List global rules. Subcommands: `create`, `get`, `update`, `delete`. Alias: `rules`.
`acr role`	List role mappings. Subcommands: `create`, `get`, `update`, `delete`. Alias: `roles`.
`acr search group`	Search groups by identifier, description, or labels. Alias: `groups`.
`acr search artifact`	Search artifacts by name, description, group, type, labels, or identifiers. Alias: `artifacts`.
`acr search version`	Search versions, with additional version and state filters. Alias: `versions`.
`acr search content`	Search artifacts by content from a file or standard input. Supports canonical content matching with the `--canonical` option. Alias: `contents`.
`acr content`	Retrieve content by global ID, content ID, or SHA-256 hash.
`acr server-config`	List the dynamic configuration properties of the Apicurio Registry server. Subcommands: `get`, `set`, `reset`. Alias: `server-configs`.
`acr admin export`	Export registry data to a .zip file, optionally limited to one group.
`acr admin import`	Import registry data from a .zip file.
`acr install`	Install the CLI for the current user.
`acr update`	Update the CLI to a newer version.
`acr version`	Display CLI version information and, if the server is reachable, server version information.

The rule commands accept the following rule types and configuration values:

Table 4. Rule types and configuration values
Rule type	Configuration values
`VALIDITY`	`NONE`, `SYNTAX_ONLY`, `FULL`
`COMPATIBILITY`	`NONE`, `BACKWARD`, `BACKWARD_TRANSITIVE`, `FORWARD`, `FORWARD_TRANSITIVE`, `FULL`, `FULL_TRANSITIVE`
`INTEGRITY`	`NONE`, `REFS_EXIST`, `ALL_REFS_MAPPED`, `NO_DUPLICATES`, `NO_CIRCULAR_REFERENCES`, `FULL`

You can adjust the behavior of the CLI itself with the acr config set command. The following CLI configuration properties are available:

Table 5. CLI configuration properties
Property	Default	Description
`update.check-enabled`	`true`	Check for CLI updates once per day.
`update.timeout-seconds`	`60`	Timeout for update operations, in seconds.
`update.skip-checksum-verification`	`false`	Skip checksum verification when updating the CLI.

Additional resources