Byteplus Command Line Tools

Overview

1. Byteplus CLI Tool
2. Minimum Go version required: 1.5+, recommended: 1.12+

Installing bp

Get the Client via Release

1. Download the latest version from: https://github.com/byteplus-sdk/byteplus-cli/releases
2. Select the version for your OS, extract and use directly

Build the Client Yourself

1. Use build.sh to compile the client

# For macOS
sh build.sh darwin
# For Windows
sh build.sh windows
# For Linux
sh build.sh linux

Configuring bp

Add bp to your system PATH

1. Check if $PATH includes /usr/local/bin. If not, add it accordingly.
2. Run the following command to copy bp to /usr/local/bin:

sudo cp bp /usr/local/bin

Configure Credentials

To call services, you need AK, SK, and region. You can configure them in two ways:

1. Use bp configure set:

bp configure set --profile test --region cn-beijing --access-key ak --secret-key sk --endpoint endpoint

Supported Parameters:

profile: Configuration name. If it exists, it will be updated; otherwise, a new one will be created.
access-key: Your AK
secret-key: Your SK
region: Region, e.g., cn-beijing
session-token: Required for role-based access
disable-ssl: Whether to disable SSL, default is false
endpoint: Optional; the default value is open.volcengineapi.com. Ignored when endpoint-resolver is standard.
endpoint-resolver: Optional; set to standard (case-insensitive) to use the standard resolver. Otherwise, the CLI uses endpoint when provided.
use-dual-stack: Optional; enable dual-stack endpoints when true. The default value is false.

2. Use Environment Variables:

export BYTEPLUS_ACCESS_KEY=AK
export BYTEPLUS_SECRET_KEY=SK
export BYTEPLUS_REGION=cn-beijing
export BYTEPLUS_DISABLE_SSL=false
export BYTEPLUS_SESSION_TOKEN=sessionToken
export BYTEPLUS_ENDPOINT=endpoint
export BYTEPLUS_ENDPOINT_RESOLVER=standard
export BYTEPLUS_USE_DUALSTACK=true

Other configure Commands

1. bp will prioritize using the credentials in the active profile.
2. After adding or modifying a profile, it becomes the active profile.
3. If multiple profiles exist, switch using:

bp configure profile --profile [profile_name]

View a Specific Profile

bp configure get --profile [profile_name]

If omitted, current profile is shown. If profile doesn't exist, default values are returned.

List All Profiles

bp configure list

Switch Active Profile (>= v1.0.16)

bp configure profile --profile [profile_name]

If profile doesn't exist, the switch fails with an error message.

Add/Modify Profile

bp configure set --profile [name] --region [region] --access-key [AK] --secret-key [SK] --endpoint [endpoint]

Additional Fields:

• access-key
• secret-key
• region
• session-token
• disable-ssl
• endpoint
• endpoint-resolver
• use-dual-stack

Delete Profile

bp configure delete --profile [profile_name]

If the deleted profile is the current one, bp will randomly pick another available profile.

SSO Session Management

Configure SSO Session (configure sso-session)

bp configure sso-session --name [session name] --start-url [SSO Start URL] --region [region] --registration-scopes [scope1,scope2]

This command creates or updates an SSO session for later use with configure sso. Behaviors and parameters:

name: SSO session name; if omitted, enter interactive selection/creation mode
start-url: SSO Start URL; required; if editing an existing session, Enter keeps the default
region: SSO region; required; default is cn-beijing, existing session values are used as defaults
registration-scopes: SSO scope list (comma-separated); allowed values are cloudidentity:account:access, offline_access

Interactive flow notes:

• If no sessions exist, you will be prompted to enter a non-empty session name
• If sessions exist, you get a searchable list with "" to add one
• When editing, Start URL, Region, and Scopes are pre-filled; press Enter to keep defaults
• Scopes are deduplicated and validated; empty input falls back to cloudidentity:account:access, offline_access

