General IBM Cloud CLI (ibmcloud) commands

The IBM Cloud® Command Line Interface provides a set of commands that are grouped by namespace for users to interact with IBM Cloud.

The IBM Cloud CLI supports the following commands, including their names, arguments, options, prerequisites, descriptions, and examples.

Global prerequisites

The prerequisites for each command describe which actions are required before you run the command. The prerequisites can include one or more of the following actions:

Endpoint: Use the ibmcloud api command to set an API endpoint.
Log in: Use the ibmcloud login command to log in. If you log in with a federated ID, use the --sso option to authenticate with a one-time passcode. Or use the --apikey option to authenticate with an API key.
Target: Use the ibmcloud target command to set or view the target account or region.

Global options

The following options are available for most commands in the IBM Cloud CLI. To check whether an option is available for a specific command, use the -h, --help option with the command.

`--output FORMAT`

Specifies an output format. Only JSON is supported.

Examples

Print available resource groups in JSON format:

ibmcloud resource groups --output json

`-q, --quiet`

Suppresses verbose messages. Prompt messages like Getting information from... as ... do not display if -q, --quiet is specified.

Examples

Print available resource groups in quiet mode:

ibmcloud resource groups -q

ibmcloud help

Displays the general help for first-level built-in commands and supported namespaces of IBM Cloud CLI, or the help for a specific built-in command or namespace.

ibmcloud help [COMMAND|NAMESPACE]

Prerequisites

None.

Command options

COMMAND|NAMESPACE: The command or namespace that help is displayed for. If not specified, the general help for IBM Cloud CLI is shown. Optional.

Examples

Display general help for the IBM Cloud CLI:

ibmcloud help

Display help for the dev command:

ibmcloud help dev

ibmcloud assist

Ask a question to the AI assistant that uses watsonx. For more information about the capabilities and limitations, see Getting help from the AI assistant.

ibmcloud assist "MY_QUERY"

Content that is generated by the AI assistant might include mistakes or be incorrect.

Prerequisites

Use the ibmcloud login command to log in. If you are logging in with a federated ID, use the --sso option to authenticate with a one-time passcode, or use the --apikey option to authenticate with an API key.

Command options

None.

Examples

ibmcloud assist "How do I update the CLI?"

If you're using quotations or exclamation marks as part of your query, make sure to escape each character by using \. For more information, see Using quotation marks with strings in IBM Cloud CLI.

ibmcloud version

Print the version of the IBM Cloud CLI.

ibmcloud version

Prerequisites

None.

Command options

None.

Examples

Print the version of the IBM Cloud CLI:

ibmcloud version

ibmcloud api

Set or view the IBM Cloud API endpoint.

ibmcloud api [API_ENDPOINT] [--unset] [--skip-ssl-validation] [--vpc]

Prerequisites

None.

Command options

API_ENDPOINT: The API endpoint that is targeted, for example, https://cloud.ibm.com. If both the API_ENDPOINT and --unset options aren't specified, the current API endpoint is displayed. Optional.
--skip-ssl-validation: Bypass SSL validation of HTTP requests. This option isn't recommended.
--vpc: Use a VPC connection for a private API endpoint. For more information about configuring to use a VPC connection for a private API endpoint, see Configuring a private endpoint gateway (required for VPC use).
--unset: Remove the API endpoint setting.

Examples

Set the API endpoint to cloud.ibm.com:

ibmcloud api cloud.ibm.com

Set the API endpoint to cloud.ibm.com and bypass SSL validation.

ibmcloud api https://cloud.ibm.com --skip-ssl-validation

View the current API endpoint:

ibmcloud api

Remove the API endpoint:

ibmcloud api --unset

ibmcloud config

Writes default values to the configuration file.

ibmcloud config --http-timeout TIMEOUT_IN_SECONDS | --trace (true|false|path/to/file) |
         --color (true|false) | --locale (LOCALE|CLEAR) | --check-version (true|false)

Prerequisites

None.

Command options

--check-version: Enable or disable CLI version checking. Valid values are true or false.
--color: Enable or disable color output. This option is disabled by default. Valid values are true or false.
--http-timeout: The timeout value for HTTP requests in seconds. The default value is 60 seconds.
--locale: Set a default locale. If no value is specified, the previous locale is deleted.
--sso-otp: Set the style of single sign-on (SSO) one-time passcode (OTP) retrieval. The default value is manual and requires user interaction. The auto setting will launch the default browser automatically and accept the token.
--trace: Trace HTTP requests to the terminal or specified file. Valid values are true or false.

