Toolkit command summary

A summary of the core commands in the IBM® API Connect developer toolkit.

Important: From IBM API Connect Version 5.0.8.7, some commands are no longer supported by the API Connect toolkit. Such commands are indicated on this page by the V5.0.7 and earlier

icon.

Viewing command line tool help
Viewing version information
Command stability
Authenticating
Using configuration variables
Configuring the command-line tool to use TLS certificates
Creating and managing local files
Listing API Manager items
Working with drafts
Working with Catalogs and Spaces
Command summary

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 or apic -v. Display extended version information, including the versions of all the command-line tool plug-in modules, by entering the command: apic --ext-version.

Command stability

Some commands are identified as Stability: prototype in the command help text (and in the tables later in this topic). These commands are not production quality, but are provided for testing and customer feedback. The syntax and functionality of these commands will likely change before they are released as production quality.

Authenticating

Use the apic login command to authenticate to an API Manager endpoint, and the

apic
logout

command to remove your local authentication credentials.

Note: When you authenticate successfully, your credentials are stored, in plain text, in the file [Icon indicating that this applies on Linux platforms]

.netrc or

_netrc. You should therefore set the file permissions in such a way that your credentials are not accessible by others.

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: You can set a configuration variable locally (the default) to affect only the current LoopBack® project, or globally (with command-line option -g), to affect all projects. The local value supersedes the global value. You can set local configuration variables only for LoopBack projects. When you set configuration variables for OpenAPI projects, they are always global.

The values of local configuration variables are stored in the project-root/.apiconnect/config file, where project-root is the project root directory. 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.

The following table describes the configuration variables:

