Toolkit command summary
A summary of the core commands in the IBM® API Connect developer toolkit.
- 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
apic login
command to authenticate to an API Manager endpoint, and the apic
logout
command to remove your local authentication credentials.Using configuration variables
-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. Useapic config
to display the values of all local configuration variables orapic 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:
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:
|
--app |
catalog | Default Catalog URI for all commands that manage aspects of a Catalog. Form:
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:
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: The mgmt-server portion sets the default value of the 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:
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 |
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:
Whereapic config:set trust-store=<cert-file>
<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:
Whereexport NODE_EXTRA_CA_CERTS=<cert-file>
<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.
--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).
$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
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.apic --disable-analytics
Listing API Manager items
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.
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. 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.
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®.
apic catalogs:set catalog_name --spaces enabled
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
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
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.
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.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. |
|
apic create |
Create project artifacts. |
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 |
|
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
|
|
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 |
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. |
|
apic services |
List and manage services. With no sub-command, lists all services that are currently executing. |
|
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:
|
Option:
|
Command | Description | Sub-commands |
---|---|---|
apic apps |
List, manage, or publish applications. Default sub-command is
|
|
apic apis |
List and manage APIs in a Catalog or Space.Stability: prototype Default sub-command is |
|
apic catalogs |
List and manage Catalogs. |
|
apic devapps |
List and get information about consumer applications. Default sub-command is
|
|
apic drafts |
List and manage APIs and Products in drafts. Default sub-command is
|
|
apic login |
Log in to API Manager. | None. Specify server and credentials with the required flags:
|
apic logout |
Log out from API Manager. | None. Specify server with the required flag:
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. |
|
apic organizations
|
List and get information about organizations. Default sub-command is Note: The
organizations command available in early releases is deprecated in favor
of orgs . |
|
apic policies |
List and manage policies in a Catalog. Default sub-command is
|
|
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
|
None. This is an alias for |
apic products |
List and manage Products in a Catalog. Default sub-command is
|
|
apic spaces |
List and manage Spaces
contained in a Catalog. Default sub-command is |
|
apic subscriptions |
List and manage subscriptions in a Product or a Catalog. Default sub-command is
|
|