You can specify only one of the options at a time.

Examples

Set the HTTP request timeout to 30 seconds:

ibmcloud config --http-timeout 30

Enable trace output for HTTP requests:

ibmcloud config --trace true

Trace HTTP requests to the /home/usera/my_trace file:

ibmcloud config --trace /home/usera/my_trace

Disable color output:

ibmcloud config --color false

Set the locale to zh_Hans:

ibmcloud config --locale zh_Hans

Clear the locale settings:

ibmcloud config --locale CLEAR

Enable automatic SSO one-time passcode acceptance:

ibmcloud config --sso-otp auto

ibmcloud login

ibmcloud login [-a API_ENDPOINT] [--sso] [-u USERNAME] [-p PASSWORD] [--apikey KEY | @KEY_FILE] [--cr-token (TOKEN | @CR_TOKEN_FILE) | --vpc-cri] [--profile PROFILE_ID | PROFILE_NAME | PROFILE_CRN] [-c (ACCOUNT_ID | ACCOUNT_OWNER_USER_ID) | --no-account] [--accept] [-g (RESOURCE_GROUP_NAME | RESOURCE_GROUP_ID)] [-r REGION | --no-region] [--vpc]

-a API_ENDPOINT: The API endpoint. For example, cloud.ibm.com. Or, use private.cloud.ibm.com to log in by using a private endpoint. Using this flag saves the API endpoint to the configuration file.
--sso: Specify this option to log in with a federated ID. Using this option prompts you to authenticate with your single sign-on provider and enter a one-time passcode to log in.
-u USERNAME: The user name. Optional.
-p PASSWORD: The user password. Optional.
--apikey API_KEY or @API_KEY_FILE_PATH: The API key content or the path of an API key file that is indicated by the @ symbol.
--cr-token TOKEN or @CR_TOKEN_FILE_PATH: The compute resource token content or the path of a compute resource token file that is indicated by the @ symbol. If provided, the --profile flag, or IBMCLOUD_CR_PROFILE environment variable, must also be provided or set.
--vpc-cri: Log in as a VPC VSI compute resource identity. For more information, see Logging in as a Virtual Server Instance Compute Resource Identity.
--profile PROFILE_ID, PROFILE_NAME, or PROFILE_CRN: The name, ID, or CRN of the linked trusted IAM profile is used when you obtain the IAM access token. If provided, the --cr-token flag, IBMCLOUD_CR_TOKEN environment variable, or --vpc-cri flag must also be provided or set. If you're authenticating as a VPC VSI compute resource, specifying only a trusted profile CRN or ID is supported.
-c ACCOUNT_ID: The ID of the target account. This option is exclusive with the --no-account option.
--no-account: Forced login without the account. This option isn't recommended, and it is exclusive with the -c option.
--accept: Accept an invitation to join the targeted account. The account that is provided must be a valid account ID.
-g RESOURCE_GROUP: The name or ID of the target resource group. Optional.
-r REGION: The name of the target region. For example, us-south or eu-gb.
--no-region: Forced login without targeting a region.
--skip-ssl-validation: Bypass the SSL validation of HTTP requests. This option isn't recommended.
--vpc: Use a VPC connection for a private API endpoint. For more information about logging in by using a VPC connection for a private API endpoint, see Logging in to the CLI with a private endpoint. For information about configuring a VPC connection to use a private API endpoint, see Configuring a private endpoint gateway (required for VPC use).

Log in interactively:

ibmcloud login

Log in to a private endpoint:

ibmcloud login -a private.cloud.ibm.com

Two regions are supported: us-south and us-east.

Log in with a username and password, and set a target account:

ibmcloud login -u username -p password -c MyAccountID

Log in with federated ID, and set a target account:

ibmcloud login --sso -c MyAccountID

Use an API key with an associated account:

ibmcloud login --apikey api-key-string

ibmcloud login --apikey @filename

Use an API key with no associated account:

ibmcloud login --apikey api-key-string -c MyAccountID

ibmcloud login --apikey @fileName -c MyAccountID

If the API key has an associated account, switching to another account isn't supported.

Log in as a specific user with a federated ID:

ibmcloud login --sso

Then, the CLI provides a URL link and prompts you for the passcode:

Get One Time Code from https://identity-1.us-south.iam.cloud.ibm.com/identity/passcode to proceed.
Open the URL in the default browser? [Y/n] >

Open the link in a browser to get a passcode. Enter the passcode in the console to log in.

