Overview of the command-line tool

The IBM® API Connect developer toolkit provides commands for cloud administration and API development and management.

Command syntax

In general, commands have the following syntax:
apic command:sub-command [argument] [options]
where
  • command is the command, usually the thing on which you are acting (for example, product, app, API, Catalogs, and so on).
  • sub-command is the action to perform.
  • argument is the argument, where applicable (for example,catalog).
  • options are any number of command-line options, which have the form --option [value]. Options also have a short form with a single dash instead of a double dash.
For example, apic apps:publish --server mgmnthost.com.
For some commands, either the command or sub-command portion is optional. For example:
  • apic products:publish is equivalent to apic publish.
  • apic products:list is equivalent to apic products.
The create command has a slightly different syntax:
apic create:type [options]
Use the -h or --help option to view command help.
Note: The language in which the CLI help text, and other command response text, is displayed is determined by the locale setting on your local machine.

Viewing command line tool help

Display general command-line help information by entering the following command: apic --help or apic -h. Display help information for a specific apic command by entering the following command: apic command_name --help or apic command_name -h.

Viewing version information

Display the version of the command-line tool by entering the command: apic --version.

Setting the mode

The API Connect toolkit CLI runs commands on either the provider organization or on the consumer organization. When you run the command, you use the different mode options to identify the instance on which you want to run the command. The following list provides a summary of the modes that are available:
apim
This mode applies to the administrative instances of the CLI. When you run commands in this mode, it uses the overall API Manager as its scope. This mode is the default mode.
An example of running a command in the apim mode:
apic extensions:list-all --mode apim --scope catalog --server server1 --catalog catalog1 --org myOrg --configured-gateway-service service1
portaladmin
This mode applies to the developer portal instances of the CLI. This mode supports commands that you can use to replicate all or part of your Developer Portal environment.
An example of running a command in the portaladmin mode:
apic --mode portaladmin custom-theme:create-export --catalog catalog1 --org myOrg --server server1 --format json
consumer
This mode applies to the consumer instances of the CLI. This command uses the consumer organizations that you have permission to access as its scope. You must specify this mode or set it as the default value for the command to use it.
An example of running a command in the consumer mode:
apic catalogs:list --mode consumer --scope catalog --server server1 --catalog catalog1 --org myOrg
To avoid having to supply the parameter on every consumer CLI command, you can set the mode configuration variable, as described in the next section.

Using configuration variables

You can set the values of commonly-used properties in configuration variables. In general, it's easier and more consistent to set configuration variables instead of specifying them using command-line options.
Note:

The configuration variables for OpenAPI projects are always global. The values of global configuration variables are stored in the user-home-dir/.apiconnect/config file, where user-home-dir is the user's home directory.

Use the following commands to work with configuration variables:

  • apic config:get varname - Get a configuration variable. Use apic config to display the values of all local configuration variables or apic config -g to display the values of all global configuration variables.
  • apic config:set varname - Set or update the specified configuration variable.
  • apic config:delete varname - Delete the specified configuration variable.
  • apic config:clear - Delete all configuration variables.

You set configuration property values by using the apic config:set command. By setting configuration properties (for example catalog and app), you do not need to supply values for these options when you enter a command.

Additionally, you can use apic properties commands to work with configuration properties:
  • apic properties:clear - Clear the configuration properties.
  • apic properties:create - Augment the configuration properties with additional name/value pairs.
  • apic properties:delete - Delete the configuration property.
  • apic properties:get - Get the configuration property.
  • apic properties:list - List the configuration properties.
  • apic properties:update - Update the configuration property.
Note:

If you have an environment variable of the same name as a CLI configuration property then, by default, its value will override the value of the corresponding CLI configuration property for any CLI command at that scope.

For example, if you have defined an environment variable called SPACE then, by default, that value will be assumed for the value of the --space parameter in the following command, regardless of any space configuration property setting:
apic products:publish my_product.yaml --scope space

