CLI for API Management Products
npm install @apistudio/apim-cliAPIM CLI provides the Command Line Interface (CLI) support for API Management. In API Studio you can build, deploy, and test the deployed assets by using APIM CLI. These following sections describe operations that you can do such as build, deploy, and test by using the CLI with some examples.
Make sure that you have Node.js, whose version is higher than 20.15.0 and less than 21.0.0, installed before you install APIM CLI.
Run the following command in the command line to install APIM CLI.
``sh`
npm install -g @apistudio/apim-cli
- apic build
- Building a single project
- Building multiple projects
- Building all projects in the local directory
- Building an API
- Building a project without --output
- apic deploy
- Deploying a single project
- Deploying multiple projects
- Deploying all projects
- Deploying an API
- apic test
- Testing a single project
- Testing multiple projects
- Testing all projects
- Testing an API
- Testing a project by overwriting the environment configuration
- Testing a project using endpoints
- apic help
This operation builds and archives the specified project assets. APIs can have external dependencies referenced, hence when you build a project it includes all these references provided in the local folder.
Syntax
`sh`
apic build [options][projects]
Specifies the projects in the local folder you want to build. You can provide multiple projects by providing comma separated project names as input.
The following table lists all available options for the apic build command and their descriptions.
Options
Description
| Command | Description |
|----------------------|--------------|
| -l, --localDir | Path of the local folder of the specified studio projects. This argument is mandatory. |-a, --all
| | Use --all to include all projects in the given local directory. If you do not want to build all projects in the given local directory, then specify the project name that is required. |-n, --names
| | Specify the API kind in the format namespace:apiname:version. You can provide multiple asset names as comma-separated entries. Studio supports only API assets. |-o, --output build_output_path
| | Provide the name and path where the output zip file should be stored. If you do not specify the path, the built project is stored in the directory from where you run the command. |-d, --debug
| | Enables the debug mode. |-h, --help
| | Displays help for the build command. |
`sh`
apic build Projectname --localDir local_dir_path --output build_output_path
Example
`sh`
apic build Project1 --localDir /Users/user1/Desktop/apistudio_localdir --output ./builds/project_build.zip
Builds a project project_build.zip from a single project file, Project1, located in the local directory /Users/user1/Desktop/apistudio_localdir and places it in the /builds folder.
Outcome
As the build progresses, it lists the assets added. On successful completion you will see the message Build completed successfully!. In addition it displays the locaton where the build is placed.
In case of any errors, a deployment failure messgae with the reason for failure is displayed so you can take the corrective action.
`sh`
apic build Project1 --localDir /Users/user1/Desktop/apistudio_localdir --output ./builds/project_build.zip
`sh`
apic build Projectname1,Projectname2 --localDir local_dir_path --output build_output_path
Example
`sh`
apic build Project1,Project2 --localDir /Users/user1/Desktop/apistudio_localdir --output ./builds/project_build.zip
Builds a project project_build.zip from two project files, Project1 and Project2, located in the local directory /Users/user1/Desktop/apistudio_localdir and places it in the /builds folder.
Outcome
As the build progresses, it lists the assets added. On successful completion you will see the message Build completed successfully!. In addition it displays the locaton where the build is placed.
In case of any errors, a deployment failure messgae with the reason for failure is displayed so you can take the corrective action.
`sh`
apic build --all --localDir local_dir_path --output build_output_path
Example
`sh`
apic build --all --localDir /Users/user1/Desktop/apistudio_localdir --output ./builds/project_build.zip
Builds a project project_build.zip by bundling all the projects located in the local directory /Users/user1/Desktop/apistudio_localdir and places it in the /builds folder.
Outcome
As the build progresses, it lists the assets added. On successful completion you will see the message Build completed successfully!. In addition it displays the locaton where the build is placed.
In case of any errors, a deployment failure messgae with the reason for failure is displayed so you can take the corrective action.
`sh`
apic build Projectname1 --names namespace:name:version --localDir local_dir_path --output build_output_path
Example
`sh`
apic build Project1 --names dev:TestPayments:1.0 --localDir /Users/user1/Desktop/apistudio_localdir --output ./builds/project_build.zip
Builds an API project_build.zip from a single API file specified by its name dev:TestPayments:1.0 located in the local directory /Users/user1/Desktop/apistudio_localdir and places it in the /builds folder.
Outcome
As the build progresses, it lists the assets added. On successful completion you will see the message Build completed successfully!. In addition it displays the locaton where the build is placed.
In case of any errors, a deployment failure messgae with the reason for failure is displayed so you can take the corrective action.
`sh`
apic build Projectname --localDir local_dir_path
Example
`sh`
apic build Project1 --localDir /Users/user1/Desktop/apistudio_localdir
Builds a project project_build.zip from the project file, Project1, located in the local directory /Users/user1/Desktop/apistudio_localdir. When you do not provide the --output option, APIM CLI builds it with a fixed standard package name, for example, studio-projectname-build.zip and archives it in the same location from where the command is run.
Outcome
As the build progresses, it lists the assets added. On successful completion you will see the message Build completed successfully!. In addition it displays the locaton where the build is placed.
In case of any errors, a deployment failure messgae with the reason for failure is displayed so you can take the corrective action.
This operation deploys the build API Gateway.
Syntax
`sh`
apic deploy [options][projects]
projects. Specifies the projects in the local folder you want to deploy. You can provide multiple projects by providing comma separated project names as input.
The following table lists all available options for the apic deploy command and their descriptions.
Options
Description
| Commands | Description |
|-----------------------------|--------------|
| -l, --localDir | Path of the local folder of the specified studio projects. This is a mandatory argument. |-a, --all
| | Use --all to include all projects in the given local directory. If you do not want to build all projects in the given local directory, then specify the project name that is required. |-n, --names
| | Specify the API kind in the format namespace:apiname:version. You can provide multiple asset names as comma-separated entries as input. Studio supports only API assets. |-a, --archive archive
| | Specify the archive to be deployed. |-t, --target target
| | Specify the endpoint of the API Gateway instance to which the asset has to be deployed. This is a mandatory argument. |-u, --username username
| | Provide the username of the API Gateway instance to which the asset is deployed. This user must have Manage APIs functional privilege. This is a mandatory argument. |-pwd, --password password
| | Provide the password of the API Gateway instance to which the asset is deployed. If you do not provide the password, CLI prompts for the password, where you can provide the masked password. |-ow, --overwrite
| | Specify if you want to overwrite the existing assets on the API Gateway instance where the specified asset is being deployed. |-d, --debug
| | Enables the debug mode. |-h, --help
| | Displays help for the build command. |
`sh`
apic deploy Projectname --localDir local_dir_path --target "http://host:port"
--username username --password password --overwrite
Example
`sh`
apic deploy Project1 --localDir /Users/user1/Desktop/apistudio_localdir --target "http://host:port" --username "" --password "" --overwrite
Deploys a single project file, Project1, located in the local directory /Users/user1/Desktop/apistudio_localdir to the specified API Gateway instance. If there is any identical asset in the API Gateway instance then the overwrite argument helps in overwriting that asset.
Outcome
As the deployment progresses, it lists the asset being added followed by deployment status of the asset. On successful deployment you will see the deployment success message Deployment to api gateway is successful!. In addition the gateway endpoints of the APIs in the project is displayed.
In case of any errors, a deployment failure messgae with the reason for failure is displayed so you can take the corrective action.
`sh`
apic deploy Projectname1,Projectname2
--localDir local_dir_path
--target "http://host:port"
--username username --password password --overwrite
Example
`sh`
apic deploy Project1,Project2 --localDir /Users/user1/Desktop/apistudio_localdir
--target "http://host:port"
--username "" --password "" --overwrite
Deploys two projects from two project files, Project1 and Project2, located in the local directory /Users/user1/Desktop/apistudio_localdir to the specified API Gateway instance. If there is any identical asset in the API Gateway instance then the overwrite argument helps in overwriting that asset.
Outcome
As the deployment progresses, it lists the assets being added followed by deployment status of the assets. On successful deployment you will see the deployment success message Deployment to api gateway is successful!. In addition the gateway endpoints of the APIs in the projects is displayed.
In case of any errors, a deployment failure messgae with the reason for failure is displayed so you can take the corrective action.
`sh`
apic deploy --all --localDir local_dir_path
--target "http://host:port"
--username username --password password --overwrite
Example
`sh`
apic deploy --all --localDir /Users/user1/Desktop/apistudio_localdir
--target "http://host:port"
--username "" --password "" --overwrite
Deploys all projects located in the local directory /Users/user1/Desktop/apistudio_localdir to the specified API Gateway instance. If there is any identical asset in the API Gateway instance then the overwrite argument helps in overwriting that asset.
Outcome
As the deployment progresses, it lists the assets being added followed by deployment status of the assets. On successful deployment you will see the deployment success message Deployment to api gateway is successful!. In addition the gateway endpoints of the APIs in the project is displayed.
In case of any errors, a deployment failure messgae with the reason for failure is displayed so you can take the corrective action.
`sh`
apic deploy Projectname1 --names namespace:name:version
--localDir local_dir_path --target "http://host:port"
--username username --password password --overwrite
Example
`sh`
apic deploy Project1 --names dev:TestPayments:1.0
--localDir '/Users/user1/Desktop/apistudio_localdir' --target 'http://host:port'
--username "" --password "" --overwrite
Deploys an API specified by its name dev:TestPayments:1.0, located in the local directory /Users/user1/Desktop/apistudio_localdir to the specified API Gateway instance. If there is any identical asset in the API Gateway instance then the overwrite argument helps in overwriting that asset.
Outcome
As the deployment progresses, it lists the asset being added followed by deployment status of the assets. On successful deployment you will see the deployment success message Deployment to api gateway is successful!. In addition the gateway endpoint of the API is displayed.
In case of any errors, a deployment failure messgae with the reason for failure is displayed so you can take the corrective action.
`sh`
apic deploy --archive --localDir local_dir_path
--target "http://host:port"
--username username --password password --overwrite
Example
`sh`
apic deploy --archive /Users/user1/Desktop/apistudio_localdir/build.zip
--target "http://host:port" --username "" --password "**"
--overwrite
Deploys an archive, build.zip, located in the local directory /Users/user1/Desktop/apistudio_localdir to the specified API Gateway instance. If there is any identical asset in the API Gateway instance then the overwrite argument helps in overwriting that asset.
Outcome
As the deployment progresses, it lists the assets being added followed by deployment status of the assets. On successful deployment you will see the deployment success message Deployment to api gateway is successful!. In addition the gateway endpoints of the APIs in the project is displayed.
In case of any errors, a deployment failure messgae with the reason for failure is displayed so you can take the corrective action.
This operation tests the projects deployed to API Gateway.
Syntax
`sh`
apic test [options][projects]
projects. Specifies the projects in the local folder that have to be tested. You can provide multiple projects by providing comma separated project names as input.
The following table lists all available arguments for the apic test command and their descriptions.
Argument
Description
| Command | Description |
|--------------------------------|--------------|
| -l, --localDir localDirpath | Path of the local folder of the specified studio projects. This is a mandatory argument. |-a, --all
| | Use --all to include all projects in the given local directory. If you do not want to build all projects in the given local directory, then specify the project name that is required. |-t, --target target
| | Specify the endpoint of the API Gateway instance to which the asset has to be deployed. |-n, --names
| | Specify the API kind in the format namespace:apiname:version. You can provide multiple asset names as comma-separated entries as input. Studio supports only API assets. |-u, --username username
| | Provide the username of the API Gateway instance to which the asset is deployed. This user must have Manage APIs functional privilege. This is a mandatory argument. |-pwd, --password password
| | Provide the password of the API Gateway instance to which the asset is deployed. If you do not provide the password, CLI prompts for the password, where you can provide the masked password. |-de, --deploy
| | Deploys the projects or the specified asset to API Gateway during testing. |-e, --env key=value
| | Adds or overwrites the environment configuration values in the environment asset file. For example, key1=value1,key2=value2. |-en, --endpoints
| | Tests the specified API, as defined by the --names parameter, against the --endpoint value where it is already deployed. |-d, --debug
| | Enables the debug mode. |-h, --help
| | Displays help for the build command. |
`sh`
apic test Projectname --localDir local_dir_path
Example
`sh`
apic test Project1 --localDir /Users/user1/Desktop/apistudio_localdir
Tests the project, Project1, located in the local directory /Users/user1/Desktop/apistudio_localdir.
Outcome
As the tests start, it displays the asset added and a list of gateway endpoints of the APIs in the project. On successful execution of all tests you will see you will see the message Test executed successully.... In addition, it displays the number of tests passed, number of tests failed and the Test status. You would also see the details of each test such as resource, assertion, status and in case of a failed test an appropriate message with the reason for failure.
`sh`
apic test Projectname1,Projectname2 --localDir local_dir_path
Example
`sh`
apic test Project1,Project2 --localDir /Users/user1/Desktop/apistudio_localdir
Tests the projects, Project1 and Project2, located in the local directory /Users/user1/Desktop/apistudio_localdir.
Outcome
As the tests start, it displays the assets added and a list of gateway endpoints of the APIs in the project. On successful execution of all tests you will see you will see the message Test executed successully.... In addition, it displays the number of tests passed, number of tests failed and the Test status. You would also see the details of each test such as resource, assertion, status and in case of a failed test an appropriate message with the reason for failure.
`sh`
apic test --all --localDir local_dir_path
Example
`sh`
apic test --all --localDir /Users/user1/Desktop/apistudio_localdir
Tests all the projects located in the local directory /Users/user1/Desktop/apistudio_localdir.
Outcome
As the tests start, it displays the asset added and a list of gateway endpoints of the APIs in the project. On successful execution of all tests you will see you will see the message Test executed successully.... In addition, it displays the number of tests passed, number of tests failed and the Test status. You would also see the details of each test such as resource, assertion, status and in case of a failed test an appropriate message with the reason for failure.
`sh`
apic test Projectname --names namespace:name:version --localDir local_dir_path
Example
`sh`
apic test Project1 --names dev:TestPayments:1.0 --localDir /Users/user1/Desktop/apistudio_localdir
Tests an API specified by its name dev:TestPayments:1.0, located in the local directory /Users/user1/Desktop/apistudio_localdir.
Outcome
As the tests start, it displays the asset added and a list of gateway endpoint of the API. On successful execution of all tests you will see you will see the message Test executed successully.... In addition, it displays the number of tests passed, number of tests failed and the Test status. You would also see the details of each test such as resource, assertion, status and in case of a failed test an appropriate message with the reason for failure.
`sh`
apic test Projectname --localDir local_dir_path --env key=value
Example
`sh`
apic test Project1 --localDir /Users/user1/Desktop/apistudio_localdir --env Content-Type=application/json,petId=1
Tests a project, Project1, located in the local directory /Users/user1/Desktop/apistudio_localdir using the environment configuration values provided in the environment asset file.
Outcome
As the tests start, it displays the asset added and a list of gateway endpoints of the APIs in the project. On successful execution of all tests you will see the message Test executed successully.... In addition, it displays the number of tests passed, number of tests failed and the test status. You would also see the details of each test such as resource, assertion, status and in case of a failed test an appropriate message with the reason for failure.
`sh`
apic test Projectname --names namespace:name:version --localDir local_dir_path --endpoints endpoint
Example
`sh`
apic test Project1 --names dev:TestPayments:1.0 --localDir /Users/user1/Desktop/apistudio_localdir
--endpoints http://host:port/gateway/ProductAPI10/1.0
Tests a project, Project1, located in the local directory /Users/user1/Desktop/apistudio_localdir using the API endpoint http://host:port/gateway/ProductAPI10/1.0.
Outcome
As the tests start, the display shows the added assets. When all tests run successfully, the message Test executed successully... appears. Additionally, it shows the number of tests passed, the number failed, and the overall test status. You can view details for each test, including the resource, assertion, status, and, for any failed test, an error message explaining the reason for failure.
`sh`
apic test Projectname --localDir local_dir_path --target "http://host:port" --username username --password password --deploy
Example
`sh`
apic test Project1 --localDir C:/Users/user1/Desktop/apistudio_localdir --target "http://host:port"
--username "" --password "" --deploy
Deploys the project, Project1, located in the local directory /Users/user1/Desktop/apistudio_localdir to the specified API Gateway instance. On successful deployment it tests the deployed project.
Outcome
As the tests start, it displays the asset added and a list of gateway endpoints of the APIs in the project. On successful execution of all tests you will see you will see the message Test executed successully.... In addition, it displays the number of tests passed, number of tests failed and the Test status. You would also see the details of each test such as resource, assertion, status and in case of a failed test an appropriate message with the reason for failure.
Displays help for the specified command.
Syntax
`sh`
apic help command_name
Example: Viewing help for the deploy command.
`sh`
apic help deploy
Outcome. This lists the help for the deploy command as follows:
Usage: apic deploy [options] [projects]
deploy the projects or the specified archive to API Gateway
Options:
| Command | Description |
|--------------------------------|--------------|
| -l, --localDir | Path of the local directory of the specified project asset. For example, C:\local_dir. |-a, --all
| | Deploys all projects existing in the local directory. |-n, --names
| | Deploys the specified API asset kind. For example, dev:paymentAPI:1.0. |-ar, --archive
| | Deploys the specified archive. For example, C:\dir\build.zip. |-t, --target
| | Endpoint of the API Gateway instance to which the asset has to be deployed. |-u, --username
| | Username of the API Gateway instance to which the asset has to be deployed. |-pwd, --password
| | Password of the API Gateway instance to which the asset has to be deployed. |-ow, --overwrite
| | Overwrites the existing assets on the API Gateway instance where the specified asset is being deployed. |-d, --debug
| | Enables debug mode. |-h, --help` | Displays help for the command. |
|