In addition to using the URL link provided by the CLI, you can start the IBM Cloud console and log in. In the IBM Cloud console, to the Avatar icon > Log in to CLI and API. Copy the IBM Cloud CLI passcode command and enter it. Use this method to log in to your IBMid with your Google account or if you connected your cloud account with an IBM Cloud App ID instance.

Log in as an IBM Kubernetes Service Compute Resource linked to a trusted profile:

ibmcloud login --cr-token token-string --profile trusted_profile_name_id_or_crn

ibmcloud login --cr-token @filename --profile trusted_profile_name_id_or_crn

IBMCLOUD_CR_TOKEN=@filename ibmcloud login --profile trusted_profile_name_id_or_crn

IBMCLOUD_CR_TOKEN=@filename IBMCLOUD_CR_PROFILE=trusted_profile_name_id_or_crn ibmcloud login

For more information about logging in as an IBM Kubernetes Service compute resource, see Logging in with a Compute Resource token.

Log in as a VPC VSI Compute Resource by using the default trusted profile linked during instance provisioning:

ibmcloud login --vpc-cri

Log in as a VPC VSI Compute Resource linked to the specified trusted profile:

ibmcloud login --vpc-cri --profile trusted_profile_id_or_crn

IBMCLOUD_CR_PROFILE=trusted_profile_id_or_crn ibmcloud login --vpc-cri

For more information about logging in as a VPC VSI compute resource, see Logging in as a Virtual Server Instance Compute Resource Identity.

Accept an invitation to join a new account:

ibmcloud login -c TargetedAccountID --accept

ibmcloud logout

Log out of the CLI:

ibmcloud logout

Prerequisites

None.

ibmcloud regions

View the information for all regions on IBM Cloud:

ibmcloud regions

Prerequisites

Use the ibmcloud api command to set an API endpoint.

ibmcloud target

Set or view the target account or region:

ibmcloud target [-r REGION_NAME | --unset-region] [-c ACCOUNT_ID] [-g RESOURCE_GROUP | --unset-resource-group]

Prerequisites

Use the ibmcloud api command to set an API endpoint.
Use the ibmcloud login command to log in. If you are logging in with a federated ID, use the --sso option to authenticate with a one-time passcode, or use the --apikey option to authenticate with an API key.

Command options

-c ACCOUNT_ID: The ID of the target account. Optional.
-r REGION: The name of the target region, for example, us-south or eu-gb. Optional.
-g RESOURCE_GROUP: The name of the target resource group. Optional.
--unset-region: Clear the targeted region.
--unset-resource-group: Clear the targeted resource group.

If none of the options are specified, the current account and region are displayed.

Examples

Set the current account:

ibmcloud target -c MyAccountID

Switch to a new region:

ibmcloud target -r eu-gb

View the current account and region:

ibmcloud target

ibmcloud update

Update the CLI to the most recent version:

ibmcloud update [-f]

Prerequisites

None.

Command options

-f: Force an update without confirmation. Root privilege is required.

General classic infrastructure service commands

Use classic infrastructure commands in the IBM Cloud CLI to configure and manage infrastructure services.

Run the ibmcloud sl command to see the list of available commands:

USAGE:
   ibmcloud sl command [arguments...] [options...]

COMMANDS:
   block           Classic infrastructure Block Storage
   call-api        Call arbitrary API endpoints
   file            Classic infrastructure File Storage
   dns             Classic infrastructure Domain Name System
   globalip        Classic infrastructure Global IP addresses
   hardware        Classic infrastructure hardware servers
   image           Classic infrastructure Compute images
   ipsec           Classic infrastructure IPSEC VPN
   order           Classic infrastructure Orders
   placement-group Classic infrastructure Placement Group
   security        Classic infrastructure SSH Keys and SSL Certificates
   securitygroup   Classic infrastructure network security groups
   subnet          Classic infrastructure Network subnets
   ticket          Classic infrastructure Manage Tickets
   user            Classic infrastructure Manage Users
   vlan            Classic infrastructure Network VLANs
   vs              Classic infrastructure Virtual Servers
   help            Print command usage message

To view help information about a command, run the following command:

ibmcloud sl [command] -h

For detailed information about each command, see the related reference topics in this documentation.

The ibmcloud sl init command is no longer available as of CLI version 0.14. To install the most recent CLI version, see Installing the stand-alone IBM Cloud CLI.

ibmcloud sl help

View help information for all commands to operate the classic infrastructure environment:

ibmcloud sl help