To prevent environment variables overriding CLI configuration properties, define an environment variable called APIC_LOAD_FROM_ENV, set to the value false.

The following table describes the configuration variables:

Table 1. Configuration variables
Variable name Description Use instead of (or override with) these flags...
catalog Default Catalog name for all commands that manage aspects of a Catalog.
The Catalog value can be specified as either:
  • The full Catalog URI that includes server name and organization name: mgmt-server/api/catalogs/org-name/catalog-name. In this case, you do not need to specify --catalog, --organization, or --server when you make CLI calls, since their values are included in the full Catalog URI.
  • The Catalog name, for example: sandbox. In this case, you still need to specify --organization and --server when you make CLI calls.
Note: The Catalog name apic-dev is reserved for local testing.
  • If Catalog URI used in variable assignment: --catalog, --organization, --server
  • If Catalog name used in variable assignment: --catalog
cloud Default management server host name for cloud administration commands. Form: mgmt-server/api/. --server
consumer Default URI of an API consumer. Form: mgmt-server/api/consumer-orgs/org-name/catalog-name/consumer-org-name, where mgmt-server is the management server, org-name is the organization name, catalog-name is the Catalog name, and consumer-org-name is the consumer organization name. -–server, -–organization, -–catalog, -–consumer
mode The default value of the --mode parameter for CLI commands. Set the value to apim or consumer depending on whether you want to run commands on a provider organization or a consumer organization. If you do not set this variable, and do not supply a --mode parameter on a command, the value apim is assumed. --mode
org Default org name for all commands that manage organizations.

Form: mgmt-server/api/orgs/org-name, where mgmt-server is the management server, org-name is the organization name.

The org value can be specified as either:
  • The full org URI that includes the server name: mgmt-server/api/orgs/org-name. In this case, you do not need to specify --server or --organization when you make CLI calls, since their values are included in the full org URI.
  • The org name, for example: providerorg1. In this case, you still need to specify --server when you make CLI calls.
  • If org URI used in variable assignment: --organization, --server
  • If org name used in variable assignment: --organization
space Default Space URI for all commands that manage aspects of a Space.

Form: mgmt-server/api/spaces/org-name/catalog-name/space-name, where mgmt-server is the management server, org-name is the organization name, catalog-name is the Catalog name, and space-name is the Space name.

You can append the port number to the server name if it is not the default value of 443.

 --server, --organization, --catalog, --space
To set configuration properties, enter the following command:
apic config:set name=value
where name is the name of the configuration property and value the value to assign to it.

For example:

apic config:set catalog=sandbox

Scripting commands

It's often helpful to automate a series of apic commands In a shell script. Since the apic tool first requires you to interactively accept the license, you must first use the following command:
apic --accept-license
Once you do that, your scripts can run non-interactively.
To disable collection of usage analytics, enter this command:
apic --live-help

Setting the language

You can configure the language for the CLI command outputs by using the --lang flag. This flag allows the developer toolkit to provide command outputs in the specified language. The following table contains the supported languages:

Table 2. Supported languages
Language value Language
en-us English (US)
cs Czech
de German
es Spanish
fr French
it Italian
ja Japanese
ko Korean
nl Dutch
pl Polish
pt-br Portuguese (Brazil)
ru Russian
tr Turkish
zh-cn Chinese (Simplified)
zh-tw Chinese (Traditional)
Use a language values based on your needs. Use French as an example. To set the language to French, run the following command:
apic --lang fr
After you run the command, the outputs are displayed in French. For example:
apic config get invalid
Error: invalid n'est pas une variable de configuration valide
When you provide an invalid value that is not a supported language, the system displays the following error:
apic --lang invalid
Error: Value invalid is not valid for lang. Valid values are: en-us, cs, de, es, fr, it, ja, ko, nl, pl, pt-br, ru, tr, zh-cn, zh-tw