Table 1. Configuration variables
Variable name	Description	Use instead of (or override with) option...
accessibility-mode	Enable accessibility mode. To enable accessibility features, set to `enabled`. Accessibility features make the tools easier to use for those with limited eyesight.	N/A
app	Default app URI for all commands that manage aspects of an app. Form: `apic-app://mgmt-server/orgs/org-name/apps/app-name`, where `mgmt-server` is the management server, `org-name` is the organization name, and `app-name` is the Catalog name.	--app
catalog	Default Catalog URI for all commands that manage aspects of a Catalog. Form: `apic-catalog://mgmt-server/orgs/org-name/catalogs/catalog-name`, where `mgmt-server` is the management server, `org-name` is the organization name, and `catalog-name` is the Catalog name. Note: The Catalog name `apic-dev` is reserved for local testing.	--catalog
log-level	Level of logging detail for the local application and Micro Gateway. Must be one of: `debug` - Verbose logging full debugging information. `info` - Log messages of "info" level and more severe. `warning` - Log only messages of "warning" level or more severe. `error` - Log only messages of "error" level and more severe. `fatal` - Log only messages of "fatal" (the most severe) level. Important: IBM API Connect Micro Gateway is deprecated in IBM API Connect Version 5.0.8 in favor of DataPower® Gateway. From 1 April 2020, Micro Gateway, and associated toolkit CLI commands, will no longer be supported. Existing users can migrate their API definitions to IBM DataPower Gateways. For information on supported API policies, see Built-in policies.	N/A
org	Default org URI for all commands that manage organizations. Form: `apic-org://mgmt-server/orgs/org-name`, where `mgmt-server` is the management server, `org-name` is the organization name. The `mgmt-server` portion sets the default value of the `--server` option. You can append the port number to the server name if it is not the default value of 443.	--organization, --server
space	Default Space URI for all commands that manage aspects of a Space. Form: `apic-space://mgmt-server/orgs/org-name/catalogs/catalog-name/spaces/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
template-default-api	Default API template to use. Specify base file name of Handlebars (.hbs) file.	--template
template-default-product	Default Product template to use. Specify base file name of Handlebars (.hbs) file.	--template
template-path	Space-delimited list of absolute local directory paths containing Handlebar templates.	--template

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=apic-catalog://mgmtnhost.com/orgs/climbon/catalogs/sb

Configuring the command-line tool to use TLS certificates

API Manager uses TLS profiles to secure data transmission. For information on how to create a TLS profile in API Manager, see TLS profiles.

To configure the toolkit command-line tool to use certificates to communicate with an API Manager that has TLS profiles enabled, follow these steps:

Set the trust-store configuration variable to the name of the certificate file used in the server's trust store of the TLS profile by entering this command:
```
apic config:set trust-store=<cert-file>
```
Where <cert-file> is the absolute file path to the TLS certificate file.
Set the value of the NODE_EXTRA_CA_CERTS environment variable to extend Node’s built-in CA certificate store by entering this command:
```
export NODE_EXTRA_CA_CERTS=<cert-file>
```
Where <cert-file> is the absolute file path to the TLS certificate file.

For more information about the NODE_EXTRA_CA_CERTS environment variable, see Node.js documentation.

Creating and managing local files

You create and work with API and Product definition YAML files locally before you stage them to API Manager.

To create a local API definition file, use the apic create --type api command. To create a local Product definition file, use the apic create --type product command.

Use the apic apis and apic products commands to list API Manager artifacts of the specified type.

To validate the syntactical correctness of a local API or Product definition file, use the apic validate command.

To create a draft API or Product in API Manager from a local API or Product definition file, use the apic drafts:push command.

To stage and publish a locally defined application, Product, and its referenced APIs to a Catalog in API Manager, use the apic publish and apic apps:publish commands.

If Spaces are enabled for a Catalog, Products can be staged and published only to a Space within that Catalog. To publish to a Space, the --scope space option must be included in the publish command, for example:

apic publish --scope space product.yaml --space space --catalog catalog --organization organization --server server

where

product is the name of the product that you want to publish.
space is the name of the Space to publish to.
catalog is name of the Catalog that contains the Space.
organization is the name of the organization.
server is the management server; portnumber is optional (default is 443).

Note: If the OpenAPI (Swagger 2.0) file that defines your API uses a $ref field to reference a fragment of OpenAPI (Swagger 2.0) code that is defined in a separate file, the $ref field is replaced with the contents of the target file before an API is validated, created in draft, staged, or published. For more information, see

Using $ref to reuse code fragments in your OpenAPI (Swagger 2.0) files.

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 --disable-analytics

Listing API Manager items

Use these commands to list items of the specified type:

apic apps
apic catalogs
apic drafts
apic orgs
apic props
apic services
apic spaces
apic extensions

Working with drafts

To work directly with draft APIs and Products, use the apic drafts:action command, where action is the action that you want to perform. For example, to publish a draft Product, and its referenced draft APIs, to a Catalog, use the apic drafts:publish command.

To create a local API or Product definition file from a draft API or Product, use the apic drafts:pull command.

To create local API or Product definition files from all the draft APIs and Products, use the apic drafts:clone command.

Note: You can publish a Product and its referenced APIs directly to a Catalog by using the apic products:publish command. You do not have to first create draft Products and APIs.

Working with Catalogs and Spaces

To create a Catalog, use the apic catalogs:create command. To view information on a Catalog, use the apic catalogs:get command; to list all Catalogs contained in organizations that the currently authenticated user is a member of, use the apic catalogs command. [V5.0.8 or later] Beginning with Version 5.0.8.4, you can transfer the ownership of a Catalog to another user by using the apic catalogs:transfer command.

[V5.0.5 or later] You can use a Space to partition a Catalog so multiple teams can manage Products and APIs independently in a single Catalog. A Space is conceptually like a sub-catalog, except that Products and APIs in all Spaces in a given Catalog are published to the same developer portal. For more information about Spaces, see Using syndication in IBM API Connect®.

To enable Spaces for a Catalog, use the following command:

apic catalogs:set catalog_name --spaces enabled

Note: If Spaces are enabled for a Catalog, Products can be published only to a Space within that Catalog.

Use the toolkit apic spaces commands to create and manage Spaces:

apic spaces - List Spaces contained in a Catalog.
apic:spaces create - Create a Space in a Catalog.
apic:spaces get - Get information on a Space in a Catalog.
apic:spaces set - Set information on a Space in a Catalog.
apic:spaces delete - Delete a Space in a Catalog.

To work directly with Products, apps, and APIs in a Catalog or Space, use the apic products, apic apps, and apic apis commands. For example, to update a Product, use the apic products:set command. If you need to specify the Space upon which to act, you must include the --scope space option in the command.

Command summary

The following tables summarize apic commands. The general command syntax is:

apic command:sub-command [argument] [options]

where command is the command, for example config, sub-command is the sub-command, where applicable (for example get), argument is the argument, where applicable (for example,catalog), and options is one or more options, where applicable (for example,--local). Some apic commands don't have sub-commands or arguments. For some commands, options are required. The full example command is:

apic config:get catalog --local

Note: The create command has a slightly different syntax:

apic create --type sub-command [options]

Some of the commands in the following tables are annotated with Stability: prototype, which indicates that IBM is in the process of collecting customer feedback on the commands and you should not use them in production scripts.

You can use a template to create an API or Product by running the following command:

apic create --type [api | product] --template template_filename --title new_title

where the template_filename is the name of the Handlebars template to use. The template must have an .hbs file name extension. Alternatively, when you create an API or Product interactively, you can specify a template. For more information, see Creating and using API and Product definitions templates.

Table 2. Summary of general-purpose apic commands
Command	Description	Sub-commands
`apic config`	List and manage configuration variables. For more information, see Using configuration variables. With no sub-command, lists values of defined configuration variables.	`get` - Get a configuration variable. `list` - List configuration variables (default). `set` - Set configuration variables. `delete` - Delete a configuration variable. `clear` - Delete all configuration variables
`apic create`	Create project artifacts.	`--type api` - Create an API. `--type api --wsdl filename` - Create a SOAP API from a WSDL definition file, or a .zip file that contains the WSDL definition files for a service. The name and version of the generated API are obtained from the WSDL file. `--type product` - Create a Product. `--type model` - Create a LoopBack model. `--type datasource` - Create a LoopBack data source. Note: You can create an API or Product from an OpenAPI (Swagger 2.0) template file by using the `--template template-name` option.
`apic edit`	Run the API Designer and open in default web browser.	None
`apic extensions`	Manage OpenAPI (Swagger 2.0) extensions in a catalog. With no sub-command, lists the extensions in the production catalog. Stability: prototype	`clone` - Pull all extensions from a catalog. `delete` - Delete an extension in a catalog. `get` - Get information on an extension in a catalog. `list` - List all extensions published to a catalog (default). `publish` - Publish an extension to a catalog. `pull` - Pull an extension from a catalog.
`apic loopback`	Create LoopBack project and project artifacts. With no sub-command, creates a new LoopBack project. All of these commands are Stability: prototype, except for `loopback:app`.	`acl` - Add access control list specification. `app` - Create a new LoopBack project (default). `boot-script` - Add boot script. `export-api-def` - Generate OpenAPI (Swagger 2.0) definitions from models. `middleware` - Add middleware function. `property` - Add property to existing model. `refresh` - Update Product and API definition from a model. `relation` - Add relation between models. `remote-method` - Add remote method `swagger` - Generate LoopBack project from an OpenAPI (Swagger 2.0) definition.
`apic microgateway`	Create Micro Gateway applications. Important: IBM API Connect Micro Gateway is deprecated in IBM API Connect Version 5.0.8 in favor of DataPower Gateway. From 1 April 2020, Micro Gateway, and associated toolkit CLI commands, will no longer be supported. Existing users can migrate their API definitions to IBM DataPower Gateways. For information on supported API policies, see Built-in policies.	None
`apic validate`	Validate API or Product definition YAML file.	None

Table 3. Summary of apic commands to manage and test applications locally
Command	Description	Sub-commands
`apic logs`	Display server logs continuously to console.	None
`apic props`	List and manage service properties for a LoopBack application running locally. With no sub-command, lists values of defined service properties.	`get` - Get a property value. `list` - List all property values (default). `set` - Set or update property values. `delete` - Delete a service property. `clear` - Delete all service properties.
`apic services`	List and manage services. With no sub-command, lists all services that are currently executing.	`list` - List all services currently executing (default) `start` - Start a service. `stop` - Stop a service. `logs` - Display logs to console. `get` - Get information about a service.
`apic start`	If run in LoopBack project directory, start the LoopBack application; otherwise, start the Micro Gateway. Important: IBM API Connect Micro Gateway is deprecated in IBM API Connect Version 5.0.8 in favor of DataPower Gateway. From 1 April 2020, Micro Gateway, and associated toolkit CLI commands, will no longer be supported. Existing users can migrate their API definitions to IBM DataPower Gateways. For information on supported API policies, see Built-in policies.	None
`apic stop`	Stop the specified service or all services.	None
`apic explore`	Opens the API Explore tool. Shows the operations, definitions, and documentation for all of the APIs that are contained in the project directory. To specify a particular API, include the name of the API in the command, for example: `apic explore apiname.yaml`	Option: `-e, --external` Opens the Explore tool on 0.0.0.0 instead of the default 127.0.0.1. This option binds the server to all IP addresses on the machine, and makes the tool accessible on the wider network.

Table 4. Summary of apic commands to manage APIs, apps, Products, and Catalogs, and publish them to the cloud
Command	Description	Sub-commands
`apic apps`	List, manage, or publish applications. Default sub-command is `list`.	`get` - Get information about an application. `build` - Build an application. `list` - List provider apps contained in organizations of which the currently-authenticated user is a member (default sub-command). `publish` - Publish an application to a provider app. `set` - Update an application.
`apic apis`	List and manage APIs in a Catalog or Space.Stability: prototype Default sub-command is `list`.	`clone` - Pull all APIs from a Catalog or Space - Build an application. `get` - Get information on an API in a Catalog or Space. The output separately lists the production and development endpoints at which an application can call the API. For more information, see Managing the application lifecycle. `list` - List APIs in a Catalog or Space (default sub-command). `pull` - Pull an API from a Catalog or Space. `set` - Update an API in a Catalog or Space.
`apic catalogs`	List and manage Catalogs.	`catalogs:create` Create a Catalog in an organization `catalogs:delete` Delete a Catalog in an organization `catalogs:get` Get information on a Catalog in an organization `catalogs:list` - List Catalogs contained in organizations of which the currently-authenticated user is a member (default sub-command). `catalogs:transfer` - Beginning with Version 5.0.8.4: Transfers the ownership of a Catalog to another user.
`apic devapps`	List and get information about consumer applications. Default sub-command is `list`.	`get` - Get information about a consumer application. `list` - List consumer apps in an organization and a Catalog.
`apic drafts`	List and manage APIs and Products in drafts. Default sub-command is `list`.	`clear` - Delete all API and Product definitions in drafts. `clone` - Pull all API and Product definitions from drafts. `delete` - Delete an API or Product definition from drafts. `list` - List APIs and Products in drafts (default sub-command). `get` - Get information on an API or Product definition in drafts. `publish` - Stage and publish a Product and its referenced APIs in drafts to a Catalog. `pull` - Pull API or Product definitions from drafts. `push` - Push local API or product definitions to drafts.
`apic login`	Log in to API Manager.	None. Specify server and credentials with the required flags: `-u, --username` `user_name` `-p, --password` `password` `-s, --server` `mgmt_server`. You can append the port number to the server name if it is not the default value of 443.
`apic logout`	Log out from API Manager.	None. Specify server with the required flag: `-s, --server` `mgmt_server`. You can append the port number to the server name if it is not the default value of 443.
`apic members`	List members in an organization. Stability: prototype	None
`apic orgs:get`	Display information on a consumer or provider organization. Use `--type provider\|consumer` to specify either provider or consumer organization.	`get` - Display information on a consumer or provider organization.
`apic organizations` `apic orgs`	List and get information about organizations. Default sub-command is `list`. Note: The `organizations` command available in early releases is deprecated in favor of `orgs`.	`get` - Get information on a provider organization. `list` - List organizations of which the currently-authenticated user is a member. On IBM Cloud, lists only organizations where the API Management tile is provisioned and added.
`apic policies`	List and manage policies in a Catalog. Default sub-command is `list`.	`clone` - Pull all policies from a Catalog. `delete` - Delete a policy from a Catalog. `get` - Get information on a policy in a Catalog. `list` - List policies in a Catalog (default sub-command). `publish` - Publish a policy to a Catalog. `pull` - Pull a policy from a Catalog.
`apic publish`	Publish a Product and its referenced APIs to a Catalog. If Spaces are enabled for a Catalog, Products can be published only to a Space within that Catalog. To publish to a Space, the `--scope space` option must be included in the publish command.	None. This is an alias for `apic products:publish`.
`apic products`	List and manage Products in a Catalog. Default sub-command is `list`.	`clear` - Clear all Products in a Catalog. Stability: prototype `clone` - Pull all Product definitions from a Catalog. Stability: prototype `delete` - Delete a Product in a Catalog. `get` - Get information on a Product in a Catalog. `list` - List Products in a Catalog (default sub-command). `publish` - Stage and publish Product and referenced APIs to a Catalog. `pull` - Pull a Product from a Catalog. `replace` - Replace a Product in a Catalog with another Product . Stability: prototype `set` - Update a Product in a Catalog. `set-migration-target` - Set migration target of a Product in a Catalog with another Product. Stability: prototype `supersede` - Supersede a Product in a Catalog with another Product. Stability: prototype
`apic spaces`	List and manage Spaces contained in a Catalog. Default sub-command is `list`.	`spaces:create` Create a Space in a Catalog `spaces:delete` Delete a Space in a Catalog. `spaces:get` Get information on a Space in a Catalog. `spaces:list` List Spaces contained in a Catalog (default sub-command). `spaces:set` Set information on a Space in a Catalog.
`apic subscriptions`	List and manage subscriptions in a Product or a Catalog. Default sub-command is `list`.	`subscriptions:get` - Get information on a subscription in an app. `subscriptions:list` List Spaces contained in a Catalog (default sub-command). Stability: prototype