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

Installing the CLI for all users

You can install the CLI in shared system directories on Linux or macOS with the --global option.

Prerequisites

You have downloaded and extracted the CLI distribution for your platform.
You have permission to run commands with sudo.

Procedure

In the extracted distribution directory, install the CLI:

$ sudo ./acr install --global

The installer copies the CLI to /usr/local/lib/apicurio-registry-cli and creates the acr and acr_env symbolic links in /usr/local/bin. It does not change individual shell profiles.

A global installation shares one config.json file. Separate configuration for each user is not supported. Users without write access to that file cannot change contexts or configuration. Use a per-user installation when you need independent contexts and authentication settings.

Optional: Add the following command to your shell profile to load shell completions:
```
source /usr/local/bin/acr_env
```

Verification

Verify that /usr/local/bin is on your PATH, and run /usr/local/bin/acr --help.

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

Optional: Save group and artifact identifiers automatically after successful group create, group get, artifact create, and artifact get commands:
```
$ acr config set context.auto-update=true
```
This setting is disabled by default. When a group command changes the context group, it clears the previous artifact identifier. An artifact command saves both identifiers. Commands that omit --group or --artifact then use these saved values.
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 OpenID Connect (OIDC) provider URL and client ID. The CLI discovers the token endpoint and prompts for the client secret:
```
$ acr login --auth-server-url https://auth.example.com/realms/registry --client-id registry-client
```
The CLI appends /.well-known/openid-configuration to the provider URL. Alternatively, specify the token endpoint directly:
```
$ acr login --token-endpoint https://auth.example.com/realms/registry/protocol/openid-connect/token --client-id registry-client
```
If you specify both options, --token-endpoint takes precedence over discovery. Provide an OAuth2 scope with --scope when required by your provider.
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
```
The first page includes the built-in group as default (implicit) in table output. Use default as the identifier in commands. JSON output uses default without the display marker. You cannot create, update, or delete this implicit 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.

Checking and synchronizing GitOps storage using the CLI

You can inspect GitOps storage status and request an immediate synchronization from the configured Git repositories.

Prerequisites

Your CLI context points to a Apicurio Registry instance that uses GitOps storage.
You have read access to view status and administrator access to request synchronization when authorization is enabled.

Procedure

Check the current synchronization status:
```
$ acr gitops status
```
The output includes the synchronization state, attempt and success timestamps, resource counts, source commit identifiers, and reported errors.
Request synchronization and wait for the server to report a completed attempt:
```
$ acr gitops sync --wait --timeout 300
```
The CLI checks status every two seconds. It waits for the attempt timestamp to advance and for the state to become IDLE or ERROR. Without --wait, the command returns after requesting synchronization.
Optional: Write the reported status as JSON for automation:
```
$ acr gitops status --output-type json
$ acr gitops sync --wait --output-type json
```
For sync, JSON status output requires --wait. Without --wait, the command prints a request confirmation regardless of the output format.

Verification

Check that the sources values match the expected commits. The CLI reports the server status; a successful command exit alone does not verify which commit the registry loaded.

Additional resources

Configuring Apicurio Registry with GitOps storage

Validating a Git revision using the CLI

You can validate the content of a Git revision before merging a change. Validation does not change the live registry content.

Prerequisites

Your CLI context points to a Apicurio Registry instance that uses GitOps storage.
The server has apicurio.gitops.validate.enabled=true.
The repository ID is configured on the server, and the server can fetch the Git revision.
You have administrator access when authorization is enabled.

Procedure

Submit a branch, tag, or pull request ref for validation:
```
$ acr gitops validate --repo primary --ref refs/heads/proposed-schemas --timeout 300
```
Replace primary with the configured repository ID. The CLI waits for the validation task to finish and displays its result, resource counts, and errors. The default timeout is 300 seconds.
Optional: Use JSON output to process the validation result in a pipeline:
```
$ acr gitops validate --repo primary --ref refs/heads/proposed-schemas --output-type json
```
JSON output includes the task ID, task state, validation result, timestamps, counts, and error details. A failed task, failed validation result, or timeout returns exit code 1.
Optional: Retain the server task for later inspection:
```
$ acr gitops validate --repo primary --ref refs/heads/proposed-schemas --no-cleanup
```
By default, the CLI attempts to delete the task when it finishes waiting, including after an error or timeout. With --no-cleanup, the task remains available until it expires or you delete it through the REST API.

Verification

Check the command exit code and the reported validation result. Successful validation reports success.

Additional resources

Configuring Apicurio Registry with GitOps storage

GitOps CLI options

The GitOps commands support waiting for results, JSON output, and validation task cleanup.

Table 1. GitOps command options
Command	Option	Description
`status`, `sync`, `validate`	`--output-type`, `-o`	Output format: `table` (default) or `json`. The `sync` command requires `--wait` to return status in either format.
`sync`	`--wait`	Wait for a completed synchronization attempt. Disabled by default. A reported `ERROR` state or timeout returns exit code `1`.
`sync`, `validate`	`--timeout`	Maximum wait in seconds. Default: `300`. Applies only when the command waits for completion.
`validate`	`--repo`	Required repository ID from the server configuration, not a repository URL.
`validate`	`--ref`	Required Git branch, tag, or pull request ref to validate.
`validate`	`--no-wait`	Return the initial task details without waiting for the result or deleting the task. A successful exit confirms task creation, not successful validation. Retrieve the task result through the REST API using the returned task ID.
`validate`	`--cleanup`, `--no-cleanup`	Control task deletion after waiting. Cleanup is enabled by default and does not apply with `--no-wait`.

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.

Terminal width

Table output adapts to the terminal width by wrapping long cell values. If automatic width detection fails, the CLI uses the COLUMNS environment variable, then a default of 120 characters. Piped or redirected output has no width limit. JSON output is unaffected by terminal width.

Verbose output

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

$ acr --verbose artifact get my-artifact --group my-schemas

Verbose output includes HTTP requests prefixed with > and responses prefixed with <. It shows the method, URL, headers, status, and body. Bodies longer than 8192 characters are truncated.

The logger redacts credential headers and common credential query parameters. Other URL values and body content remain visible, so review verbose logs before sharing them. Redirects appear as separate requests with a redirect number; retries appear as additional requests.

To suppress HTTP traffic logs and retain other debug output, configure the HTTP logging category:

$ acr config set 'quarkus.log.category."io.apicurio.registry.client.http".level=WARNING'

Category overrides apply only when you use --verbose.

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 2. 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 3. 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 4. 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 gitops`	Display GitOps command help. Subcommands: `status`, `sync`, `validate`.
`acr install`	Install the CLI for the current user, or for all users with `--global` on Linux or macOS.
`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 5. 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 6. CLI configuration properties
Property	Default	Description
`context.auto-update`	`false`	Save group and artifact identifiers to the current context after successful group or artifact `create` and `get` commands.
`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