Configure SSO Profile (configure sso)

bp configure sso --profile [profile name] --sso-session [session name]

This command configures an SSO profile, links an SSO session, runs the device authorization flow, and writes the profile to ~/.byteplus/config.json. Behaviors and parameters:

profile: profile name; empty uses {sso-role-name}-{sso-account-id} as the default
sso-session: SSO session name; if omitted, enter interactive selection/creation mode
no-browser: Adding the `--no-browser` parameter to the command line disables the browser from opening; omitting it will automatically open the browser by default.

Notes:

• If the profile already exists and is not an SSO profile, the command will refuse to overwrite it
• If the SSO session does not exist, you will be guided to create it and enter Start URL, Region, and Scopes

SSO Login and Logout

SSO Login (sso login)

bp sso login --profile [profile name]
# or
bp sso login --sso-session [session name]

This command performs an explicit SSO login, runs a new authorization flow, obtains an access token, and caches it. Each execution re-authenticates the current SSO session and does not silently exchange an existing refresh_token for an access_token. Parameters:

profile: the SSO profile to use; must exist, be of sso type, and have sso-session configured
sso-session: the SSO session to use; the session must exist and be valid
no-browser: Adding the `--no-browser` parameter to the command line disables the browser from opening; omitting it will automatically open the browser by default.

Login behavior:

• If neither profile nor sso-session is provided: error when no sessions are configured; use the only session if one exists; otherwise enter interactive selection with search
• Only the device code flow is supported; use --no-browser to disable auto-opening the browser
• When running business commands, if the cached SSO access token is expired or close to expiry, the CLI attempts to silently refresh the access token with the cached refresh_token before requesting role credentials
• If the refresh_token is missing, the client registration has expired, or refresh fails, business commands do not automatically open a browser for re-authorization and will ask you to run bp sso login again

SSO Logout (sso logout)

bp sso logout --sso-session [session name]

This command logs out from SSO by revoking the cached token and clearing local credentials. Parameters:

sso-session: the SSO session name to log out

Logout behavior:

• If sso-session is not provided: error when no sessions are configured; logout the only session if one exists; otherwise enter interactive selection that includes "All SSO sessions"
• Batch logout logs out each session and returns aggregated errors on failure

Configure Auto-Completion

Run bp completion --help to check how to enable shell auto-completion.

Bash

1. View bash script: bp completion bash
2. Install bash-completion:

yum install bash-completion
# or
apt-get install bash-completion

3. Enable it:

source /usr/share/bash-completion/bash_completion

Add it to ~/.bashrc for persistence.

4. Configure auto-completion:

echo 'source <(bp completion bash)' >> ~/.bashrc
bp completion bash > /etc/bash_completion.d/bp

Then reload shell or run source ~/.bashrc

Zsh

1. Enable compinit:

echo "autoload -U compinit; compinit" >> ~/.zshrc

2. Configure:

bp completion zsh > "${fpath[1]}/_bp"

Then reload shell or run source ~/.zshrc

Configure Color Output

Enable color:

bp enable-color

Disable color:

bp disable-color

Using bp

List Services and Actions

1. View available services:

bp [-h|--help]

2. View service's supported actions:

bp ecs [-h|--help]

Show CLI version

bp version

bp -v

Calling APIs

Basic structure:

bp <service> <action> [--param1 val1 --param2 val2 ...]

Example:

bp ecs DescribeInstances
bp rds_mysql ListDBInstanceIPLists --InstanceId "xxxxxx"

Support JSON input:

bp rds_mysql ModifyDBInstanceIPList --InstanceId "xxxxxx" --GroupName "xxxxxx" --IPList '["10.20.30.40", "50.60.70.80"]'

Support --body for application/json:

bp rds_mysql ModifyDBInstanceIPList --body '{"InstanceId":"xxxxxx", "GroupName": "xxxxxx", "IPList": ["10.20.30.40", "50.60.70.80"]}'